                  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 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.5 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.6 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).
    

