Chapter 9: Utility Routines
This chapter describes the utilities available to transform coordinates,
sort data and calculate the lengths of numbers and character strings.
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.
- 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'.
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.
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:
- The Watson algorithm is used for calculating
the Delaunay triangulation. The algorithm increases with the
number of points as approximately O(N^{1.5}).
Reference: S.W. Sloan and G.T. Houlsby, An Implementation of
Watson's algorithm for computing 2-dimensional Delaunay
triangulations, Advanced Engineering Software, 1984, Vol. 6,
No. 4.
- Surfaces and contours can be directly plotted from the
triangulation with the routines CRVTRI, SURTRI and CONTRI.
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.
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.
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.
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.
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.
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