                 Chapter 5: Plotting Curves

This chapter describes how to plot  curves  with  lines  and
symbols.  Several curves  can be plotted  in one axis system
and can be differentiated by colour, line style and pattern.
Curve attributes can be plotted in a legend.

5.1 Plotting Curves

                         C U R V E

CURVE  connects  data points  with lines  or plots them with
symbols.

The call is:  CALL CURVE (XRAY, YRAY, N)          level 2, 3

XRAY, YRAY    are arrays that contain X- and Y-coordinates.
              For a polar scaling, XRAY must hold the radial
              values and YRAY the  angular values  expressed
              in radians.
N             is the number of data points.

Notes:     -  CURVE must be called after  GRAF  from level 2
              or 3.
           -  By default, data points that lie outside of an
              axis system  are  listed  on the  screen.  The
              listing  can be  suppressed  with the  routine
              NOCHEK.
           -  For a logarithmic  scaling  of an axis,  CURVE
              suppresses the plotting of curves and prints a
              warning if some corresponding data coordinates
              have non positive values.  After the statement
              CALL NEGLOG (EPS),  where EPS is a small posi-
              tiv floating-point number,  CURVE will use the
              value EPS for non positive values.
           -  CURVE suppresses  lines outside the borders of
              an axis system.  Suppressing  can be  disabled
              with  NOCLIP or the margins of suppression can
              be changed with GRACE.
           -  INCMRK determines if CURVE plots lines or sym-
              bols.
           -  When plotting several curves,  attributes such
              as colour and line style can be changed  auto-
              matically by  DISLIN  or directly by the user.
              The routine CHNCRV  defines  which  attributes
              are changed automatically.  The routines COLOR
              or  SETCLR are used to define colours,  SOLID,
              DOT,  DASH,  CHNDOT,  CHNDSH,  DOTL, DASHM and
              DASHL to define line styles and  MARKER to de-
              fine symbols plotted  with the routine  CURVE.
           -  Different  data interpolation  methods  can be
              chosen with POLCRV.

5.2 Plotting Legends

To differentiate multiple curves in an axis system,  legends
with text can be plotted.  DISLIN can store  up to 30  curve
attributes  such as  symbols,  thicknesses,  line styles and
colours and these can be incorporated in a legend.

Legends are created with the following steps:

       (1)   define a character variable used to store the
             lines of text in the legend
       (2)   initialize the legend
       (3)   define the lines of text
       (4)   plot the legend.

The corresponding routines are:

                         L E G I N I

LEGINI initializes a legend.

The call is:  CALL LEGINI (CBUF, NLIN, NMAX)   level 1, 2, 3

CBUF          is a  character  variable  used to  store  the
              lines of text in the legend. The variable must
              be defined by the user to have at least NLIN *
              NMAX characters.
NLIN          is the number of text lines in the legend.
NMAX          is the  number of  characters  in the  longest
              line of text.

                         L E G L I N

LEGLIN stores lines of text for the legend.

The call is:  CALL LEGLIN (CBUF, CSTR, ILIN)   level 1, 2, 3

CBUF          see LEGINI.
CSTR          is a character string  that contains a line of
              text for the legend.
ILIN          is the number of the legend line between 1 and
              NLIN.

                         L E G E N D

LEGEND plots legends.

The call is:  CALL LEGEND (CBUF, NCOR)            level 2, 3

CBUF          see LEGINI.[0.3cm]
NCOR          indicates the position of the legend:
      =  1    is the lower left corner of the page.
      =  2    is the lower right corner of the page.
      =  3    is the upper right corner of the page.
      =  4    is the upper left corner of the page.
      =  5    is the lower left corner of the axis system.
      =  6    is the lower right corner of the axis system.
      =  7    is the upper right corner of the axis system.
      =  8    is the upper left corner of the axis system.

Notes:        The following routines change the position and
              appearance  of a legend.  They must  be called
              after LEGINI except for the routines FRAME and
              LINESP.

           -  LEGTIT (CTIT) sets the title of the legend.
           -  LEGPOS (NX, NY) defines a global  position for
              the legend  where NX and NY are the plot coor-
              dinates of the upper left corner. After a call
              to LEGPOS, the second parameter in LEGEND will
              be ignored.
           -  NLX = NXLEGN (CBUF)   and  NYL = NYLEGN (CBUF)
              return the length  and the height  of a legend
              in plot coordinates.
           -  FRAME (NFRA) defines the thickness  of a frame
              plotted around a legend.
           -  LINESP (XF)  changes the spacing of lines in a
              legend.
           -  LEGCLR  retains the same colour for curves and
              lines of text in the legend.
           -  The statement   CALL MIXLEG  enables  multiple
              text lines in legends. By default, the charac-
              ter '/' is used as a newline character but can
              be changed with the routine SETMIX.

                         L E G P A T

