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