                  Chapter 9: Utility Routines

This chapter describes  the utilities available to transform
coordinates,  sort data and calculate the lengths of numbers
and character strings.

9.1 Transforming Coordinates

The following functions  and the subroutine  TRFREL  convert
user coordinates to plot coordinates.

The calls are:  IXP = NXPOSN (X)                  level 2, 3
                IYP = NYPOSN (Y)                  level 2, 3

Plot coordinates can also be returned as real numbers.

The calls are:  XP = XPOSN (X)                    level 2, 3
                YP = YPOSN (Y)                    level 2, 3

The following two functions convert plot coordinates to user
coordinates.

The calls are:  XW = XINVRS (NXP)                 level 2, 3
                YW = YINVRS (NYP)                 level 2, 3

                         T R F R E L

TRFREL converts user coordinates to plot coordinates.

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

XRAY, YRAY    are arrays  containing  the user  coordinates.
              After the call,  they contain  the  calculated
              plot coordinates.
N             is the number of points.

Note:         The routines above can be used for linear  and
              logarithmic scaling.

                         T R F C O 1

The routine TRFCO1 converts one-dimensional coordinates.

The call is:  CALL TRFCO1 (XRAY, N, CFROM, CTO) 
                                            level 0, 1, 2, 3

XRAY          is  an  array  containing  angles expressed in
              radians  or degrees.  After a call to  TRFCO1,
              XRAY contains the converted coordinates.
N             is the number of coordinates.
CFROM, CTO    are character strings that can have the values
              'DEGREES' and 'RADIANS'.

                         T R F C O 2

The routine TRFCO2 converts two-dimensional coordinates.

The call is:  CALL TRFCO2 (XRAY, YRAY, N, CFROM, CTO)
                                            level 0, 1, 2, 3

XRAY, YRAY    are arrays containing rectangular or polar co-
              ordinates.  For  polar coordinates,  XRAY con-
              tains  the angles measured in degrees and YRAY
              the radii.
N             is the number of coordinates.
CFROM, CTO    are character strings that can have the values
              'RECT' and 'POLAR'. 

                         T R F C O 3

The routine TRFCO3 converts three-dimensional coordinates.

The call is:  CALL TRFCO3 (XRAY, YRAY, ZRAY, N, CFROM, CTO)
                                            level 0, 1, 2, 3

XRAY, YRAY,   are arrays  containing rectangular,  spherical
    ZRAY      or cylindrical coordinates.  Spherical coordi-
              nates must be in the form (longitude,latitude,
              radius) where
                       0 <= longitude <= 360   and
                     -90 <= latitude  <=  90.
              Cylindrical  coordinates  must  be in the form
              (angle, radius, z).
N             is the number of coordinates.
CFROM, CTO    are character strings that can have the values
              'RECT','SPHER' and 'CYLI'. 

9.2 String Arithmetic

                         N L M E S S

The function NLMESS returns the length of text in plot coor-
dinates.

The call is:  NL = NLMESS (CSTR)               level 1, 2, 3

CSTR          is a character string (<= 132 characters).
NL            is the length in plot coordinates.

                         T R M L E N

The function  TRMLEN returns the number  of characters  in a
character string.

The call is:  NL = TRMLEN (CSTR)            level 0, 1, 2, 3

CSTR          is a character string.
NL            is the number of characters.

                          U P S T R

UPSTR converts a character string to uppercase letters.

The call is:  CALL UPSTR (CSTR)             level 0, 1, 2, 3

CSTR          is a character string to be converted.

9.3 Number Arithmetic

                         N L N U M B

NLNUMB calculates the length of numbers in plot coordinates.

The call is:  NL = NLNUMB (X, NDIG)            level 1, 2, 3

X             is a real number.
NDIG          is the number of decimal places (>= -1).
NL            is the length in plot coordinates.

                         I N T L E N

INTLEN calculates the number of digits in integers.

The call is:  CALL INTLEN (NX, NL)          level 0, 1, 2, 3

NX            is an integer.
NL            is the number of digits.

                           F L E N

FLEN calculates the number of digits in real numbers.

The call is:  CALL FLEN (X, NDIG, NL)       level 0, 1, 2, 3

X             is a real number.
NDIG          is the number of decimal places (>= -1).
NL            is the number of digits  including the decimal
              point.  For negative numbers,  it includes the
              minus sign.

                         I N T C H A