The routine  LEGPAT  stores  curve attributes plotted in le-
gends. Normally, this is done automatically by routines such
as CURVE and BARS.

The call is:  CALL LEGPAT (ITYP, ITHK, ISYM,   
                           ICLR, IPAT, ILIN)   level 1, 2, 3

ITYP          is the line style  between -1 and 7  (see LIN-
              TYP).  IF ITYP = -1,  no line will  be plotted
              in the legend line.
ITHK          defines the thickness of lines (> 0).
ISYM          is the  symbol number between   -1 and 21.  If
              ISYM = -1,  no symbol  will be plotted  in the
              legend line.
ICLR          is the  colour value  between  -1 and 255.  If
              ICLR = -1, the current colour will be used.
IPAT          is the shading pattern (see SHDPAT). If IPAT =
              -1,  no pattern  will be plotted in the legend
              line.
ILIN          is the legend line between 1 and NLIN.

Notes:     -  The routine LEGPAT is useful to create legends
              without calls to CURVE.
           -  LEGPAT must be called after LEGINI.

                         L E G O P T

The routine LEGOPT modifies the appearance of legends.

The call is:  CALL LEGOPT (XF1, XF2, XF3)      level 1, 2, 3

XF1           is a multiplier for the length  of the pattern
              field. The length is XF1 * NH, where NH is the
              current  character height.  If  XF1 = 0.,  the
              pattern field will be suppressed.
XF2           is a multiplier for the  distance  between le-
              gend frames and text. The distance is XF2 * NH
              * XSPC, where XSPC is  the spacing between le-
              gend lines (see LINESP).
XF3           is a multiplier for the spacing between multi-
              ple text lines.  The space is XF3 * NH * XLIN-
              SP.
                                   Default: (4.0, 0.5, 1.0).

5.3 Plotting Shaded Areas between Curves

                         S H D C R V

SHDCRV plots a shaded area between two curves.

The call is:  CALL SHDCRV (X1RAY, Y1RAY, N1,      
                           X2RAY, Y2RAY, N2)      level 2, 3       

X1RAY, Y1RAY  are arrays  with  the X- and Y-coordinates  of
              the  first curve.  Values are not  changed  by
              SHDCRV.
N1            is the number of points in the first curve.
X2RAY, Y2RAY  are arrays with the  X- and  Y-coordinates  of
              the second  curve.  Values are not  changed by
              SHDCRV.
N2            is the number of points in the second curve.

Notes:     -  The maximum  number of  data points  cannot be
              greater than 25000 in Fortran 77 programs.
              There is no restriction for Fortran 90 and C.
           -  Different  shading  patterns  can be  selected
              with SHDPAT. The pattern number will automati-
              cally be incremented by 1 after a call to SHD-
              CRV.
           -  Legends may be plotted for shaded curves.
           -  The routine  NOARLN will suppress border lines
              around shaded areas.

5.4 Plotting Error Bars

                         E R R B A R

The routine ERRBAR plots error bars.

The call is:  CALL ERRBAR (XRAY, YRAY, E1RAY, E2RAY, N)
                                                  level 2, 3

XRAY, YRAY    are arrays  that contain the  X- and Y-coordi-
              nates.
E1RAY, E2RAY  are arrays that contain the errors. Lines will
              be drawn from YRAY - E1RAY to YRAY + E2RAY.
N             is the number of data points.

Notes:     -  Horizontal bars will be drawn after  CALL BAR-
              TYP ('HORI').
           -  A symbol can be selected with  MARKER  and the
              symbol size with HSYMBL.


5.5 Plotting Vector Fields

                         F I E L D

The routine FIELD plots a vector field.

The call is:  CALL FIELD (X1RAY, Y1RAY, X2RAY, Y2RAY, N, 
                          IVEC)                 - level 2, 3

X1RAY, Y1RAY  are arrays that contain  the  X- and Y-coordi-
              nates of the start points. 
X2RAY, Y2RAY  are arrays that contain  the  X- and Y-coordi-
              nates of the end points. 
N             is the number of vectors.
IVEC          is a four digit number that specifies the vec-
              tor (see VECTOR).

