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:

Plot coordinates can also be returned as real numbers.

The calls are:

The following two functions convert plot coordinates to user coordinates.

The calls are:

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.

Additional 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 coordinates. For polar coordinates, XRAY contains 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, ZRAY
are arrays containing rectangular, spherical or cylindrical coordinates. Spherical coordinates 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 coordinates.

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 INTCHA.
CSTR
is the character string containing the integer.
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 considered (>= -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 descending 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 points will be sorted in ascending order; if COPT = 'D', they will be sorted in descending order.

Additional 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 200.

Additional 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 histogram. 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 returned by HISTOG.
T R I A N G

The routine TRIANG calculates the Delaunay triangulation of an arbitrary collection of points in the plane. The Delaunay triangulation can directly be used to display surfaces and contour lines of irregularily distributed data points.

The call is:
The call is: CALL TRIANG (XRAY, YRAY, N, I1RAY, I2RAY, I3RAY, NMAX, NTRI) - level 0, 1, 2, 3
XRAY, YRAY
are arrays containing floatingpoint numbers. The dimension of XRAY and YRAY must be greater or equal N + 3.
N
is the number of points in XRAY and YRAY.
I1RAY, I2RAY, I3RAY
are the returned vertices for each triangle in anticlockwise order.
NMAX
is the dimension of I1RAY, I2RAY and I3RAY. NMAX must be greater of equal 2 * N + 1.
NTRI
is the returned number of triangles.
Additional notes: C I R C 3 P

The routine CIRC3P calculates a circle specified by three points.

The call is:
CALL CIRC3P (X1, Y1, X2, Y2, X3, Y3, XM, YM, R) - level 0, 1, 2, 3
X1, Y1
are the X- and Y-coordinates of the first point.
X2, Y3
are the X- and Y-coordinates of the second point.
X3, Y3
are the X- and Y-coordinates of the third point.
XM, YM
are the calculated coordinates of the centre point.
R
is the calculated radius of the circle.

9.4 Date Routines

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 coordinates 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 corresponding 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 variables.

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

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

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

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 coordinates can be returned in pixels and in DISLIN plot coordinates.

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 defines 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 defines 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'.
Additional note:
Plot coordinates can be converted to user coordinates 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 DISLIN.
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 error).
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).

Next | Previous | Contents