INTCHA converts integers to character strings.

The call is:  CALL INTCHA (NX, NL, CSTR)    level 0, 1, 2, 3

NX            is the integer to be converted.
NL            is the number of digits in NX returned by INT-
              CHA.
CSTR          is the  character  string containing the inte-
              ger.

                          F C H A

FCHA converts real numbers to character strings.

The call is:  CALL FCHA (X, NDIG, NL, CSTR) level 0, 1, 2, 3

X             is the real number to be converted.
NDIG          is the number of decimal places to be conside-
              red (>= -1).
              The last digit will be rounded up.
NL            is the number of digits returned by FCHA.
CSTR          is the  character  string containing  the real
              number.

                        S O R T R 1

SORTR1 sorts real numbers.

The call is:  CALL SORTR1 (XRAY, N, COPT)   level 0, 1, 2, 3

XRAY          is an array containing real numbers.
N             is the dimension of XRAY.
COPT          defines the sorting direction.  IF COPT = 'A',
              the numbers will be sorted in ascending order;
              if COPT = 'D',  they will be sorted in descen-
              ding order.

                        S O R T R 2

SORTR2 sorts two-dimensional points in the X-direction.

The call is:  CALL SORTR2 (XRAY, YRAY, N, COPT)
                                            level 0, 1, 2, 3

XRAY, YRAY    are arrays containing the coordinates.
N             is the number of points.
COPT          defines the sorting direction.  IF COPT = 'A',
              the numbers will be sorted in ascending order;
              if COPT = 'D',  they will be sorted in descen-
              ding order.

Note:         The Shell-algorithm is used for sorting.

                        S P L I N E

SPLINE  calculates splined points  used in  CURVE  to plot a
spline.

The call is:  CALL SPLINE (XRAY, YRAY, N, XSRAY, YSRAY,NSPL)
                                               level 1, 2, 3
XRAY, YRAY    are arrays containing points of the curve.
N             is the dimension of XRAY and YRAY.
XSRAY, YSRAY  are the splined points returned by SPLINE.
NSPL          is the  number of  calculated  splined  points
              returned by SPLINE.  By default,  NSPL has the
              value 201.

Note:         The number  of  interpolated  points  and  the
              order of the  polynomials can be modified with
              SPLMOD.

                        B E Z I E R

The routine BEZIER calculates a Bezier interpolation.

The call is:  CALL BEZIER (XRAY, YRAY, N, XPRAY, YPRAY, NP)
                                            level 0, 1, 2, 3
XRAY, YRAY    are arrays containing points of the curve.
N             is the dimension of  XRAY and  YRAY   (1 < N <
              21).
XPRAY, YPRAY  are the Bezier points returned by BEZIER.
NP            is the number  of calculated points defined by
              the user.

                        H I S T O G

The routine HISTOG calculates a histogram.

The call is:  CALL HISTOG (XRAY, N, XHRAY, YHRAY, NH)
                                            level 0, 1, 2, 3

XRAY          is an  array containing floatingpoint numbers.
N             is the dimension of XRAY.
XHRAY, YHRAY  are arrays  containing  the calculated  histo-
              gram. XHRAY contains distinct values from XRAY
              sorted in ascending order.  YHRAY contains the
              frequency of points.
NH            is the number of points in XHRAY und YHRAY re-
              turned by HISTOG.

9.4 Date Routine

                        B A S D A T

The routine  BASDAT  defines the base date.  This routine is
necessary for plotting date labels and data  containing date
coordinates.

The call is:  CALL BASDAT (IDAY, IMONTH, IYEAR) 
                                            level 0, 1, 2, 3

IDAY          is the day number  of the date  between 1  and 
              31.
IMONTH        is the month number of the date between 1  and
              12.
IYEAR         is the four digit year number of the date.

                        I N C D A T

The function  INCDAT  returns the number  of days  between a
specified date and the base date.  This calculated days  can
be passed as parameters to the routine GRAF and as coordina-
tes to data plotting routines such as CURVE. 

The call is:  N = INCDAT (IDAY, IMONTH, IYEAR)
                                            level 0, 1, 2, 3

N             is the returned number of calculated days.
IDAY          is the day number  of the date  between 1  and 
              31.
IMONTH        is the month number of the date between 1  and
              12.
