1Dashpack(3NCARG)                 NCAR GRAPHICS                Dashpack(3NCARG)
2
3
4

NAME

6       Dashpack - a set of routines allowing you to draw curves using dashed-
7       line patterns that may include gap-portion specifiers, solid-portion
8       specifiers, and label-string specifiers.  DASHPACK is intended to
9       replace and unify the old family of NCAR Graphics routines (DASHLINE,
10       DASHCHAR, DASHSMTH, and DASHSUPR), all of which date from the early
11       1970s or before.  At the time of its introduction, DASHPACK will do
12       anything that DASHLINE, DASHCHAR, and DASHSMTH will (and a number of
13       things that they won't); it does not yet functionally replace all of
14       DASHSUPR, but it is intended that this will eventually happen.  For the
15       moment, the older routines will stay in NCAR Graphics.
16
17       Structurally, DASHPACK is rather different from the routines that it
18       replaces: Its behavior is controlled by "internal parameters" that are
19       accessed by calling parameter-access routines, rather than by
20       manipulating the contents of labelled common blocks. There is only one
21       version of DASHPACK; rather than load a different version of it in
22       order to, say, turn smoothing on, one just changes the value of the
23       internal parameter that controls whether or not smoothing is done.
24       There is no analog of the old routines DASHDB and DASHDC in DASHPACK;
25       to use a different dash pattern, one just changes the values of the
26       internal parameters that specify what dash pattern to use.
27
28       As in other NCAR Graphics packages, each of the internal parameters of
29       DASHPACK has a three-character mnemonic name. The internal parameters
30       are described in detail in the man page "dashpack_params".
31
32       Dashed-Line Patterns
33
34       A dashed-line pattern (or just "dash pattern") may be specified using
35       either an integer or a character string (see the parameters 'DPL',
36       'DPS', and 'DPT').  However the pattern is specified, it is applied in
37       a repetitive fashion as a curve is drawn. For example, if the dash
38       pattern specifies a solid, a gap, and the label "A", a curve drawn
39       using it will include a solid, a gap, the label "A", a solid, a gap,
40       the label "A", and so on, until the end of the curve is reached. When a
41       new curve is begun, use of the dash pattern starts over: the new curve
42       starts with a solid, a gap, and the label "A".
43
44       If an integer dash pattern is used, the low-order "n" bits of the
45       integer (where "n" is the absolute value of the user-specified
46       parameter, 'DPS', and is between 1 and 32, inclusive) are interpreted;
47       0's represent gaps and 1's represent solids.
48
49       In a character-string dash pattern, the character used to represent a
50       gap (by default, an underscore) and the character used to represent a
51       solid (by default, a dollar sign) are determined by the values of other
52       internal parameters ('CRG' and 'CRS'); such characters may be mixed
53       with other strings of characters that are to be used as label strings.
54       There are parameters allowing one to specify how much distance along
55       the curve should be devoted to each gap ('WOG') and solid ('WOS'), what
56       size characters should be used for writing label strings ('WOC'),
57       whether label strings should be written at a fixed angle relative to
58       the plotter frame or in the direction of the curve ('SAF'), and, if
59       they are written in the direction of the curve, whether or not they
60       should be made to "bend" with the curve ('CRB' and 'SCF') and whether
61       or not it is allowed to rotate them by 180 degrees to make them more
62       nearly upright on the plotter frame ('SAF').
63
64       A label string written along a curve may either be placed in a gap left
65       in the curve or just written on top of it ('LS1', 'LS2', and 'LTL');
66       the latter is most effective when the characters are written in a color
67       different from that of the curve itself.
68
69       Output of label strings is buffered so that, if the end of the curve
70       occurs prior to the occurrence of the next solid or gap in the dash
71       pattern, the curve itself may be drawn in lieu of an incomplete label,
72       and so that, when labels are being made to "bend" with the curve, the
73       entire label can be inverted, if necessary, so as to have the majority
74       of it right-side up. This buffering is done by default, but may be
75       turned off, if desired ('SBF').
76
77       All character strings are written using calls to PLOTCHAR routines.
78       There is an internal parameter ('PCF') that says whether to call
79       PLCHHQ, PLCHMQ, or PLCHLQ. By default, PLCHHQ is used.
80
81       Curve Smoothing
82
83       Curve smoothing is turned on and off by setting a single internal
84       parameter ('TCS') that also specifies the tension on the cubic splines
85       used to do the smoothing. Another parameter ('SSL') specifies the
86       distance between points used to plot the smoothed curve and another
87       ('EPS') specifies the minimum distance between input points required
88       for them to be considered separate points.
89

SYNOPSIS

91       DPCURV - draws a complete curve with a single call.
92
93       DPDRAW - called to just draw the curve by connecting a given sequence
94       of points.
95
96       DPFRST - does a "pen-up" move to the first in a sequence of points
97       defining a curve.
98
99       DPGETC - called with the name of an internal parameter of type
100       CHARACTER and a character variable in which the value of that parameter
101       is to be returned.
102
103       DPGETI - called with the name of an internal parameter of type INTEGER
104       or REAL and an integer variable in which the integer equivalent of the
105       value of that parameter is to be returned.
106
107       DPGETR - called with the name of an internal parameter of type INTEGER
108       or REAL and a real variable in which the real equivalent of the value
109       of that parameter is to be returned.
110
111       DPLAST - called to say that the latest call to DPVECT was the last one
112       in the sequence, that drawing of the curve should be completed, and
113       that buffers should be flushed.
114
115       DPLINE - draws the straight line joining two points. (No smoothing
116       takes place, even if smoothing is turned on.)
117
118       DPSETC - called with the name of an internal parameter of type
119       CHARACTER and a character variable or constant that is to supply the
120       new value of that parameter.
121
122       DPSETI - called with the name of an internal parameter of type INTEGER
123       or REAL and an integer expression that is to become the new value of
124       that parameter.
125
126       DPSETR - called with the name of an internal parameter of type INTEGER
127       or REAL and a real expression that is to become the new value of that
128       parameter.
129
130       DPSMTH - called to create a smooth curve passing through a sequence of
131       points and then to interpolate points along that smoothed curve and
132       pass them on to DPDRAW.
133
134       DPVECT - does a "pen-down" move to the next in a sequence of points
135       defining a curve.
136

C-BINDING SYNOPSIS

138       #include <ncarg/ncargC.h>
139
140       c_dpcurv
141       c_dpdraw
142       c_dpfrst
143       c_dpgetc
144       c_dpgeti
145       c_dpgetr
146       c_dplast
147       c_dpline
148       c_dpsetc
149       c_dpseti
150       c_dpsetr
151       c_dpsmth
152       c_dpvect
153

ACCESS

155       To use the Dashpack C or Fortran routines, load the NCAR Graphics
156       libraries ncarg, ncarg_gks, and ncarg_c, preferably in that order.
157

MESSAGES

159       When error conditions are detected, the support routine SETER is
160       called. By default, SETER writes a message to the standard error file
161       (as defined by I1MACH(4)) and then terminates execution.  It is
162       possible to put SETER into recovery mode and regain control after a
163       recoverable error (which includes all of the possible errors).
164
165       The possible error messages are listed below.  All errors are
166       recoverable in the sense that a user program which has called ENTSR to
167       set recovery mode will get control back after one of these errors
168       occurs.
169
170            DPCURV - UNCLEARED PRIOR ERROR
171
172            This error message indicates that, at the time DPCURV was called,
173            there was an unrecovered outstanding error. In this case, DPCURV
174            cannot continue; it forces the error message for the outstanding
175            error to be printed and then substitutes this one for it.
176
177            DPDRAW - IMPLEMENTATION ERROR - SEE SPECIALIST
178
179            An internal error has occurred which indicates that DASHPACK has
180            not been correctly installed. See a specialist.
181
182            DPDRAW - UNCLEARED PRIOR ERROR
183
184            This error message indicates that, at the time DPDRAW was called,
185            there was an unrecovered outstanding error. In this case, DPDRAW
186            cannot continue; it forces the error message for the outstanding
187            error to be printed and then substitutes this one for it.
188
189            DPFRST - UNCLEARED PRIOR ERROR
190
191            This error message indicates that, at the time DPFRST was called,
192            there was an unrecovered outstanding error. In this case, DPFRST
193            cannot continue; it forces the error message for the outstanding
194            error to be printed and then substitutes this one for it.
195
196            DPGETC - PARAMETER NAME NOT KNOWN - X
197
198            The first argument in a call to DPGETC is not one of the legal
199            internal parameter names of DASHPACK. "X" is the value of the
200            offending first argument.
201
202            DPGETC - PARAMETER NAME TOO SHORT - X
203
204            The given parameter name is only one or two characters long. All
205            DASHPACK parameter names are at least three characters long, so
206            there is something wrong. "X" is the value of the offending first
207            argument.
208
209            DPGETC - UNCLEARED PRIOR ERROR
210
211            This error message indicates that, at the time DPGETC was called,
212            there was an unrecovered outstanding error. In this case, DPGETC
213            cannot continue; it forces the error message for the outstanding
214            error to be printed and then substitutes this one for it.
215
216            DPGETI - UNCLEARED PRIOR ERROR
217
218            This error message indicates that, at the time DPGETI was called,
219            there was an unrecovered outstanding error. In this case, DPGETI
220            cannot continue; it forces the error message for the outstanding
221            error to be printed and then substitutes this one for it.
222
223            DPGETR - PARAMETER NAME NOT KNOWN - X
224
225            The first argument in a call to DPGETR is not one of the legal
226            internal parameter names of DASHPACK. "X" is the value of the
227            offending first argument.
228
229            DPGETR - PARAMETER NAME TOO SHORT - X
230
231            The given parameter name is only one or two characters long.  All
232            DASHPACK parameter names are at least three characters long, so
233            there is something wrong. "X" is the value of the offending first
234            argument.
235
236            DPGETR - UNCLEARED PRIOR ERROR
237
238            This error message indicates that, at the time DPGETR was called,
239            there was an unrecovered outstanding error. In this case, DPGETR
240            cannot continue; it forces the error message for the outstanding
241            error to be printed and then substitutes this one for it.
242
243            DPLAST - UNCLEARED PRIOR ERROR
244
245            This error message indicates that, at the time DPLAST was called,
246            there was an unrecovered outstanding error. In this case, DPLAST
247            cannot continue; it forces the error message for the outstanding
248            error to be printed and then substitutes this one for it.
249
250            DPLINE - UNCLEARED PRIOR ERROR
251
252            This error message indicates that, at the time DPLINE was called,
253            there was an unrecovered outstanding error. In this case, DPLINE
254            cannot continue; it forces the error message for the outstanding
255            error to be printed and then substitutes this one for it.
256
257            DPSETC - PARAMETER NAME NOT KNOWN - X
258
259            The first argument in a call to DPSETC is not one of the legal
260            internal parameter names of DASHPACK. "X" is the value of the
261            offending first argument.
262
263            DPSETC - PARAMETER NAME TOO SHORT - X
264
265            The given parameter name is only one or two characters long. All
266            DASHPACK parameter names are at least three characters long, so
267            there is something wrong. "X" is the value of the offending first
268            argument.
269
270            DPSETC - UNCLEARED PRIOR ERROR
271
272            This error message indicates that, at the time DPSETC was called,
273            there was an unrecovered outstanding error. In this case, DPSETC
274            cannot continue; it forces the error message for the outstanding
275            error to be printed and then substitutes this one for it.
276
277            DPSETI - UNCLEARED PRIOR ERROR
278
279            This error message indicates that, at the time DPSETI was called,
280            there was an unrecovered outstanding error. In this case, DPSETI
281            cannot continue; it forces the error message for the outstanding
282            error to be printed and then substitutes this one for it.
283
284            DPSETR - PARAMETER NAME NOT KNOWN - X
285
286            The first argument in a call to DPSETR is not one of the legal
287            internal parameter names of DASHPACK. "X" is the value of the
288            offending first argument.
289
290            DPSETR - PARAMETER NAME TOO SHORT - X
291
292            The given parameter name is only one or two characters long. All
293            DASHPACK parameter names are at least three characters long, so
294            there is something wrong. "X" is the value of the offending first
295            argument.
296
297            DPSETR - UNCLEARED PRIOR ERROR
298
299            This error message indicates that, at the time DPSETR was called,
300            there was an unrecovered outstanding error. In this case, DPSETR
301            cannot continue; it forces the error message for the outstanding
302            error to be printed and then substitutes this one for it.
303
304            DPSMTH - UNCLEARED PRIOR ERROR
305
306            This error message indicates that, at the time DPSMTH was called,
307            there was an unrecovered outstanding error. In this case, DPSMTH
308            cannot continue; it forces the error message for the outstanding
309            error to be printed and then substitutes this one for it.
310
311            DPVECT - UNCLEARED PRIOR ERROR
312
313            This error message indicates that, at the time DPVECT was called,
314            there was an unrecovered outstanding error. In this case, DPVECT
315            cannot continue; it forces the error message for the outstanding
316            error to be printed and then substitutes this one for it.
317
318

SEE ALSO

320       Online: dashpack_params, dpcurv, dpdraw, dpfrst, dpgetc, dpgeti,
321       dpgetr, dplast, dpline, dpsetc, dpseti, dpsetr, dpsmth, dpvect,
322       ncarg_cbind.
323
324       Hardcopy: None.
325
327       Copyright (C) 1987-2009
328       University Corporation for Atmospheric Research
329       The use of this Software is governed by a License Agreement.
330
331
332
333UNIX                              March 1995                  Dashpack(3NCARG)
Impressum