If an integer dash pattern is used, the low-order "n" bits of the integer (where "n" is the absolute value of the user-specified parameter, 'DPS', and is between 1 and 32, inclusive) are interpreted; 0's represent gaps and 1's represent solids.
In a character-string dash pattern, the character used to represent a gap (by default, an underscore) and the character used to represent a solid (by default, a dollar sign) are determined by the values of other internal parameters ('CRG' and 'CRS'); such characters may be mixed with other strings of characters that are to be used as label strings. There are parameters allowing one to specify how much distance along the curve should be devoted to each gap ('WOG') and solid ('WOS'), what size characters should be used for writing label strings ('WOC'), whether label strings should be written at a fixed angle relative to the plotter frame or in the direction of the curve ('SAF'), and, if they are written in the direction of the curve, whether or not they should be made to "bend" with the curve ('CRB' and 'SCF') and whether or not it is allowed to rotate them by 180 degrees to make them more nearly upright on the plotter frame ('SAF').
A label string written along a curve may either be placed in a gap left in the curve or just written on top of it ('LS1', 'LS2', and 'LTL'); the latter is most effective when the characters are written in a color different from that of the curve itself.
Output of label strings is buffered so that, if the end of the curve occurs prior to the occurrence of the next solid or gap in the dash pattern, the curve itself may be drawn in lieu of an incomplete label, and so that, when labels are being made to "bend" with the curve, the entire label can be inverted, if necessary, so as to have the majority of it right-side up. This buffering is done by default, but may be turned off, if desired ('SBF').
All character strings are written using calls to PLOTCHAR routines. There is an internal parameter ('PCF') that says whether to call PLCHHQ, PLCHMQ, or PLCHLQ. By default, PLCHHQ is used.
NOTE: As of 11/16/2004, a new capability has been added. Dash patterns may now contain "symbol-selection" characters, calling for the drawing of symbols along a curve. See the descriptions of the routines DPDPWS, which is used to create dash patterns that contain such characters (each of which has its highest-order bit turned on, allowing it to be distinguished from other characters), and DPDSYM, the default version of which can draw any of ten different symbols. The size and orientation of symbols along a curve are determined by the same parameters that affect character strings: 'WOC' and 'SAF'. However, symbols do not become part of the character strings they are next to; if you try to put a symbol in the middle of a character string serving as a label, it will break that label into two pieces, each of which will act like a separate label. For an example showing how to use dash patterns that include symbols, see the section "Use of DASHPACK by AUTOGRAPH", in the programmer document for AUTOGRAPH, which includes a link to such an example, called "agdp01".
The routine DPRSET may be called to reset the values of all internal parameters of DASHPACK to the defaults:
CALL DPCURV (XCPU,YCPU,NPTS)
draws a complete curve by connecting the point (XCPU(1),YCPU(1)) to
the point (XCPU(2),YCPU(2)), connecting that point to the point
(XCPU(3),YCPU(3)), and so on through the last point,
(XCPU(NPTS),YCPU(NPTS)), in a manner described by the current values
of the internal parameters of DASHPACK. DPCURV maps the input coordinates to the fractional system and then passes them on to lower-level routines. If smoothing is turned off, DPCURV calls DPDRAW; if smoothing is turned on, it calls DPSMTH.
NPTS (an input expression of type INTEGER) is the number of points defining the curve.
CALL DPLINE (XCP1,YCP1,XCP2,YCP2)
draws a straight-line segment joining the point (XCP1,YCP1) to the point
(XCP2,YCP2) in a manner described by the current values of the internal
parameters of DASHPACK. DPLINE maps the input coordinates to the fractional system and then passes them on to DPDRAW. Even if smoothing is turned on, no smoothing is done by a call to DPLINE.
XCP2 and YCP2 (input expressions of type REAL) are the X and Y coordinates, in the user coordinate system, of the point at the end of the straight-line segment.
CALL DPFRST (XCPU,YCPU)
does a "pen-up" move to the first of a sequence of points defining a
curve. Call DPVECT to do "pen-down" moves to each of the other points
in the sequence and then call DPLAST to finish drawing the curve and
flush the buffers.DPFRST maps the input coordinates of the given point to the fractional coordinate system and then does a "pen-up" call to either DPDRAW (if smoothing is turned off) or DPSMTH (if smoothing is turned on) with those coordinates.
CALL DPVECT (XCPU,YCPU)
does a "pen-down" move to each point after the first in a sequence of
points defining a curve. Prior to the first call to DPVECT, call DPFRST
to do a "pen-up" move to the first point in the sequence and then, after
the last call to DPVECT, call DPLAST to finish drawing the curve and
flush the buffers.DPVECT maps the input coordinates of the given point to the fractional coordinate system and then does a "pen-down" call to either DPDRAW (if smoothing is turned off) or DPSMTH (if smoothing is turned on) with those coordinates.
CALL DPLAST
to finish drawing the curve defined by prior calls to DPFRST and DPVECT
and to flush the buffers. Call DPFRST to do a "pen-up" move to the first
point in the sequence, DPVECT to do "pen-down" moves to the second and
following points in the sequence, and DPLAST to finish the process.DPLAST just does a "buffer-flush" call to either DPDRAW (if smoothing is turned off) or DPSMTH (if smoothing is turned on).
CALL DPDRAW (XCPF,YCPF,0)
to do a "pen-up" move to the first point in a sequence of points defining
a curve, Fortran statements like
CALL DPDRAW (XCPF,YCPF,1)
to do pen-down moves to the second and following points in the sequence,
and the Fortran statement
CALL DPDRAW (0.,0.,2)
to terminate the sequence, finish drawing the curve, and flush the
buffers.
IFVL (an input expression of type INTEGER) is a flag indicating what kind of call is being done:
CALL DPSMTH (XCPF,YCPF,0)
to do a "pen-up" move to the first point in a sequence of points defining
a curve, Fortran statements like
CALL DPSMTH (XCPF,YCPF,1)
to do pen-down moves to the second and following points in the sequence,
and the Fortran statement
CALL DPSMTH (0.,0.,2)
to terminate the sequence, finish drawing the curve, and flush the
buffers. DPSMTH accumulates points until it has an internal buffer-load or until the last one has been received. It then creates a smooth curve passing through all the points, interpolates points along that smooth curve, and passes those points along to the routine DPDRAW. If the internal parameter 'TCS' has a value less than or equal to zero, the smoothing is done using simple cubic splines; if 'TCS' has a value greater than zero, the smoothing is done using cubic splines under tension and 'TCS' specifies the desired tension.
IFVL (an input expression of type INTEGER) is a flag indicating what kind of call is being done:
CALL DPSETC (PNAM,CVAL)
CALL DPSETI (PNAM,IVAL)
CALL DPSETR (PNAM,RVAL)
to set the value of the parameter specified by PNAM to the value
specified by the argument CVAL, IVAL, or RVAL.Before changing the parameter, DPSETx will do a
CALL DPSMTH (0.,0.,2)
to flush all buffers in DPSMTH and DPDRAW. This ensures that the
parameter change will affect only curves drawn by later calls.
xVAL (an input variable or constant of type CHARACTER or an input expression of type INTEGER or REAL, depending on whether "x" is a "C", an "I", or an "R") defines the new value to be given to the internal parameter specified by PNAM.
CALL DPGETC (PNAM,CVAL)
CALL DPGETI (PNAM,IVAL)
CALL DPGETR (PNAM,RVAL)
to retrieve, in the variable CVAL, IVAL, or RVAL, the value of the
parameter specified by PNAM.
xVAL (an output variable of type CHARACTER, INTEGER, or REAL, depending on whether "x" is a "C", an "I", or an "R") is the name of a variable into which the value of the internal parameter specified by PNAM is to be retrieved.
CALL DPDPWS (DPCH,DSYM,DPAT)
to create, from a basic pattern, DPCH, and a symbol-selection pattern,
DSYM, a combined dash pattern, DPAT, suitable for use in a call to
DPSETC as the value of the internal parameter 'DPT'.
DPCH (input expression of type CHARACTER and length "n") is the basic dash pattern desired, containing characters that represent solids (sections of a curve that are drawn), gaps (sections of a curve that are not drawn), other characters that are simply to be written along a curve, break characters (specifying breakpoints within a string of characters to be written along a curve and thereby allowing the string to bend with the curve), and, finally, symbol-selecting characters. For example, assuming the default values of 'CRS' ('$', to represent a solid), 'CRG' ('_', to represent a gap), and 'CRB' ('|', to represent a break), one might use the following value of DPCH:
'$$$_1|3|.|6|2_$$$000'
This would specify a dash pattern consisting of a three-unit solid, a
one-unit gap, the digits '1', '3', '.', '6', and '2', another one-unit
gap, another three-unit solid, and, finally, three zeros, which will
become characters selecting filled-circle symbols. See the description
of the routine DPDSYM, below, for a list of the possible symbol-selecting
characters.DSYM (input expression of type CHARACTER and length "n") is a character string of the same length as DPCH. If an element of DSYM is not a blank and not a minus sign, it says that the corresponding element of DPCH is to be treated as a symbol-selection character. In the example above, one might use this value of DSYM:
'-----------------+++'
indicating that only the last three characters of the twenty-character
value of DPCH are to be treated as symbol-selection characters:DPAT (output variable of type CHARACTER and length "n") is a character string, constructed from DPCH and DSYM, that one can use as a value of 'DPT', specifying a dash pattern that includes the desired symbols. (Actually, DPAT is just a copy of DPCH, but the highest-order bit of each of the symbol-selection characters is turned on.)
CALL DPDSYM (XPSW,YPSW,CSYM,WOSW,ANGD)
to draw a specified symbol at a specified position, of a specified size,
and having a specified orientation.
CSYM (input expression of type CHARACTER) is a single character, specifying what symbol is to be written. The default version of DPDSYM allows for ten possibilities:
ANGD (input expression of type REAL) is the desired angular orientation of the symbol, in degrees counterclockwise from a vector pointing horizontally to the right.
The internal parameters of DASHPACK are as listed in the following table:
| Name | Type | Description |
|---|---|---|
| 'CRB' | C | "Character Representing Break" - the
single character that is to be used in a label string in a character dash
pattern to represent a break point in the label string. (Each piece of the
label string is written using a separate call to PLCHHQ, PLCHMQ, or PLCHLQ;
the effect is to make the label "bend" with the curve that it labels.) The default value of 'CRB' is a vertical bar. |
| 'CRG' | C | "Character Representing Gap" - the
single character that is to be used in a character dash pattern to represent
a gap (of width 'WOG') in the curve. The default value of 'CRG' is an underscore. |
| 'CRS' | C | "Character Representing Solid" - the
single character that is to be used in a character dash pattern to represent
a solid section (of width 'WOS') of the curve. The default value of 'CRS' is a dollar sign. |
| 'DPL' | I | "Dash Pattern Length" - the length
of the internal parameter 'DPT', as set by DPSETC or by a subsequent call
to DPSETI or DPSETR. Calling DPSETC with first argument 'DPT' sets both 'DPT', which is the character dash pattern, and 'DPL', which is its length; 'DPL' can later be reset (normally to a smaller value) by a subsequent call to DPSETI or DPSETR with first argument 'DPL' , thus requesting the use of a different number of characters of the specified dash pattern. The value of 'DPL' must be between 1 and 256. The default value is 16. |
| 'DPS' | I | "Dash Pattern Selector" - selects
the dash pattern to be used. A negative value of 'DPS' says that the integer dash pattern (as specified by a call to DPSETI or DPSETR with first argument 'DPT') is to be used. If the absolute value is "n", then the low-order "n" bits of the integer are used as the dash pattern. No more than 32 bits of an integer dash pattern may be used; using more than 24 may be a problem on some systems. A positive value of 'DPS' says that the current character dash pattern (as specified by a call to DPSETC with first argument 'DPT') is to be used; 'DPS' = 0 says to use the first 'DPL' characters of the dash pattern, while 'DPS' > 0 says to use the first 'DPS' characters of the dash pattern. No more than 256 characters of a character dash pattern may be used. The value of 'DPS' must be between -32 and +256. The default value is 0. |
| 'DPT' | C or I | "Dash PaTtern" - one of the
current dash patterns. (In a call to DPSETC or DPGETC, the name 'DPT'
refers to the current character-string dash pattern, but in a call to DPSETI,
DPGETI, DPSETR, or DPGETR, it refers to the current integer dash pattern.
Which of these is actually in use at a given time is specified by the value
of the internal parameter 'DPS'.) In an integer dash pattern, 1 bits represent solids and 0 bits represent gaps. No more than 32 bits of an integer dash pattern may be used; using more than 24 bits may be a problem on some systems. A character dash pattern is a string of 256 or fewer characters; in such a string, occurrences of the characters specified by the values of 'CRG' and 'CRS' specify gaps and solids, respectively. Other characters in the dash pattern form label strings to be written along a curve. Within each complete label string of a character dash pattern, the character specified by the value of 'CRB' may be used to specify "break points" at which the label string may be broken into smaller substrings. Alternatively, the single-character flag 'SCF' may be set non-zero to say that the label string may be broken into single-character substrings. Since each such substring is written by a separate call to PLCHHQ, PLCHMQ, or PLCHLQ, the effect of breaking up a label string is to make the label "bend" with the curve. The default character dash pattern consists of sixteen dollar signs, and the default integer dash pattern is "65535", which has sixteen low-order 1s. |
| 'EPS' | R | "EPSilon" - says how far apart two
points have to be (in X or Y, in the fractional coordinate system) in order
to be considered separate points by the smoothing routine DPSMTH. The value of 'EPS' must be greater than or equal to zero. The default value is .000001. |
| 'LS1' | R | "Label Spacing parameter 1" -
specifies how much extra gap space to leave at the beginning and end of
a label. Giving 'LS1' a non-zero value helps to ensure that there will be
a sufficiently large gap to (for example) prevent a leading minus sign from
appearing to be part of the line. The value of 'LS1' is given as a multiple of the value of the parameter 'WOC' (the width of a character); it must not be less than zero nor greater than 10. The default value is .5. |
| 'LS2' | R | "Label Spacing parameter 2" -
specifies how much extra gap space to leave for each piece of a broken
label. When break characters are used or the single-character flag 'SCF'
is turned on, 'LS2' determines the spacing of the characters along the
line. The value of 'LS2' is given as a multiple of the value of the parameter 'WOC' (the width of a character); it must not be less than zero nor greater than 10. The default value is 0. |
| 'LTL' | I | "Line Through Label" - a flag that
says whether or not each label substring specified by a character dash
pattern is to be written in a gap ('LTL' = 0) or just on top of the curve
('LTL' = 1). The latter is most effective if the line is one color and the
labels are another color. The value of 'LTL' must be either 0 or 1. The default value is 0. |
| 'MFS' | R | "Multiplier for First Solid" - a
real multiplier for the length of an initial solid portion of a curve drawn
by DASHPACK. The object of using this is to make it possible to slightly
offset labels on curves that are very nearly parallel to one another (as
can happen, for example, when drawing contour lines). The value of 'MFS' must be greater than or equal to zero. The default value is 1. |
| 'PCF' | I | "PlotChar Flag" - says which
PLOTCHAR routine is to be called to draw character strings. The value 0
says to call PLCHHQ, the value 1 says to call PLCHMQ, and the value 2 says
to call PLCHLQ. The value of 'PCF" must be either 0, 1, or 2. The default value is 0. |
| 'SAF' | R | "String Angle Flag" - says how
labels are to be oriented. If 'SAF' = 0, labels are written along a curve in the direction in which the curve is being drawn. If 'SAF' is negative, labels are written in the direction ABS('SAF') degrees, but this is done only if 'LTL' is non-zero; otherwise, the code behaves as if 'SAF' were zero: labels are written in the direction of the curve. If 'SAF' is greater than zero, labels are written along the curve, but the angle is adjusted by adding multiples of 180 degrees so that the resulting angle lies in the range from 'SAF'-90 to 'SAF'+90 degrees. If a label string is broken into substrings (either because there are "break" characters in it or because 'SCF' is non-zero), a negative value of 'SAF' will be treated as a zero value; a value greater than zero may cause the entire label to be written in the opposite direction along the curve if that ensures that more characters of the label will be written at angles between 'SAF' -90 and 'SAF'+90 degrees. Generally, when 'SAF' is non-zero, it is either -360 or +360, which has the effect of making the labels as nearly upright as possible on the frame. The value of 'SAF" must be in the range from -360 to +360. The default value is 360. |
| 'SBF' | I | "String Buffering Flag" - a flag
that says whether output of labels is to be buffered or not. When 'SBF' is non-zero, buffering is done. This ensures that, if the end of a curve occurs anywhere within a particular label, no part of the label is written; instead, that part of the curve is drawn using only the gap and solid elements of the dash pattern. Buffering is also important when 'SCF' is non-zero or there are "break" characters in a label string and 'SAF' is greater than zero; in this case, the buffering makes it possible to reorient the label as needed to make most of it upright. When 'SBF' is zero, buffering is turned off. There may be gaps at the ends of curves. If, in addition, 'SCF' is non-zero or there are "break" characters in label strings, there may be partial labels at the ends of curves. The value of 'SBF' must be either 0 or 1. The default value is 1. |
| 'SCF' | I | "Single Character Flag" - when
'SCF' is non-zero, it says that the label-string portions of character dash
patterns are to be broken into single-character pieces, each of which is to
be written by a separate call to PLCHHQ, PLCHMQ, or PLCHLQ. If 'SCF' = 0,
label strings are broken into pieces only at the break points indicated by
the use of "break" characters in the strings. It is not appropriate to use 'SCF' non-zero when PLCHHQ is being used and a label string in the dash pattern contains function codes that are meaningful to PLCHHQ; in that case, one should leave 'SCF' = 0 and use the "break" character 'CRB' in the label string to tell DASHPACK where it can be broken. The value of 'SCF" must be either 0 or 1. The default value is 0. |
| 'SSL' | R | "Smoothed Segment Length" - specifies
how far apart the points used to draw a smoothed curve should be. The value of 'SSL' is given in the fractional coordinate system and must be in the range from .000001 to 1. The default value is .01. |
| 'TCS' | R | "Tension on Cubic Splines" - a value
which, if negative, turns smoothing off, and which, if non-negative, turns
smoothing on and, if greater than zero, specifies the desired tension to be
used on the cubic splines used to do the smoothing. Note that only the routines DPCURV, DPFRST, DPVECT, DPLAST, and DPSMTH are affected by the value of 'TCS'; the routines DPLINE and DPDRAW never smooth. The routine DPSMTH always smooths: if 'TCS' is less than or equal to zero, simple cubic splines are used, and, if 'TCS' is greater than zero, splines under tension are used, in which case 'TCS' specifies the desired tension. It's a bad idea to use values of 'TCS' much bigger than about 15, as this can cause overflows in the smoothing routines. The default value is -1. |
| 'WOC' | R | "Width Of Character" - the character
width to be used in writing labels. The value of 'WOC' is given in the fractional coordinate system and must be in the range from .000001 to 1. The default value is .01. |
| 'WOG' | R | "Width of Gap" - the width of each
gap in the dashed line. The value of 'WOG' is given in the fractional coordinate system and must be in the range from .000001 to 1. The default value is .005. |
| 'WOS' | R | "Width of Solid" - the width of
each solid in the dashed line. The value of 'WOS' is given in the fractional coordinate system and must be in the range from .000001 to 1. The default value is .005. |
By default, SETER prints a line and STOPs. The line printed will look something like this:
ERROR 3 IN DPGETR - PARAMETER NAME NOT KNOWN - QAT
The error number ("3", in the example) may be of use to a consultant (to
determine exactly where the error occurred), but is not otherwise meaningful.
The actual error message consists of the name of the routine in which the
error occurred ("DPGETR", in the example), a blank, a minus sign, another
blank, and, lastly, a short description of the error (in this case, to the
effect that a specified parameter name is unrecognized).All errors are "recoverable" in the sense that, if the user program puts SETER into "recovery mode", control will be returned to the caller of the DASHPACK routine in which the error occurred. In some cases, it is then possible to take remedial action to get around whatever problem has occurred; in any case, the error flag can be cleared and execution of the user's program can continue.
When SETER is in recovery mode (and, occasionally, even when it is not), error messages may have a somewhat more complicated form, like this:
DPGETI/DPGETR - PARAMETER NAME NOT KNOWN - QAT
What this particular error message says is that DPGETI called DPGETR, which
detected an error condition and called SETER. Upon getting control back from
DPGETR, DPGETI detected the fact that DPGETR had logged an error. It
augmented the error message by prepending its own name, followed by a slash,
and then passed control back to the user. Of course, there can be more than
two such levels of routine calls indicated in the error message: in a few
cases, seven or eight routine names may be listed, each separated from the
next by a slash.The various error conditions in DASHPACK are described in the list below. Each bulleted item includes an error message and a thumb-nail description of the error. The items in the list are arranged in alphabetical order. If you get an error message with one or more prefixed subroutine names, as described above, omit them and look up the result in this list. Note that, since DASHPACK routines sometimes call other routines, elsewhere in NCAR Graphics, that can detect error conditions and call SETER, the error message you get by calling a DASHPACK routine may not be listed here, but in the programmer document for some other package.
ncargex tdshpk
To look at the resulting metafile, use the command
ctrans tdshpk.ncgm
To acquire the code for the example without running it, use the command
ncargex -n tdshpk
After the source file has been modified, compile and run it using the
commands
ncargf77 tdshpk.f
a.out
Then, to look at the resulting metafile, use the command
ctrans gmeta
(For "ctrans" to work properly, one or more environment variables may need
to be set.)The unmodified example produces three frames:
User-level entry points in the package DASHPACK are as follows: DPCURV, DPDRAW, DPFRST, DPGETC, DPGETI, DPGETR, DPLAST, DPLINE, DPSETC, DPSETI, DPSETR, DPSMTH, and DPVECT. There is also a BLOCK DATA routine called DPBLDA.
DASHPACK uses the following common block names: DPCMCH and DPCMRI.
DASHPACK uses the routine SETER and various routines from the package SPPS.
DASHPACK is written in portable FORTRAN-77.