IYEAR         is the four digit year number of the date.

                        T R F D A T

The routine  TRFDAT calculates for a number of days the cor-
responding date.

The call is:  CALL TRFDAT (N, IDAY, IMONTH, IYEAR)
                                            level 0, 1, 2, 3

N             is the number of days.
IDAY          is the returned day number.
IMONTH        is the returned month number.
IYEAR         is the returned four digit year number.

                        N W K D A Y
 
The function NWKDAY returns the weekday for a given date.

The call is:  N =  NWKDAY (IDAY, IMONTH, IYEAR) 
                                         level 0, 1, 2, 3

N             is the returned weekday between 1 and 7 
              (1 = Monday, 2 = Tuesday, ...).
IDAY          is the day number  of the date  between 1  and 
              31.
IMONTH        is the month number of the date between 1  and
              12.
IYEAR         is the four digit year number of the date.

9.5 Bit Manipulation  

                        B I T S I 2

The routine BITSI2 allows bit manipulation on 16 bit variab-
les.

The call is:  CALL BITSI2 (NBITS, NINP, IINP, NOUT, IOUT,
                           IOPT)            level 0, 1, 2, 3

NBITS         is the number of bits to be shifted.
NINP          is a 16 bit variable from which to extract the
              bit field.
IINP          is the bit position of the leftmost bit of the 
              bit field.  The bits are numbered 0 - 15 where
              0 is the most significant bit.
NOUT          is a 16 bit variable  into which the bit field 
              is placed.        
IOUT          is the  bit  position  where  to  put  the bit
              field.
IOPT          controls whether the bits outside of the field 
              are set to zero or not.  If IOPT equal 0,  the
              bits are set to zero. If IOPT not equal 0, the
              bits are left as they are.

                        B I T S I 4

The routine BITSI4 allows bit manipulation on 32 bit variab-
les.

The call is:  CALL BITSI4 (NBITS, NINP, IINP, NOUT, IOUT,
                           IOPT)            level 0, 1, 2, 3

NBITS         is the number of bits to be shifted.
NINP          is a 32 bit variable from which to extract the
              bit field.
IINP          is the bit position of the leftmost bit of the 
              bit field.  The bits are numbered 0 - 31 where
              0 is the most significant bit.
NOUT          is a 32 bit variable  into which the bit field 
              is placed.        
IOUT          is the  bit  position  where  to  put  the bit
              field.
IOPT          controls whether the bits outside of the field 
              are set to zero or not.  If IOPT equal 0,  the
              bits are set to zero. If IOPT not equal 0, the
              bits are left as they are.
        

9.6 Byte Swapping  

                        S W A P I 2

The routine SWAPI2 swaps the bytes of 16 bit integer variab-
les.

The call is:  CALL SWAPI2 (IRAY, N)         level 0, 1, 2, 3 
 
IRAY          is an array containing the 16 bit variables.
N             is the number of variables.
    
                        S W A P I 4

The routine SWAPI4 swaps the bytes of 32 bit integer variab-
les.

The call is:  CALL SWAPI4 (IRAY, N)         level 0, 1, 2, 3 
 
IRAY          is an array containing the 32 bit variables.
N             is the number of variables.

9.7 Cursor Routines

The following routines allow an user  to collect some X- and
Y-coordinates in a graphics window with the mouse. The coor-
dinates can be returned in pixels and in DISLIN plot coordi-
nates.
 
                        C S R P T 1

The routine CSRPT1 returns the position of the mouse pointer
if  the  mouse button 1  is  pressed.  The mouse pointer  is
changed to a cross hair  pointer  in the  graphics window if
 CSRPT1 is active.

The call is:  CALL CSRPT1 (NX, NY)             level 1, 2, 3

NX, NY        are the returned  coordinates  of the  pressed
              mouse pointer.

                        C S R P T S

The routine  CSRPTS returns an array of mouse positions. The
routine is waiting for mouse button 1 clicks  and terminates
if mouse button 2 is pressed.  The mouse pointer  is changed
to a cross hair pointer in the graphics window.

The call is:  CALL CSRPTS (NXRAY, NYRAY, NMAX, N, IRET) 
                                               level 1, 2, 3

NXRAY, NYRAY  are the returned coordinates  of the collected
              mouse positions.
NMAX          is  the dimension of  NXRAY  and NYRAY and de-
              fines the maximal  number  of points that will
              be stored in NXRAY and NYRAY.
