NAME ---- The CALCOMP Graphics Library User Guide Last Revised 07/01/91 This is documentation for the CALCOMP graphics library. It is complete except for graphics figures and the documentation of a few local enhancements to the library that will not affect general users. Copies of the figures are available as GIF images. The CALCOMP library is a simple set of FORTRAN callable graphic routines that allows users to construct plots. It is principally available for use by purchased software from outside vendors and to ease the conversion process for users migrating CALCOMP code. It is not usually recommended for use in new code. Consult the supplement at the end of this guide for specific guidelines on how to convert existing user and vendor CALCOMP code. 1 TABLE OF CONTENTS Section Title ------- ----- 1.0 INTRODUCTION 2.0 CALCOMP BASIC SOFTWARE 2.1 C_PLOT - Move or Draw to specified point, establish plot origin, update pen position and terminate plotting 2.2 C_PLOTS - Initialization, specify output file unit number 2.3 C_FACTOR - Adjusts the overall size of the plot 2.4 C_WHERE - Returns current pen location 2.5 C_NFRAME - Ends current frame and re-origins pen position 2.6 C_SYMBOL - Plots annotation (text) and special symbols 2.7 C_NUMBER - Plot decimal equivalent of a floating point number 2.8 C_SCALE - Determine starting value and scale for an array to be plotted on a graph 2.9 C_AXIS - Draws an annotated linear graph axis 2.10 C_LINE - Scale and plot a set of X,Y values 2.11 C_NEWPEN - Select new pen color 2.12 Sample Plotting Program 3.0 CALCOMP GENERAL FUNCTIONAL SOFTWARE 3.1 C_CIRCL - Draws a circle, arc, or spiral 3.2 C_ELIPS - Draws an ellipse or elliptical (or circular) arc 3.3 C_DASHL - Draws dashed line connecting a series of data points 3.4 C_DASHP - Draws a dashed line to a specified point 3.5 C_FIT - Draws a curve through three points 3.6 C_GRID - Draws a linear grid 3.7 C_POLY - Draws an equilateral polygon 3.8 C_RECT - Draws a rectangle 4.0 CALCOMP SCIENTIFIC FUNCTIONAL SOFTWARE 4.1 C_CURVX - Draws a function of X over a given range 4.2 C_CURVY - Draws a function of Y over a given range 4.3 C_FLINE - Draws a smooth curve through a set of data points 4.4 C_SMOOT - Draws a smooth curve through sequential data points 4.5 C_SCALG - Performs scaling for logarithmic plotting 4.6 C_LGAXS - Plots an annotated logarithmic axis 4.7 C_LGLIN - Draws data in either log-log or semi-log mode 4.8 C_POLAR - Draws data points using polar coordinates 5.0 APPLICATIONS ROUTINES 5.1 C_CNTOUR - Makes a contour plot 6.0 ACCESSING THE CALCOMP ROUTINES 7.0 CALCOMP CODE MIGRATION SUPPLEMENT 1 RECORD OF REVISIONS (Preliminary release was made 06/24/85 for COS) 07/11/89 Third parameter of C_PLOTS is no longer ignored, but may be used to set the FORTRAN unit number used for output metafile 'pdf'. The routine C_NEWPEN may be used to select color. 07/01/91 The first release of the documentation on UNICOS. Output file goes to default filename "pdf". User may specify the output filename with the environment variable CALCOMP_PDF. 1 1.0 INTRODUCTION This user's guide describes the calling sequences and arguments for the FORTRAN-callable CALCOMP software subroutines which was leased from CALCOMP and interfaced to TEMPLATE. The routines do not produce a device dependent CALCOMP file but rather produce an intermediate, device independent metalanguage file that must be post-processed to a selected graphics device. This metalanguage file is written in the format of a TEMPLATE Pseudo Device File (PDF). CALCOMP divides their routines into three categories: Basic, General Function, and Scientific Function. They are all placed in a single library called libcalcomp.a Differences between the implemented routines and the standard CALCOMP routines are: A. All coordinate values should be greater than or equal to zero, and less than 100 inches. Values outside this range may result in unpredictable results (Negative values are possible if the frame coordinate origin is set first using the C_PLOT call). B. The metalanguage output filename is "pdf", and uses FORTRAN unit 50 unless an appropriate alternate value is specified in the C_PLOTS routine call. The output filename may be specified using the environment variable CALCOMP_PDF. C. A routine C_NFRAME is available for creating multiple frames for graphic devices other than pen plotters. D. Color is supported via the C_NEWPEN routine E. Frames will not plot to true inches unless specific steps are taken in the generation and post-processing of the plot file. Other changes may be needed in existing CALCOMP code from vendors as CALCOMP has produced several versions of CALCOMP routines that vary in such ways as use of CHARACTER variables versus Hollerith, the number of parameters on C_SYMBOL calls, and the current pen position after a call to C_SYMBOL. The CALCOMP subroutines were written for use with CALCOMP pen plotters and originally worked in units of inches for the mapping of the plot directly to the output device. There are two classes of CALCOMP subroutines--those that accept user units and scale them to inches and those that require data to be directly in units of inches. Table 1 lists the CALCOMP subroutines that fall into each class. The main difference CALCOMP users will notice when using this CALCOMP library is that when the CALCOMP subroutines were incorporated into TEMPLATE, the meaning of CALCOMP inches was altered to no longer mean a physical inch but just a unit-less measure (since TEMPLATE uses device-independent space and the graphics post processing procedures produce output for a number of graphics devices, some of which have a limited device space unlike pen plotters). THIS DIFFERENCE IS USUALLY ONLY OF SIGNIFICANCE TO USERS TRYING TO PRODUCE PLOTS USING TRUE INCHES. The graphics post processing procedures use the CALCOMP inches to determine the aspect ratio of the plot, and the plot is made as large as possible for a given device while maintaining the aspect ratio specified by the user CALCOMP calls. A parameter called SIZE is included with most graphics post-processor procedures which facilitates the scaling of plots to a specific size in inches. An example program shows how to use these parameters to get consistent frames in as close as possible to true inches. 1 TABLE 1 Routines Which Routines Which Require Perform Scaling Inches of User Data to Inches (Data Must be Scaled to Inches) ______________________ _______________________________ C_SCALE C_PLOT C_AXIS C_WHERE C_LINE C_SYMBOL C_DASHL C_NUMBER C_FLINE C_CIRCL C_SCALG C_ELIPS C_LGAXS C_DASHP C_LGLIN C_FIT C_POLAR C_GRID C_POLY C_RECT C_CURVX C_CURVY C_SMOOT 1 2.0 CALCOMP BASIC SOFTWARE The routines included in the CALCOMP Basic Software category are C_PLOT, C_PLOTS, C_FACTOR, C_WHERE, C_SYMBOL, C_NUMBER, C_SCALE, C_AXIS, C_LINE and C_NEWPEN . C_NFRAME, an enhancement, is included here because it performs a basic function. 1 Usually when examining existing CALCOMP code you will find it breaks down into two categories - that which produces XY plots and that which does almost everything in its own high-level routines and uses CALCOMP mostly just to draw lines with the C_PLOT command. Therefore you are likely not to need to be familiar with many of the CALCOMP routines described here. The majority of graphic applications are intended to produce an XY-plot. Usually the production of these graphs requires only a combination of the routines C_PLOTS (initialize), C_SCALE, C_AXIS, C_LINE, C_NFRAME and C_PLOT (terminate). Additional text can be added with C_SYMBOL, and options such as frame borders and general line drawing might be added with C_PLOT calls. When plotting requirements cannot be satisfied by using these subroutines, the code often calls the C_PLOT routine almost exclusively ( which basically draws a line or moves the pen directly in units of inches). This is often done by vendors so that it is very easy for them to interface to virtually any graphics library. Two other routines are often found in programs that do not call the higher level routines (such as the axis and contour plot routines): follows: C_FACTOR Adjusts the overall size of a plot. C_WHERE Returns the current pen location. 1 2.1 Subroutine C_PLOT --------------- FUNCTION The C_PLOT subroutine is used to move the pen in a straight line to a new position, with the pen either up or down during the movement. Another function of C_PLOT is to establish a new reference point (origin) for the current plot frame. This must be done if any draws or moves use values which are negative relative to the ORIGINAL frame origin. C_PLOT also is used to terminate CALCOMP plotting, and must be called once and only once at the end of plotting calls in each CALCOMP application. CALLING SEQUENCE: CALL C_PLOT (XPAGE,YPAGE,+-IPEN) where: XPAGE, YPAGE are the X, Y coordinates in CALCOMP inches. The values are measured relative to the current frame reference (origin). An origin (where both X, Y equal zero) may be established anywhere on the plotting surface by using negative IPEN values, as explained below. Because CALCOMP routines are interfaced to write a TEMPLATE PDF, some limits on X and Y coordinates were required. All coordinate values (XPAGE, YPAGE) should be greater than or equal to zero and less than 100 inches. If negative values are necessary a new frame origin must be set so the negative values are positive relative to the ORIGINAL frame origin. 0 < XPAGE+origin x-offset < 100 0 < YPAGE+origin y-offset < 100 The values of XPAGE and YPAGE which are used to establish a new origin must also be considered. See the discussion under subroutine C_NFRAME for details. +-IPEN is a signed integer which controls pen status (up or down), and the origin definition. If IPEN=2, the pen is down during movement, thus drawing a visible line. If IPEN=3, the pen is up during movement. If IPEN= -2, or -3, a new origin is defined at (XPAGE,YPAGE) after the movement is completed as if IPEN were positive. That is, the X,Y coordinates of the new pen position are set equal to zero. This position is the reference point for succeeding pen movements. If IPEN=999 the metalanguage file is closed. (Note this must be the last call made by the plotting application). 1 2.2 Subroutine C_PLOTS ---------------- FUNCTION: Subroutine C_PLOTS is used to initialize the CALCOMP package. It must be called once and only once before any other CALCOMP calls are used in the application program. C_PLOTS also is used to specify which FORTRAN unit number will be used by the output metalanguage file. Note that calling C_PLOTS produces a logfile message indicating the CALCOMP source code version number and the CFT level used when building the library. CALLING SEQUENCE: CALL C_PLOTS (O,O,LDEV) where: LDEV is the FORTRAN unit number for the metalanguage file. If LDEV is not in the range of 1 to 99 inclusive, then FORTRAN unit 50 is used. The FORTRAN unit used for the output file cannot be used for any other purposes within the application program (Avoid units 1,2,5 and 6 which are often associated with standard input and output). The output metafile default name is 'pdf'. It may be specified through the environment variable CALCOMP_PDF. The first two arguments of C_PLOTS are no longer used, but are maintained for compatibility with previous versions of the CALCOMP software package. ** NOTE : In versions before the library for CFT11531, LDEV was ignored and unit 50 was always used; and no logfile message was produced. 1 2.3 Subroutine C_FACTOR ----------------- FUNCTION: Subroutine C_FACTOR enables the user to enlarge or reduce the size of the entire plot by changing the ratio of the desired plot size to the normal plot size. C_FACTOR is often called only once in a program, immediately after the initialization call to C_PLOTS, to rescale all plotting to a single specific scale. Because CALCOMP inches are unit-less units in PDF files, this routine is not necessary unless inch units greater than 100 are needed (100 is maximum PDF frame size) or if the program needs to remain portable to standard true-inch CALCOMP libraries and using the actual values used in the C_PLOT calls would produce a very small or very large plot. USERS TRYING TO PRODUCE TRUE INCHES PLEASE NOTE: In this CALCOMP, all frames are scaled individually to the maximum size obtainable on the output device they are produced on. This means to keep frames scaled relative to each other, you must move to the same maximum XY value IN EACH FRAME (see routine C_NFRAME description) with a call to C_PLOTS so that each frame is the same number of unit-less units in size. An example program at the end of this manual illustrates keeping frames scaled relative to each other. CALLING SEQUENCE: CALL C_FACTOR (FACT) where: FACT is the ratio of the desired plot size to the normal plot size. For example, if FACT=2.0, all subsequent pen movements will be twice their normal size. When FACT is reset to 1.0, all plotting returns to normal size. During the debugging of a plotting application program, plotting time can be saved by reducing the size of the entire plot output on certain devices such as pen plotters. This is done by calling C_FACTOR with a value less than 1.0 after calling C_PLOTS. When debugging is completed, this call statement can be removed. 1 2.4 Subroutine C_WHERE ---------------- FUNCTION: Subroutine C_WHERE returns the current position coordinates (that are in use by the C_PLOT subroutine) and the plot-scaling factor. This permits user-written subroutines to know the current location for optimizing pen movement or for determining coordinates for future calls. CALLING SEQUENCE: CALL C_WHERE (RXPAGE,RYPAGE,RFACT) where: RXPAGE, RYPAGE are variables that will be set to the current position coordinates resulting from the previous call to C_PLOT (which may have been called internally by C_SYMBOL, C_NUMBER, C_AXIS, C_LINE or most other CALCOMP routines). RFACT is set to the current plot-sizing factor, i.e., the value last supplied by a call to C_FACTOR or 1.0 if C_FACTOR has not been called. A call to C_WHERE made after a call to C_SYMBOL returns the coordinates of the location of the last point actually plotted. Please note that different versions of CALCOMP may return different values to this routine. For example, CALCOMP has produced CALCOMP libraries that will return the following to C_WHERE after a call to C_SYMBOL has been made: a) The beginning coordinate of the string produced by C_SYMBOL b) The end point of the string produced c) The position where the next character will be drawn if C_SYMBOL is called with the 999 value flags (as described in the C_SYMBOL routine description). 1 2.5 Subroutine C_NFRAME ----------------- FUNCTION: Terminates the current frame and resets the current pen position and origin to zero (The lower left-hand corner of the new frame). C_NFRAME is a locally-developed routine. Subroutine C_NFRAME allows users to define the logical beginning and ending of a plot. This capability is necessary if plots are to be drawn on a graphics device with a limited display area (e.g., a graphics terminal or microfiche/ film). A call to C_NFRAME enters a plot terminator in the user's metalanguage file. All plotting data generated between calls to C_NFRAME is treated as a single plot by the graphics post processing procedures. The absence of calls to C_NFRAME results in all plotting data being processed as a single plot by the post processor (e.g., all plotting data will be drawn in a single frame on microfiche). The call to C_NFRAME should be placed before the call to subroutine C_PLOT that is used to move the pen to the origin of the next plot. Be aware that the area encompassed by moving the pen to establish the origin of a plot is considered part of the plot and will produce a visible bottom and left margin on plot frames if no negative values are subsequently used. As mentioned previously, a plot frame is limited to a maximum size in either the X or Y direction of 100 "CALCOMP inches." Each plot frame is initialized by a call to subroutine C_PLOT with the third argument (IPEN) equal to -2 or -3. For example: CALL C_PLOT (0.5,1.0,-3) says to move 0.5 inches in the X-direction and 1.0 inch in the Y-direction before establishing a new origin. When establishing a new origin, all offsets are included inside the frame boundary and are therefore part of the plot frame size. If any X or Y coordinate value (plus the appropriate offset) exceeds the 100 inch limit, results are unpredictable. In programs where X and Y coordinate values exceed the scaling limit, a call to the CALCOMP routine C_FACTOR may be used to scale down the plot size appropriately. No additional offset is added by the call to C_NFRAME. Knowledge of the plot frame size in the X and Y directions will be needed to scale pen plots to actual inches with the device dependent post processing procedures. The following example is provided to assist in understanding how the frame size is determined. PROGRAM CALTEST C Perform initialization CALL C_PLOTS(0,0,0) C Establish origin for first plot (Negative Y values up to -0.5 are C now permitted also) CALL C_PLOT (0.0,0.5,-3) C Draw a box inside of which all lines will appear C but notice plot frame size now includes the offset plus this box size C Plot frame size = maximum coordinate value used + offset C Plot frame size in the X-direction is 8 inches C Plot frame size in the Y-direction is 9.5 inches (0.5 offset in C_PLOT C call above! CALL C_PLOT (8.,0.,2) CALL C_PLOT (8.,9.,2) CALL C_PLOT (0.,9.,2) CALL C_PLOT (0.,0.,2) C Calls to generate first plot go here C . C . C . C Terminate first plot CALL C_NFRAME C Establish origin for second plot CALL C_PLOT (1.0,2.0,-3) C Plot frame size in the X-direction is 6 inches C Plot frame size in the Y-direction is 6 inches CALL C_PLOT (5.0,0.0,2) CALL C_PLOT (5.0,4.0,2) CALL C_PLOT (0.0,4.0,2) CALL C_PLOT (0.0,0.0,2) C Calls to generate second plot go here C . C . C . C Close the plot file CALL C_PLOT (0.0,0.0,999) END An inch drawn in frame 1 will not appear equal in length to an inch drawn in frame 2 because their unit-less frame sizes are not equal ( 8.5 x 9 versus 6 x 6 ) ! The size of each frame is determined by the maximum value reached in each frame relative to the ORIGINAL frame origin. Each frame, when plotted, is stretched without distortion to the maximum size it can obtain in the plotting area specified on post-processor calls (Usually the SIZE, and XI and YI parameters as described in the DOCLIB document GRPHDOC). CALLING SEQUENCE: CALL C_NFRAME 1 2.6 Subroutine C_SYMBOL ----------------- FUNCTION: The C_SYMBOL subroutine produces plot annotation at any angle and in practically any size. There are two C_SYMBOL call formats: 1) the "standard" call, which can be used to draw text such as titles, captions, and legends. 2) the "special" call, which is used to draw special centered symbols such as a box, octagon, triangle, etc., for denoting data points. Both forms of the C_SYMBOL calling sequence have seven arguments. Which form is being used is determined by the value of the NCHAR parameter. The standard characters that are drawn by C_SYMBOL include the letters A-Z, digits 0-9, and certain special characters. See Table 2 for a description of CALCOMP's symbol table. The parameter NCHAR is used to specify whether a text string or a single symbol is being plotted. If NCHAR is >= 0, the text string in IBCD is used. If NCHAR= -1 or -2, a single symbol is produced using the value of INTEQ (Which MUST then be between 0 and 90, inclusive). It is recommended that 999 be used for INTEQ when NCHAR is greater than or equal to zero, and either a dummy character variable (e.g. CHARACTER*1 DUMMY) or a literal character string (e.g. ' ') be used for IBCD when NCHAR is less than zero (not just a plain word as a dummy variable)! CALLING SEQUENCE: The "standard" call which produces a line of text is: CALL C_SYMBOL (XPAGE,YPAGE,HEIGHT,IBCD,INTEQ,ANGLE,+NCHAR) where: XPAGE, YPAGE are the coordinates, in inches, of the lower left-hand corner (before character rotation) of the first character to be produced. The pen is up while moving to this point. Annotation may be continued from the position following that at which the last annotation ended. Continuation occurs when XPAGE and/or YPAGE equals 999.0, and may be applied to X or Y independently. (Calling C_WHERE to obtain the current pen position and using RXPAGE, RYPAGE in another call to C_SYMBOL would not give the same results as using 999.) HEIGHT is the height, in inches, of the character(s) to be plotted. For best results, it should be a multiple of seven times the standard CALCOMP increment size of 0.01 (e.g., 0.07, 0.14, 0.21), but other values are acceptable. The width of a character, including spacing, is normally the same as the height (e.g., a string of 10 characters 0.14 inch high is 1.4 inches wide). IBCD is the text to be used as annotation. The character(s) must be in a character array or single variable. (The data should be stored as TYPE CHARACTER.) INTEQ Ignored (Assuming NCHAR is positive!) ANGLE is the angle, in degrees from the X axis, at which the annotation is to be plotted. If ANGLE=0.0, the character(s) will be plotted right side up and parallel to the X axis. The absolute magnitude of ANGLE can not exceed 1800 degrees. +NCHAR is the number of characters to be plotted from IBCD. If NCHAR=0, one alphanumeric character is produced, using a single character which is the first element of IBCD. For example, the following call to C_SYMBOL will result in the characters TITLE 10 being output beginning at the X and Y coordinates of 1.0. CHARACTER GRLBL*8 GRLBL='TITLE 10' CALL C_SYMBOL (1.0,1.0,0.14,GRLBL,999,0.0,8) A second form is the "special" call, which produces only a single symbol based on the value of INTEQ - not on the ASCII representation of a character. The "special" call is: CALL C_SYMBOL (XPAGE,YPAGE,HEIGHT,IBCD,INTEQ,ANGLE,-NCHAR) where: XPAGE, YPAGE, are the same as described for the "standard" call. If and ANGLE the symbol to be produced is one of the centered symbols (e.g., if INTEQ is less than 14), XPAGE, YPAGE represent the geometric center of the character produced. HEIGHT is the height (and width), in inches, of the centered symbol to be drawn. Preferably, it should be a multiple of four times the CALCOMP 0.01 increment size. IBCD Ignored (assuming NCHAR is negative!) INTEQ is the integer equivalent of the desired symbol. Valid integers and their symbols are listed in the Symbol Table (Table 2). If INTEQ is 0 through 14, a centered symbol is produced. INTEQ -MUST- be greater than or equal to zero and less than or equal to 90. NCHAR is negative and determines whether the pen is up or down during the move to XPAGE, YPAGE. When NCHAR is: -1, the pen is up during the move, after which a single symbol is produced. -2, or less, the pen is down during the move, after which a single symbol is produced. For example, the following call to C_SYMBOL will result in special symbol number 5 being output with its center at X and Y coordinates of 1.0. CALL C_SYMBOL (1.0,1.0,0.16,' ',5,0.0,-1) Table 2 shows the current symbols available and the integer equivalents for each symbol which are used in the "special" call. When a "standard" call to C_SYMBOL is made, the host computer's internal characters are translated to the appropriate characters from this table. 1 2.7 Subroutine C_NUMBER ----------------- FUNCTION: Subroutine C_NUMBER plots a floating-point number; using the specified number of decimals in the mantissa (Using FORTRAN F-type format). The routine is very similar to C_SYMBOL, with the exception that a numeric value, not a string, is to be plotted. CALLING SEQUENCE: CALL C_NUMBER (XPAGE,YPAGE,HEIGHT,FPN,ANGLE,+-NDEC) where: XPAGE,YPAGE, are the same as those arguments described for subroutine HEIGHT,ANGLE C_SYMBOL. The continuation feature, where XPAGE or YPAGE equals 999.0, may be used. FPN is the floating-point number that is to be converted and plotted. +-NDEC controls the precision of the conversion of the number FPN. If the value of NDEC>0, it specifies the number of digits to the right of the decimal point that are to be converted and plotted, after proper rounding. For example, assume an internal value of - 0.12345678 x 10**3. If NDEC were 2, the plotted number would be -123.46. If NDEC=0, only the number's integer portion and a decimal point are plotted, after rounding. If NDEC=-1, only the number's integer portion is plotted, after rounding. (The above example would be plotted as -123 with no decimal point). If NDEC < -1, ABS (NDEC) -1 digits are truncated from the integer portion, after rounding. The magnitude of NDEC should not exceed 9. 1 2.8 Subroutine C_SCALE ---------------- FUNCTION: Calculate scaling factors and a starting value for an array of X or Y values for use in producing XY plots with the C_LINE and C_AXIS routines, for example. Typically, the user's program will accumulate plotting data in two arrays: o An array of independent variables, X(i) o An array of dependent variables, Y(i)=f(X(i)) Typically these values should not be drawn directly in units of inches, but should be rescaled (A temperature of 3000 should not require the generation of a 3000 inch plot!). For some problems the range of data is predictable. The programmer can predetermine suitable conversion factors for use in drawing the axis scale values and plot the data points on the graph directly in units of inches using the C_PLOT routine. Usually, however, these factors are not known in advance. Therefore, the C_SCALE subroutine can examine the data values in an array and determine a starting value (minimum or maximum) and a scaling factor (positive or negative) such that: 1) The scale numbers drawn by the C_AXIS subroutine at each division will properly represent the range of real data values in the array. 2) The data points, when plotted by the C_LINE subroutine, will fit in a given plotting area (Generally the bounds of the plot axis drawn with C_AXIS). These values are computed and stored by C_SCALE at the END OF THE INPUT VALUE ARRAY. The computed scaling factor (DELTAV) represents the number of data units per inch of axis, adjusting DELTAV so that it is always an interval of 1, 2, 4, 5, or 8 x 10**n (where n is an exponent consistent with the original unadjusted scaling factor). Thus, an array may have a range of values from 301 to 912, to be plotted over an axis of 10 inches. The unadjusted scaling factor is (912-301)/10=61.1 units/inch. The adjusted DELTAV would be 8 x 10**1 = 80. This will allow the production of 'nice' axes, that start and end on rounded units and are divided into increments people can easily interpolate between. The starting value (FIRSTV) is intended to be used as the first numeric label on the axis, is computed as a multiple of DELTAV that is equal to or outside the limits of the data in the array. For the example given above, if a minimum is wanted for FIRSTV, 240 would be chosen as the best value. If a maximum is desired instead, 960 would be selected (The nearest multiple of 80=DELTAV that is below or above the minimum and maximum data values 301 and 912). CALLING SEQUENCE: CALL C_SCALE (ARRAY,AXLEN,NPTS,+-INC) where: ARRAY is the first element of the array of data points to be examined. AXLEN is the length of the axis, in inches, to which the data is to be scaled. Its value must be greater than 1.0 inch, and less than 100 inches. NPTS is the number of data values to be scanned in the array. The FORTRAN DIMENSION statement must specify at least two elements more than the number of values being scaled, to allow room for C_SCALE to store the computed starting value and scaling factor at the end of the array. +-INC is an integer whose magnitude is used by C_SCALE as the increment with which to select the data values to be scaled in the array. Normally INC=1; if it is 2, every other value is examined. If INC is positive, the selected starting value (FIRSTV) approximates a minimum, and the scale factor (DELTAV) is positive. If INC is negative, the selected starting value (FIRSTV) approximates a maximum, and the scaling factor (DELTAV) is negative. WARNING: If INC= +-1, the array must be dimensioned at least two elements larger than the actual number of data values it contains. If the magnitude of INC > 1, the computed values are stored at (INC) elements and (2*INC) elements beyond the last data point. The subscripted element for FIRSTV is ARRAY(NPTS*INC+1); for DELTAV it is ARRAY (NPTS*INC+INC+1). Therefore, ARRAY must always be dimensioned at least NPTS*INC+INC+1. Generally, C_SCALE is called to examine each array to be plotted. If the user knows the range of his data values, he does not have to call C_SCALE for that array so long as he supplies an appropriate FIRSTV and DELTAV when C_AXIS and C_LINE are called. 1 2.9 Subroutine C_AXIS --------------- FUNCTION: Draws a linear axis with numeric scale and axis label. Important: Axis labels can be 0.4 inches lower than or to the left of the axis origin (XPAGE,YPAGE). Since lines drawn whose value is negative relative to the frame's ORIGINAL origin will be clipped, XPAGE and YPAGE must be greater than 0.4 or a new origin must be specified at least 0.4 units up and to the right from the original using C_PLOT(0.4,.4,-3) when (XPAGE,YPAGE) is (0.,0.). Most graphs require axis lines and scales to indicate the orientation and values of the plotted data points. The most common type of scaled axis is produced by the C_AXIS subroutine which draws any length line at any angle, divides the line into one-inch segments, annotates the divisions with appropriate scale values and labels the axis with a centered title. When both the X and Y axes are needed, C_AXIS is called separately for each one. CALLING SEQUENCE: CALL C_AXIS(XPAGE,YPAGE,IBCD,+-NCHAR,AXLEN,ANGLE,FIRSTV,DELTAV) where: XPAGE,YPAGE are the coordinates, in inches, of the axis line's starting point. The entire line should be at least one-half inch from any side to allow space for the scale annotation and axis title. Usually, both the X and Y axes are joined at the origin of the graph, where XPAGE and YPAGE equal zero, but other starting points can be used. When using the C_LINE subroutine to plot data on an axis, at least one of the coordinates must be 0, i.e., for an X axis, XPAGE=0, and for a Y axis, YPAGE=0. IBCD is the title, which is centered and placed parallel to the axis line. This parameter may be a character array or single variable. (The data should be stored as TYPE CHARACTER.) The characters have a fixed height of 0.14 inch (about seven characters per inch). +-NCHAR The magnitude specifies the number of characters in the axis title, and the sign determines on which side of the line the scale (tick) marks and labeling information shall be placed. Since the axis line may be drawn at any angle, the line itself is used as a reference. If the sign is positive, all annotation appears on the positive (counterclockwise) side of the axis. This condition is normally desired for the Y axis. If the sign is negative, all annotation appears on the negative (clockwise) side of the axis. This condition is normally desired for the X axis. AXLEN is the length of the axis line, in inches. ANGLE is the angle in degrees (positive or negative), at which the axis is drawn. The value is 0 degrees for the X-axis and 90 degrees for the Y-axis. FIRSTV is the starting value (either minimum or maximum) which will appear at the first tick mark on the axis. This value may either be computed by the C_SCALE subroutine and stored at subscripted location ARRAY(NPTS*INC+1), or the value may be determined by the user and stored at any location. This number and scale value along the axis is drawn with two decimal places. Since the digit size is 0.105 inch (about 10 characters per inch), and since a scale value appears every inch, no more than six digits and a sign should appear to the left of the decimal point. DELTAV represents the number of data units per inch of axis. This value (increment or decrement), which is added to FIRSTV for each succeeding one-inch division along the axis, may either be computed by C_SCALE and stored beyond FIRSTV at ARRAY(NPTS*INC+INC+1), or the value may be determined by the user and stored at any location. In order to use a standard format of two decimal places, the size of DELTAV is adjusted to less than 100, but not less than 0.01. As a result, the decimal point may be shifted left or right in the scale values as drawn, and the axis title is then followed by "*10**n", where n is the power-of-ten adjustment factor. (See X-axis example in Figure _____.) 1 2.10 Subroutine C_LINE --------------- FUNCTION: Plots a series of XY points with optional rescaling. The C_LINE subroutine produces a line plot of the pairs of data values in two arrays (XARRAY and YARRAY). C_LINE computes the page coordinates of each plotted point according to the data values in each array and the respective scaling parameters. The data points may be represented by centered symbols and/or connecting lines between points. The scaling parameters corresponding to FIRSTV and DELTAV (see C_SCALE) must immediately follow each array. If these parameters have not been computed by the C_SCALE subroutine they must be supplied by the user. If scaling is not required, the user must place the appropriate minimum and delta values in the specified elements of the arrays. For a one-to-one correspondence between array data and plotted data, these values should be 0.0 (minimum) and 1.0 (delta). CALLING SEQUENCE: CALL C_LINE (XARRAY,YARRAY,NPTS,INC,+-LINTYP,INTEQ) where: XARRAY is the name of the array containing the abscissa (X) values and the scaling parameters for the X array. YARRAY is the name of the array containing the ordinate (Y) values and the scaling parameters for the Y array. NPTS is the number of data points to be plotted in each of the two arrays just mentioned. The number does not include the extra two locations for the scaling parameters. The number of points in each array must be the same. INC is the increment that the C_LINE subroutine is to use in gathering data from the two arrays, as described previously for the C_SCALE subroutine. XARRAY and YARRAY must be dimensioned NPTS*INC+INC+1. +-LINTYP is a control parameter which describes the type of line to be drawn through the data points. The magnitude of LINTYP determines the frequency of plotted symbols. If LINTYP is zero, the points are connected by straight lines but no symbols are plotted. If LINTYP=1, a line plot with a symbol at each data point is produced. If LINTYP=n, a line plot connects every data point defined in the array; a symbol is drawn at every nth data point. (The pen is up when moving from its current position to the first point.) For example, if LINTYP=4, a special symbol (denoted by INTEQ) is plotted at every fourth data point. If LINTYP=-n, no connecting lines are drawn; only the symbols are plotted, at every nth data point. INTEQ is the integer equivalent of the special plotting symbol centered at each data point. This value normally can be 0 through 14 (see Table 2), and has meaning only when LINTYP is not zero. Some of these symbols are as follows: box, octagon, triangle, plus, X, diamond, and asterisk. 1 2.10 Subroutine C_NEWPEN ----------------- FUNCTION Select a new pen color. The number of colors available depends on the output device used, but on almost all color devices the following values will produce the associated colors: 0 -black 1 -red 2 -green 3 -yellow 4 -purple 5 -magenta 6 -cyan 7 -white (the default) CALLING SEQUENCE ** CALL C_NEWPEN(ICOLOR) ** This routine only produces color when CFT levels of 11531 or above are used. Before this, this routine forced the pen back to the frame origin and had no other affect. 1 2.12 A Sample Plotting Program ------------------------- To illustrate the use of the CALCOMP routines, a sample program is provided which will produce the graph shown in Figure ____. The only assumption made is that the 24 pairs of TIME and VOLTAGE data values are contained in a file of 24 records. PROGRAM SAMPLE Metalanguage output file is "pdf". DIMENSION XARRAY(26),YARRAY(26) Reserve space for 24 data values plus two additional locations required by the C_SCALE, C_AXIS, and C_LINE subroutines. 10 CALL C_PLOTS (0,0,0) Perform initialization. 20 READ (5,25)(XARRAY(I),YARRAY(I),I=1,24) 25 FORMAT(2F6.2) Read 24 pairs of TIME and VOLTAGE from an input file into two arrays with names XARRAY and YARRAY. 30 CALL C_PLOT(0.0,0.5,-3) Establish a new origin one-half inch higher than the point where the pen was initially placed so that the annotation of the TIME axis will fit between the axis and the edge of the plotting surface. 40 CALL C_SCALE (XARRAY,5.0,24,1) Compute scale factors for use in plotting the TIME values within a five-inch plotting area. 50 CALL C_SCALE(YARRAY,6.0,24,1) Compute scale factors for use in plotting the VOLTAGE data values within a six-inch plotting area (i.e., the data pairs of TIME, VOLTAGE will plot within a five-by-six inch area). 60 CALL C_AXIS(0.0,0.0,'TIME IN MILLISECONDS',-20,5.0,0.0,XARRAY(25), XARRAY(26)) Draw the TIME axis (5 inches long), using the scale factors computed in statement 40 to determine the milliseconds at each inch along the TIME axis. 70 CALL C_AXIS(0.0,0.0,'VOLTAGE',7,6.0,90.0,YARRAY(25),YARRAY(26)) Draw the VOLTAGE axis (6 inches long) using the scale factors computed in statement 50 to determine the voltage at each inch along the VOLTAGE axis. 80 CALL C_LINE(XARRAY,YARRAY,24,1,2,4) Plot VOLTAGE vs TIME, drawing a line between each of the 24 scaled points and a symbol X at every other point. 90 CALL C_SYMBOL(0.5,5.6,0.21,'PERFORMANCE TEST',INTEQ,0.0,16) Plot the first line of the graph title. 100 CALL C_SYMBOL(0.5,5.2,0.14,'REF. NO. 1623-46',INTEQ,0.0,16) Plot the second line of the graph title. 110 CALL C_NFRAME Terminate the plot. 120 CALL C_PLOT(0.0,00.0,999) Close the plot file. 130 CALL EXIT Terminate Program execution. 1 3.0 CALCOMP GENERAL FUNCTIONAL SOFTWARE The routines included in the CALCOMP General Functional software category are C_CIRCL, C_DASHL, C_DASHP, C_ELIPS, C_FIT, C_GRID, C_POLY and C_RECT. These routines call the Basic routines and should be viewed as an extension of the Basic library rather than as a separate entity. 1 3.1 Subroutine C_CIRCL ---------------- GENERAL DESCRIPTION: C_CIRCL is a FORTRAN subroutine that draws, starting at a given point, an arc which may be extended to form a circle or spiral. CALLING SEQUENCE: CALL CIRCLE (XPAGE,YPAGE,THO,THF,RO,RF,DI) where: XPAGE,YPAGE are the coordinates in inches, of the arc's starting point. THO is the radius angle, in degrees from the X-axis, for the start of the arc. THF is the radius angle, in degrees from the X-axis, for the end of the arc. RO is the arc's starting radius, in inches. RF is the arc's ending radius, in inches. DI is a code used to specify the type of line desired. If DI = 0.0, a solid arc is drawn; 0.5, a dashed arc is drawn. COMMENTS: THO and THF may be positive or negative. If THO is less than THF, the arc is drawn in a counterclockwise direction; and if THO is greater than THF, the arc is drawn in a clockwise direction. 1 3.2 Subroutine C_ELIPS ---------------- GENERAL DESCRIPTION: C_ELIPS is a FORTRAN subroutine which draws an ellipse or elliptical arc. CALLING SEQUENCE: CALL C_ELIPS (XPAGE,YPAGE,RMAJ,RMIN,ANGLE,THO,THF,IPEN) where: XPAGE,YPAGE are the coordinates, in inches, of the starting point of the ellipse or arc. RMAJ,RMIN are the lengths, in inches, of the semi-major and semi-minor axes, respectively. ANGLE is the angle of the major axis, in degrees. THO,THF are the angles, in degrees with respect to ANGLE, of the arc's starting and ending points. IPEN is the code that moves the pen to the arc's starting point. If the value of IPEN is: 3, the pen is up for the move; 2, the pen is down for the move. COMMENTS: THO and THF may be positive or negative. If THO is less than THF, the arc is drawn in a counterclockwise direction; if THO is greater than THF, the arc is drawn in a clockwise direction. 1 3.3 Subroutine C_DASHL ---------------- GENERAL DESCRIPTION: C_DASHL is a FORTRAN subroutine which draws dashed lines connecting a series of data points. Its operation is similar to that of the C_LINE subroutine. CALLING SEQUENCE: CALL C_DASHL (XARRAY,YARRAY,NPTS,INC) where: XARRAY is the name of the array containing the X values of the data points to be plotted and the scaling parameters for the X array. YARRAY is the name of the array containing the Y values of the data points to be plotted and the scaling parameters for the Y array. NPTS is the quantity of data points to be plotted. INC is the increment between array elements to be plotted. INC is greater than 1 if the values to be plotted are in a mixed or multi-dimensioned array. (Normally INC = 1). COMMENTS: The arrays must be dimensioned with at least NPTS + 2 elements. The adjusted minimum value (FIRSTV) and the adjusted delta value (DELTAV), normally provided by the C_SCALE subroutine, must be stored following the data array. For the X array, the adjusted minimum is stored in XARRAY (NPTS*INC + 1), and the adjusted delta is in XARRAY (NPTS*INC + INC + 1). Similarly, for the Y array, the minimum is in YARRAY (NPTS*INC + 1), and the delta is in YARRAY (NPTS*INC + INC + 1). Therefore, XARRAY and YARRAY must be dimensioned to be at least NPTS*INC+INC+1. If scaling is not required, the user must place the appropriate minimum and delta values in the specified elements of the arrays. For a one-to-one correspondence between array data and plotted data, these values should be 0.0 (minimum) and 1.0 (delta). A dashed line, with dashes approximately 0.1 inch long, is drawn connecting sequential points. Coding is optimized so that plotting may either begin at the first point and progress forward or begin at the last point and progress backward. 1 3.4 Subroutine C_DASHP ---------------- GENERAL DESCRIPTION: C_DASHP is a FORTRAN subroutine which draws a dashed line from the pen's present position to a specified point. CALLING SEQUENCE: CALL C_DASHP (XPAGE,YPAGE,DASH) where: XPAGE,YPAGE are the coordinates, in inches, of the point to which the dashed line is to be drawn. DASH is the length, in inches, of each dash and of the space between dashes. COMMENTS: If the line length is less than double the dash length, the dash length is adjusted to half the line length. 1 3.5 Subroutine C_FIT -------------- GENERAL DESCRIPTION: C_FIT is a FORTRAN subroutine which draws a semi-hyperbolic curve through three points. CALLING SEQUENCE: CALL C_FIT (XPAGE1,YPAGE1,XPAGE2,YPAGE2,XPAGE3,YPAGE3) where: XPAGE1,YPAGE1 are the X and Y coordinates, in inches, of the three XPAGE2,YPAGE2 points through which the curve passes. XPAGE3,YPAGE3 COMMENTS: This subroutine generates a semi-hyperbolic fit using the three given points. A set of points for which a fit is not possible is drawn with straight-line segments. RESTRICTIONS: The curve through the three points must be multi-valued in both X and Y. That is, the middle point (XPAGE2,YPAGE2) must be between the endpoints along the X-axis or the Y-axis. XPAGE1XPAGE2>XPAGE3 or YPAGE1YPAGE2>YPAGE3 1 3.6 Subroutine C_GRID --------------- GENERAL DESCRIPTION: C_GRID is a FORTRAN subroutine which draws a linear grid. CALLING SEQUENCE: CALL C_GRID (XPAGE,YPAGE,DELTAX,DELTAY,NXSP,NYSP) where: XPAGE,YPAGE are the coordinates, in inches, of the grid's lower left corner. DELTAX is the number of inches between grid lines in the X direction. DELTAY is the number of inches between grid lines in the Y direction. NXSP,NYSP are the number of grid intervals in the X and Y directions, respectively. The number of grid lines is one more than the number of grid intervals. COMMENTS: C_GRID generates a linear grid of any size. The number of lines drawn is NXSP\+\1 in the X direction and NYSP + 1 in the Y direction. 1 3.7 Subroutine C_POLY --------------- GENERAL DESCRIPTION: C_POLY is a FORTRAN subroutine used to draw equilateral polygons. CALLING SEQUENCE: CALL C_POLY (XPAGE,YPAGE,SLEN,SN,ANGLE) where: XPAGE,YPAGE are the coordinates, in inches, of the polygon's starting point. SLEN is the length, in inches, of a side of the polygon. SN is the number of sides of the polygon. ANGLE is the angle, in degrees, of the first side of the polygon. COMMENTS: If SN is negative, a star is drawn with SN points. 1 3.8 Subroutine C_RECT --------------- GENERAL DESCRIPTION: C_RECT is a FORTRAN subroutine used to draw rectangles. CALLING SEQUENCE: CALL C_RECT (XPAGE,YPAGE,HEIGHT,WIDTH,ANGLE,IPEN) where: XPAGE,YPAGE are the coordinates, in inches, of the rectangle's lower left corner, before rotation. HEIGHT is the rectangle's height, in inches. WIDTH is the rectangle's width, in inches. (This parameter defines the base of the rectangle.) ANGLE is the angle, in degrees, at which the rectangle's base is to be drawn. (Rectangle is rotated about XPAGE,YPAGE.) IPEN is the code that moves the pen to the rectangle's starting point. If the value of IPEN is: 3, the pen is up for the move; 2, the pen is down for the move. 1 4.0 CALCOMP SCIENTIFIC FUNCTIONAL SOFTWARE The routines included in the CALCOMP Scientific Functional software category are C_CURVX, C_CURVY, C_FLINE, C_LGAXS, C_LGLIN, C_POLAR, C_SCALG, and C_SMOOT. These routines call the Basic routines and should be viewed as an extension of the Basic library. 1 4.1 Subroutine C_CURVX ---------------- GENERAL DESCRIPTION: C_CURVX is a FORTRAN subroutine which plots a function of X over a given range. CALLING SEQUENCE: CALL C_CURVX (XO,XF,COEFF1,EXP1,COEFF2,EXP2,COEFF3,EXP3,COEFF4,EXP4) where: XO,XF are the starting and ending values of X. (These are assumed to be inches.) COEFF1,COEFF2, are the coefficients of the polynomial that defines COEFF3,COEFF4 the function to be plotted. EXP1,EXP2, are the exponents of the polynomial that defines EXP3,EXP4 the function to be plotted. COMMENTS: The polynomial that defines the function to be plotted is: Y=COEFF1*X**EXP1+COEFF2*X**EXP2+COEFF3*X**EXP3+COEFF4*X**EXP4 for values of X from XO to XF, where deltaX=0.01. Since values of X are assumed to be inches, any scaling required must be performed before calling this subroutine. Errors may be generated if X is zero or negative. 1 4.2 Subroutine C_CURVY ---------------- GENERAL DESCRIPTION: C_CURVY is a FORTRAN subroutine which plots a function of Y over a given range. CALLING SEQUENCE: Call C_CURVY(YO,YF,COEFF1,EXP1,COEFF2,EXP2,COEFF3,EXP3,COEFF4,EXP4) where: YO,YF are the starting and ending values of Y. (These are assumed to be inches.) COEFF1,COEFF2, are the coefficients of the polynomial that COEFF3,COEFF4 defines the function to be plotted. EXP1,EXP2 are the exponents of the polynomial that defines EXP3,EXP4 the function to be plotted. COMMENTS: The polynomial that defines the function to be plotted is: X=COEFF1*Y**EXP1+COEFF2*Y**EXP2+COEFF3*Y**EXP3+COEFF4*Y**EXP4 for values of Y from YO to YF, where deltaY=0.01. Since values of Y are assumed to be inches, any scaling required must be performed before calling this subroutine. If Y is zero or negative, errors may be generated. 1 4.3 Subroutine C_FLINE ---------------- GENERAL DESCRIPTION: CALLING SEQUENCE: Call C_FLINE (XARRAY,YARRAY,NPTS,INC,+-LINTYP,INTEQ) where: XARRAY is the name of the array containing the values to be plotted as the abscissa and the appropriate scaling parameters. YARRAY is the name of the array containing the values to be plotted as the ordinates and the appropriate scaling parameters. NPTS is the number of data points to be plotted: if NPTS >0 a straight line is drawn between the points. if NPTS <0 a smooth curve, drawn using a modified spline-fitting technique, is drawn between the points. INC is the increment between elements in the array to be plotted. INC >1 if the values to be plotted are in a mixed array. (Usually INC = 1.) +-LINTYP is used to control the type of graph produced: if LINTYP = 0 a line is plotted between successive data points. (No symbols are plotted.) if LINTYP = 1 a line plot is produced, with a symbol at each data point. if LINTYP = n a line plot is produced, with a symbol at every nth data point. if LINTYP = -n, connecting lines are not plotted between data points; a symbol appears at every nth data point. INTEQ is the integer equivalent used to specify the symbol to be plotted at a data point. (Refer to the description of C_SYMBOL for possible values of INTEQ.) COMMENTS: The arrays must be dimensioned with at least NPTS + 2 elements. The adjusted minimum value (FIRSTV) and the adjusted delta value (DELTAV), normally provided by the C_SCALE subroutine, must be stored following the data array. For the X array, the adjusted minimum is stored in XARRAY (NPTS*INC + 1), and the adjusted delta is in XARRAY (NPTS*INC + INC + 1). Similarly, for the Y array, the minimum is in YARRAY (NPTS*INC + 1), and the delta is in YARRAY (NPTS*INC + INC + 1). Therefore, XARRAY and YARRAY must be dimensioned to be at least NPTS*INC+INC+1. If scaling is not required, the user must place the appropriate minimum and delta values in the specified elements in the arrays. For a one-to-one correspondence between array data and plotted data, these values should be 0.0 (minimum) and 1.0 (delta). 1 4.4 Subroutine C_SMOOT ---------------- GENERAL DESCRIPTION: C_SMOOT is a FORTRAN subroutine which draws a smooth curve through a set of data points. It accomplishes this by using a modified spline-fitting technique. The subroutine receives a single coordinate pair on each call and accumulates the points until it has received a sufficient number to compute a pair of cubic parametric equations for a smooth curve. This accumulation method requires the user to specify an initial and a terminal call to the subroutine. The C_SMOOT subroutine operates in either of two modes: Smooth Mode and Plot Mode. CALLING SEQUENCE: Call C_SMOOT (XPAGE,YPAGE,IPEN) XPAGE,YPAGE are the coordinates, in inches, of a single point through which the pen moves. IPEN determines the mode and action of the C_SMOOT subroutine. DETAILED DESCRIPTION: The first call to C_SMOOT must use an IPEN value of 0 or -1 to put C_SMOOT in the Smooth Mode. if IPEN = 0, XPAGE,YPAGE define the initial point (P(1)) on the curve. The smoothing function ends at the last point (P(n)). An open curve is produced. if IPEN = -1, XPAGE,YPAGE are used to define the initial point (P(1)) on the curve. The smoothing function continues from the last point (P(n)) back to the initial point (P(1)). A closed curve is produced. SMOOTH MODE: When C_SMOOT is in the Smooth Mode, IPEN performs the following functions: IPEN = -2 XPAGE,YPAGE are used to define points P(2), P(3),..., P(N-1), and a smoothed curve is drawn through the points on the curve. IPEN = -3 XPAGE,YPAGE are used to define points P(2), P(3), ...,P(N-1), and the pen, in the up position, is moved through these points. The smoothing function is maintained. IPEN = 2 or 3 The call is treated as a normal CALL C_PLOT (XPAGE,YPAGE,IPEN), and the point is not considered a point on the curve. The point of departure from the curve is the next-to-last point received by C_SMOOT, not the last point. When the next call to C_SMOOT with IPEN = -2 or -3 is received, the pen is repositioned to the point where it left the smooth curve. The smooth curve is then continued as though the calls with IPEN = 2 or 3 had not occurred. IPEN <=(-24) is used for the terminal call while C_SMOOT is in the Smooth Mode. XPAGE,YPAGE represent P(N). The curve is finished, and the subroutine returns to the Plot Mode. C_PLOT MODE: C_SMOOT is in the Plot Mode after receiving a terminal call. IF IPEN = +-2 or +-3, the call is treated as a normal CALL C_PLOT (XPAGE,YPAGE,IPEN). COMMENTS: When C_SMOOT is called while it is in the Smooth Mode, the pen is not moved until three points on an open curve or four points on a closed curve have been received. For subsequent calls to C_SMOOT, the actual pen position is the next-to-last point received. Calls to other plotting subroutines may be intermixed with calls to C_SMOOT. Point-of-departure restrictions are the same as noted in the Smooth Mode description above. The first call to C_SMOOT must be with IPEN = 0 or -1. 1 4.5 Subroutine C_SCALG ---------------- GENERAL DESCRIPTION: C_SCALG is a FORTRAN subroutine used to determine scale factors of a data array to be plotted on a logarithmic scale. The scale factors are those used by subroutines C_LGLIN and C_LGAXS. C_SCALG is similar in operation to C_SCALE. CALLING SEQUENCE: CALL C_SCALG(ARRAY,AXLEN,NPTS,INC) where: ARRAY is the array containing the data to be scaled. The FORTRAN DIMENSION statement must specify at least two elements more than the number of values being scaled, to allow room for C_SCALG to store the computed starting value and scaling factor at the end of the array. AXLEN is the maximum length, in inches, over which the data is to be plotted. NPTS is the number of values in ARRAY to be scaled. INC is the increment between elements of the array to be plotted. INC is greater than 1 if the values to be plotted are in a mixed or multi-dimensioned array. (Normally INC = 1). COMMENTS: The array must be dimensioned with at least NPTS + 2 elements. The adjusted minimum value (FIRSTV) and the delta value (DELTAV) are stored by C_SCALG in the data array. The adjusted minimum is stored in ARRAY (NPTS*INC + 1), and the adjusted delta (log cycles per inch) is in ARRAY (NPTS*INC + INC + 1). Therefore, ARRAY must be dimensioned to be at least NPTS*INC+INC+1. Every INCth element of the array ARRAY, beginning with the first, is scanned to find the minimum and maximum values of the array. Next, the greatest value of 10**n (integer n) less than or equal to the minimum value is found and then stored in ARRAY (NPTS*INC + 1). Finally, the smallest value of 10**m (integer m) greater than or equal to the maximum value is established. The delta value is the difference between the minimum and maximum powers of ten, divided by AXLEN, yielding log cycles per inch. The delta value is stored in ARRAY (NPTS*INC + INC + 1). Examples: A. For the following array of values ARRAY(1) = 1500.0 ARRAY(2) = 3000.0 ARRAY(3) = 2500.0 ARRAY(4) = 300.0 and the following argument values AXLEN = 1.0 NPTS = 4 INC = 1 the adjusted minimum (FIRSTV) and delta value (DELTAV) stored by C_SCALG are: FIRSTV: ARRAY(5) = 100.0 DELTAV: ARRAY(6) = 2.0 B. If the value of AXLEN in Example A were changed to 4.0, the resultant values stored would be: FIRSTV: ARRAY(5) = 100.0 DELTAV: ARRAY(6) = 0.5 C. For the following array of values ARRAY(1) = 1.2* ARRAY(2) = 100.0 ARRAY(3) = 2.3* ARRAY(4) = 88.0 ARRAY(5) = 1.8* ARRAY(6) = 0.0 ARRAY(7) = 0.8* ARRAY(8) = 10.0 ARRAY(9) = 0.7* ARRAY(10) = 10.0 and the following argument values: AXLEN = 10.0 NPTS = 5 INC = 2. the adjusted minimum (FIRSTV) and delta value (DELTAV) are determined from the value of the asterisked items (1, 3, 5, 7, and 9) in the above array. The computed values are also stored two subscript elements apart. FIRSTV: ARRAY(11) = 0.1 DELTAV: ARRAY(13) = 0.2 1 4.6 Subroutine C_LGAXS ---------------- GENERAL DESCRIPTION: C_LGAXS is a FORTRAN subroutine which draws a logarithmic axis with annotation in powers of ten. C_LGAXS is similar in operation to C_AXIS. CALLING SEQUENCE: CALL C_LGAXS(XPAGE,YPAGE,IBCD,+-NCHAR,AXLEN,ANGLE,FIRSTV,DELTAV) where: XPAGE,YPAGE are the coordinates, in inches, of the axis starting point. IBCD is the character data to be used as the axis title (may be one or more characters). It is centered and positioned parallel to the axis. +-NCHAR is the number of characters in the axis title. if NCHAR is: negative, annotation is placed on the clockwise side of the axis (normally used for the X axis); positive, annotation is placed on the counterclockwise side of the axis (normally used for the Y axis). AXLEN is the length of the axis, in inches. ANGLE is the angle, in degrees, at which the axis is to be drawn. (The axis is rotated about XPAGE,YPAGE). The X axis is at 0 degrees; the Y axis is at 90 degrees. FIRSTV is the value of annotation at the beginning of the axis. DELTAV is the number of log cycles per inch (the reciprocal of the length of one cycle, in inches). COMMENTS: A tick mark is placed on the axis for each power of ten and for each of the nine integer values between. Annotation is placed at the tick marks as follows: If a cycle is not less than two inches long, the integer tick marks are annotated. The power-of-ten tick marks are annotated in the form 10**N. 1 4.7 Subroutine C_LGLIN ---------------- GENERAL DESCRIPTION: C_LGLIN is a FORTRAN subroutine used to plot data either in log-log or semi-log mode. C_LGLIN is similar in operation to C_LINE. CALLING SEQUENCE: CALL C_LGLIN (XARRAY,YARRAY,NPTS,INC,+-LINTYP,INTEQ,LOGTYP) where: XARRAY,YARRAY are the arrays containing the variables to be plotted as abscissa and ordinate, respectively; either logarithmic or linear, depending on the value of LOGTYP. They also contain the scaling parameters. NPTS is the number of points to be plotted. INC is the increment between elements in the array to be plotted. INC>1 if the values to be plotted are in a mixed array. (Usually INC = 1). +-LINTYP is used to control the type of graph produced: If LINTYP = 0 a line is plotted between successive data points. No symbols are plotted. If LINTYP = 1 a line plot is produced, with a symbol at each data point. If LINTYP = n a line plot is produced, with a symbol at every nth data point. If LINTYP = -n, connecting lines are not plotted between data points; a symbol appears at every nth data point. INTEQ is the integer equivalent used to specify the symbol to be plotted at a data point. (Refer to the description of C_SYMBOL for possible values of INTEQ.) LOGTYP is a code specifying the type of plot. If LOGTYP is: -1, a semi-log plot, logarithmic in X and linear in Y is produced; 0, a log-log plot is produced; +1, a semi-log plot, linear in X and logarithmic in Y is produced. COMMENTS: The arrays XARRAY and YARRAY must be dimensioned with at least NPTS + 2 elements. The adjusted minimum values and the delta values (normally provided by the C_SCALG subroutine for logarithmic data and by the C_SCALE subroutine for linear data) must be stored in the data arrays. For the X array, the adjusted minimum is stored in XARRAY (NPTS*INC + 1), and the adjusted delta is in XARRAY (NPTS*INC + INC + 1). Similarly, for the Y array, the minimum is in YARRAY (NPTS*INC + 1), and the delta is in YARRAY (NPTS*INC + INC + 1). Therefore, XARRAY and YARRAY must be dimensioned to be at least NPTS*INC+INC+1 words long. If scaling is not required, the user must place the appropriate minimum and delta values in the specified locations in the arrays. For linear arrays, these values should be 0.0 (minimum) and 1.0 (delta), to ensure a one-to-one correspondence between array data and plotted data. 1 4.8 Subroutine C_POLAR ---------------- GENERAL DESCRIPTION: C_POLAR is a FORTRAN subroutine which scales and plots a radial variable of any magnitude against an angular variable (angle in radians) as polar coordinates. C_POLAR produces either a line plot (with lines connecting data points) or a point plot, centered at (0.0). CALLING SEQUENCE: CALL C_POLAR (RADAR,ANGAR,NPTS,INC,+-LINTYP,INTEQ,RMAX,DR) where: RADAR is the name of the array containing the radial values. ANGAR is the name of the array containing the angular values (radians). NPTS is the number of data points to be plotted. INC is the increment between elements in the array. INC is greater than 1 if the values to be plotted are in a mixed array. Every INCth point in the array is plotted. (Normally INC = 1). RADAR and ANGAR must be dimensioned to be INC*NPTS words long. +-LINTYP is used to control the type of graph produced: If LINTYP = 0 a line is plotted between successive data points. No symbols are plotted. If LINTYP = 1 a line plot is produced, with a symbol at each data point. If LINTYP = n a line plot is produced, with symbol at every nth data point. If LINTYP = -n, connecting lines are not plotted between data points; a symbol appears at every nth data point. INTEQ is the integer equivalent used to specify the symbol to be plotted at the data point. (Refer to the description of C_SYMBOL for possible values of INTEQ). RMAX is the maximum radius for the plotting area, in page inches. If RMAX<=(0), DR is used as scale factor. DR is the scale factor. If RMAX>0, DR is computed by the C_POLAR subroutine; if RMAX<=(0), DR must contain the scale factor. DR is expressed in units of data per page inch. COMMENTS: Angles are measured in radians counterclockwise around (0.,0.), with zero being in the +X direction. Radial values are measured from (0.,0.), with negative values being plotted radially opposite from positive values. 1 5.0 APPLICATION ROUTINES The routines included in this category draw, on a single call, complete plots of types useful to engineers. They are not part of the software leased from CALCOMP, but they do use the Basic CALCOMP subroutines. 1 5.1 Subroutine C_CNTOUR ----------------- GENERAL DESCRIPTION: A contour map is a graphical representation of a three-dimensional surface or a function of two variables. A contour is defined as the intersection of the surface or function with a specified plane parallel to the reference plane. If the surface is denoted by z = f(x,y) where x and y are the coordinate values in the (x,y)-plane (reference plane), then z equals a constant defines the plane of intersection. A contour map consists of a set of contours, usually generated for equally spaced values of z. In a region where the surface changes rapidly, the individual contours are close together, and where the surface changes gradually, they are far apart. Thus, a contour map provides a means of observing topological behavior of a surface as well as locating regions where the function z has specific values. The C_CNTOUR subroutine and its supporting routines provide the user with a general-purpose package for preparing contour maps. The package was developed at the Westinghouse Research Laboratories and released at the Westinghouse Symposium for general use. CALLING SEQUENCE: CALL C_CNTOUR (A, NX, NY, X, Y, HGT, CV, NCV, LEGEND, NDIMA) where: A input double-subscripted array containing the discrete values of the function. NX index of the last row of data in A (INTEGER). NY index of the last column of data in A (INTEGER). X single-scripted array containing values of x corresponding to row positions of A. Y single-subscripted array containing values of y corresponding to column positions of A. HGT height of plot restricted to less than or equal to 6.5 inches (REAL). The width is established accordingly. CV single-scripted array of contour values to be plotted. NCV number of contour values (INTEGER). LEGEND Logical option. If .TRUE., the legend relating contour values and their identification numbers is printed. If .FALSE., this legend will not be printed. NDIMA the dimensional number of rows for A. COMMENTS: The CALCOMP initialization (C_PLOTS(0,0,0)) and termination (C_PLOT(X,Y,999)) calls must be supplied by the user, external to C_CNTOUR. These calls were left out of C_CNTOUR to allow the user to create multiple plots in a single program. 1 6.0 ACCESSING THE CALCOMP ROUTINES Program execution creates a metalanguage file with the default name "pdf". This file may be cataloged for future use or post processed immediately. The name of the output metalanguage file can be specified through the environment variable "CALCOMP_PDF". Post processing is done using the device dependent graphics post processing procedures which are described in detail in the DOCLIB file called GRPHDOC. SAMPLE JOB USING THE CALCOMP LIBRARY ------------------------------------ # assign a user specified name to output PDF export CALCOMP_PDF CALCOMP_PDF=pdf.$$ # compile and load user program "mycode.f" with calcomp library routines cf77 my_code.f -L/usr/local/lib -lcalcomp -o my_code.exe # execute user absolute my_code.e my_code.e < my_code.data gview -f pdf.$$ -t x11 -p 1 1 7.0 CALCOMP SUPPLEMENT - MOVING EXISTING CALCOMP CODE I. INTRODUCTION ------------- The CALCOMP plot library is based on materials leased from California Computer Products, Inc; and had been available in a very similar form on the old CDC 7600 Super Computers. Of course, this similarity is intentional. This library is trying to provide a consistent programming environment wherever possible. Therefore, users will notice that this guide is based heavily on it's 7600 predecessor. All of the subroutines from the 7600 version of the CALCOMP library have been included in this version; although plots generated will not always look exactly the same as those produced on the 7600s. The CALCOMP library is interfaced to locally developed routines (called primitives) which produce a file compatible with TEMPLATE PDF files. This allows CALCOMP-based code to generate output which can be sent to any supported TEMPLATE output device. Although TEMPLATE IS THE RECOMMENDED GRAPHICS PACKAGE, CALCOMP is being provided to meet certain special requirements: 1) To facilitate the migration of user code that already uses a CALCOMP-like package to new machines. 2) To support interfaces to non-inhouse code. Such code may often already support a set of CALCOMP-like calls. 3) Applications where resource utilization is more important that powerful graphics capabilities. There are no plans to provide local enhancements to CALCOMP, and TEMPLATE capabilities (such as high-level charting routines) will not be made available with CALCOMP. Those involved in program conversions and development are urged to consider long-term graphics requirements in deciding which package to use (CALCOMP or TEMPLATE). The CALCOMP software was initially developed to drive only CALCOMP plotters. In general, the calls produced plots directly in inches (A call to draw a line one unit long produced a one-inch line on the plotter). With the interfacing of CALCOMP to the TEMPLATE graphics system (which provides the ability to obtain output on a wide range of devices), the meaning of units in the CALCOMP library has undergone a change. CALCOMP Inches, therefore, may not translate directly into physical inches on a pen plotter SECTION II is written for the special audiences that most often will be using CALCOMP. It details the differences between this CALCOMP and 7600 CALCOMP and talks about how to get true inches when using PDF files. Also, important differences exist between this CALCOMP and standard CALCOMPs third-party software often provides interfaces to. The format of the following primary example program can be used as a guide as to how to nullify the affects of these differences. 1 II. DIFFERENCES FROM 7600 CALCOMP LIBRARIES -------------------------------------------- 1. For subroutines C_SYMBOL, C_AXIS, and C_LGAXS, the parameter used to specify text or title information (IBCD) has been changed to be type CHARACTER to be consistent with ANSI 77 FORTRAN. Data for these arguments should be changed to be type CHARACTER (although use of a Hollerith string or INTEGER array may currently work, their use is not recommended, and there are no plans to support this usage). 2. For subroutine C_SYMBOL on the 7600s, there is a "STANDARD" call (used to plot a text string) and a "SPECIAL" call (used to plot a single symbol). To Accommodate CHARACTER data and both versions of the call to C_SYMBOL, the calling sequence was modified to have 7 arguments. All programs being converted from the 7600 -MUST- make this change to the call to C_SYMBOL. The new calling sequence is CALL C_SYMBOL (XPAGE,YPAGE,HEIGHT,IBCD,INTEQ,ANGLE,NCHAR) Where XPAGE, YPAGE, HEIGHT, and ANGLE are defined as on the 7600s, and the user guide can be consulted for details of their use. The last parameter NCHAR is used as a flag to specify whether a text string or a single symbol is being plotted. If NCHAR is less that zero, a single symbol is plotted regardless of the contents of IBCD. If NCHAR is equal to or greater than zero the string is IBCD is used (FAILURE TO SPECIFY THE PROPER VALUE FOR NCHAR, INTEQ OR IBCD WILL CAUSE ERRONEOUS RESULTS). To use C_SYMBOL to plot text for titles, captions, or legends-- IBCD--Contains the text string as CHARACTER data. INTEQ--Should be set to 999. (THE ACTUAL VALUE IS NOT USED FOR ANYTHING.) NCHAR--Is the number of characters in IBCD. For example, the following call to C_SYMBOL will result in the characters 'TITLE 10' being output beginning at X and Y coordinates of 1.0. CHARACTER GRLBL*8 GRLBL = 'TITLE 10' CALL C_SYMBOL (1.0,1.0,0.14,GRLBL,999,0.0,8) To use C_SYMBOL to plot a single symbol or character-- IBCD--A dummy CHARACTER variable or string should be used THE ACTUAL VALUE IS NOT USED FOR ANYTHING.) INTEQ--Contains the INTEGER EQUIVALENT of the desired symbol. If INTEQ has a value of 0 (zero) through 14, a centered symbol (where XPAGE and YPAGE specify the center of the symbol) is produced. The symbol table is unchanged from that on the 7600s, so the table on page 2-10 of the 7600 CALCOMP guide is still applicable. NCHAR--Determines whether the pen is up or down during the move to XPAGE and YPAGE. (IT MUST BE NEGATIVE.) When NCHAR is-- -1, the pen is UP during the move. -2 or less, the pen is DOWN during the move. For example, the following call to C_SYMBOL will result in special symbol number 5 being output with its center at XY coordinates of (1.0,1.0). CALL C_SYMBOL (1.0,1.0,0.14,DUMMY,5,0.0,-1) 3. Because of interfacing the CALCOMP routines to the device dependent TEMPLATE-based post-processing procedures , some limit for the maximum plot size had to be established. For the CALCOMP library, a plot frame is limited to a maximum size in either the X or Y direction of 100 "CALCOMP inches". (The actual frame size on a particular output medium is dependent on the method of post- processing and the device selected.) Each plot frame is initialized by a call to subroutine C_PLOT with the third argument (IPEN) equal to -2 or -3. For example, CALL C_PLOT (0.5,1.0,-3) Says to move 0.5 inches in the X-direction and 1.0 inch in the Y-direction before establishing a new origin. When establishing a new origin, all offsets are included inside the frame boundary, and therefore, they are part of the plot frame size. If any X or Y coordinate value (Plus the appropriate offset) exceeds the 100 inch limit, results are unpredictable. In programs where X and Y coordinate values exceed the scaling limit, a call to the CALCOMP routine C_FACTOR may be used to scale down the plot size appropriately. Each plot frame is terminated by a call to subroutine C_NFRAME; no additional offset is added here. KNOWLEDGE OF THE PLOT FRAME SIZE IN THE X AND Y DIRECTIONS WILL BE NEEDED TO SCALE PEN PLOTS TO ACTUAL INCHES WHEN THE DEVICE DEPENDENT POST PROCESSING PROCEDURES ARE AVAILABLE. THE FOLLOWING EXAMPLE IS PROVIDED TO ASSIST IN UNDERSTANDING HOW THE FRAME SIZE IS DETERMINED. PROGRAM CALTEST CALL C_PLOTS (0,0,0) ! perform initialization CALL BORDER(8.5,11.0) ! establish a consistent frame size C Calls to generate first plot go here C where all calls stay inside area established by border C . C . CALL C_NFRAME ! terminate first plot CALL BORDER(8.5,11.0) ! establish a consistent frame size C In next plot negative values up to (-1,-2) are needed CALL C_PLOT (1.0,2.0,-3) ! establish origin for second plot C To stay in the border no numbers greater than XBORDER-1 in X C or YBORDER-2 can be used C Calls to generate second plot go here C . C . CALL C_NFRAME ! terminate second plot CALL C_PLOT (0.0,0.0,999)! close the plot file END SUBROUTINE BORDER(XBORDER,YBORDER) C Must be called with same values throughout entire program C or not all frames will plot to same scale. C Draw a box inside of which all frames can appear CALL C_PLOT (XBORDER,0.0, 2) CALL C_PLOT (XBORDER,YBORDER,2) CALL C_PLOT (0.0, YBORDER,2) CALL C_PLOT (0.0, 0.0, 2) RETURN END 4. All coordinate values (XPAGE, YPAGE for example) should be greater than or equal to zero relative to the original frame origin. Negative values will be clipped or might cause post-processor errors. (Although this was not a requirement on the 7600s, it is necessary because metafiles must contain only positive values and it would be very inefficient to store each frame's data and then translate all the values to positive numbers once the frame was finished and the largest negative numbers in the frame could be identified. 5. Use of the CALCOMP library results in a segmented -PDF- being created on a dataset called "pdf". Subroutine C_PLOTS can not be used to alter this name, only the FORTRAN unit number used when referencing it. 6. Subroutine C_PLOTS must still be the first CALCOMP subroutine called. It performs various initialization functions and should be called only one time per program execution. Although some of the values are not used, they are maintained for compatibility purposes. 7. Subroutine C_CNTOUR (Which was developed at the Westinghouse Research Laboratories) is available in the CALCOMP library. The plot produced by C_CNTOUR will look different from that produced on the 7600s since the legend is placed at the top of the plot. If more that 20 contours are used, the legend could overwrite the plot. A limit of 6.5 inches must be observed for the height parameter (HGT).