N             is the number  of points  that are returned in
              NXRAY and NYRAY.
IRET          is a returned status.  IRET not equal  0 means 
              that not all  mouse movements  could be stored
              in NXRAY and NYRAY. 

                        C S R M O V

The routine  CSRMOV returns an array of mouse movements. The
routine collects the mouse movements  of mouse button 1  and
terminates if mouse button 2 is pressed.  The mouse  pointer
is changed to a cross hair pointer in the graphics window.

The call is:  CALL CSRMOV (NXRAY, NYRAY, NMAX, N, IRET)
                                               level 1, 2, 3

NXRAY, NYRAY  are the returned coordinates  of the collected
              mouse movements.
NMAX          is the dimension of  NXRAY  and  NYRAY and de-
              fines  the maximal number  of points that will
              be stored in NXRAY and NYRAY.
N             is the number  of points  that are returned in
              NXRAY and NYRAY.
IRET          is a returned status.  IRET not equal  0 means 
              that not all  mouse positions  could be stored
              in NXRAY and NYRAY. 

                        C S R U N I

The routine CSRUNI defines if pixels or plot coordinates are
returned by the cursor routines.

The call is:  CALL CSRUNI (COPT)               level 1, 2, 3

COPT          is a character string that can have the values
              'PIXEL' and 'PLOT'.    Default: COPT = 'PLOT'.
 
Note:         Plot  coordinates can be converted to user co-
              ordinates with the routines XINVRS and YINVRS.
    
9.8 Binary I/O  

This chapter describes  the utilities available to transform
Binary I/O from Fortran can cause some problems: unformatted
IO in Fortran  is  system-dependent  and direct  access  I/O
needs a fixed record length.  Therefore,  DISLIN offers some
C routines callable from Fortran.

                        O P E N F L

The routine OPENFL opens a file for binary I/O.

The call is:  CALL OPENFL (CFILE, NLU, IRW, ISTAT)
                                            level 0, 1, 2, 3
  
CFILE         is a  character  string  containing  the  file
              name.
NLU           is the logical unit for the I/O   (0 <= NLU <= 
              99). The units 15 and 16 are reserved for DIS-
              LIN. 
IRW           defines  the  file  access  mode    (0:  READ,
              1: WRITE, 2: APPEND).
ISTAT         is the returned status (0: no errors). 
    
                        C L O S F L

The routine CLOSFL closes a file.

The call is:  CALL CLOSFL (NLU)             level 0, 1, 2, 3  

NLU           is the logical unit.
    

                        R E A D F L

The routine READFL reads a given number of bytes.

The call is:  CALL READFL (NLU, IBUF, NBYT, ISTAT) 
                                            level 0, 1, 2, 3  

NLU           is the logical unit.
IBUF          is an array where to read the bytes.
NBYT          is the number of bytes. 
ISTAT         is the number  of bytes read  (0 means  end of
              file). 
    
                        W R I T F L

The routine WRITFL writes a number of bytes.

The call is:  CALL WRITFL (NLU, IBUF, NBYT, ISTAT) 
                                            level 0, 1, 2, 3  

NLU           is the logical unit.
IBUF          is an array containing the bytes.
NBYT          is the number of bytes. 
ISTAT         is the number of bytes written (0 means an er-
              ror). 

                        S K I P F L

The routine  SKIPFL skips a number of bytes from the current
position.

The call is:  CALL SKIPFL (NLU, NBYT, ISTAT)
                                            level 0, 1, 2, 3  

NLU           is the logical unit.
NBYT          is the number of bytes. 
ISTAT         is the returned status (0: OK).
    
                        T E L L F L

The routine TELLFL returns the current position in bytes.

The call is:  CALL TELLFL (NLU, NBYT)       level 0, 1, 2, 3  

NLU           is the logical unit.
NBYT          is the  returned  position in bytes where byte
              numbering  begins with zero.  NBYT = -1, if an
              error occurs. 

                        P O S I F L

The routine  POSIFL  skips to a certain position relative to
the start.

The call is:  CALL POSIFL (NLU, NBYT, ISTAT) 
                                            level 0, 1, 2, 3  

NLU           is the logical unit.
NBYT          defines  the  position.  Byte numbering begins
              with zero. 
ISTAT         is the returned status (0: OK).
    

