Enter your search terms Submit search form
	Web pdp-10.trailing-edge.com

.ps 63 65.ft.t Program Description 36
.c;^&ATOPLT_ INTERNALS\&
.b 2;.c;Rob Cook
.c;La Trobe University
.c;Computer Centre
.c;6-Jul-77
.hl 1 Introduction
.p;The ATOPLT package draws graphs given the points to be plotted and
certain titling information.  The package is used by calling subroutines
using a FORTRAN subroutine call interface.
ATOPLT is capable of supporting a variety of graphics devices and basic
software plotting packages.
It should be relatively easy to convert it to run on any computer
with a FORTRAN system.
.p;ATOPLT draws graphs including up to 14 discrete sets of data.  Normally scaling of the plot to fit the data is done by ATOPLT,
but the caller can use separate subroutines to change a variety of
parameters that affect the way the plot is produced.  By suitable choice
of parameters ATOPLT will window data, plot integers or text strings
as the labels at each tick, use logarithmic scales and add least squares
lines.
.p;PN-25 describes the ATOPLT package from a user's viewpoint,
and APL02.RND contains a description of the constituent files
and an installation guide.
.p;This document refers to ATOPLT version 2A(47).
.hl 1 Entry Points
.ls.lm -4
.le;ATOPLT
.p;Subroutine ATOPLT draws a graph containing up to 14 discrete
data sets.
It calls a number of subprograms to check the actual parameters (APDATA),
draw the framework and draw tick labels and axis titles (APBORD), draw
and join the data points (APLINE), add a notes box explaining each data
set (APNOTE), add least squares lines (APPLSQ, APPLSP) and close down the
plot (APCLOS).
.le;ONEPLT
.p;Subroutine ONEPLT draws a graph containing 1 data set. It is almost
identical to ATOPLT but its calling sequence is simpler.
.le;ATOLOG
.p;Subroutine ATOLOG allows the caller to specify that he wants
logarithmic scaling in the X or Y direction (or both) in subsequent
ATO- or ONEPLTs.
A call to ATOLOG causes the linking loader to load the log scaling
and labelling subprograms in preference to dummy routines that are
loaded otherwise.
.le;ATOCHL
.p;Subroutine ATOCHL allows the caller to specify character labels
that he wants used as tick labels on the X or Y axis (or both) in
future calls to ATO- or ONEPLT.
A call to ATOCHL causes the linking loader to load subprograms that
write the character labels in preference to dummy routines that are
loaded otherwise.
.le;ATOLSQ, ATOLSP
.p;The subroutines ATOLSQ and ATOLSP specify that the caller
wants least squares lines drawn on his plots for some of the data
sets plotted in future calls to ATO- or ONEPLT.
With ATOLSP the caller specifies a fixed point through which each
least squares line must pass.
Calls to ATOLSQ and ATOLSP force the linking loader to load least
squares drawing routines instead of dummies which are otherwise loaded.
.le;ONELSP
.p;ONELSP is identical to ONEPLT except that a least squares line is
added, by calling ATOLSQ before ONEPLT.
.le;SIMPLT and SIMPLS
.p;These subroutines are merely simplified versions of ONEPLT and ONEPLS.
The caller does not have to supply all the titling information which
can be confusing to a beginner.
.le;ATOPRM
.p;Subroutine ATOPRM allows the caller to alter a wide range of
parameters that affect the way that the plot is drawn (see Appendix A
of PN25 for a complete list).
For each new parameter value ATOPLT checks the value against a maximum
and minimum, which may be some other parameter or may be an absolute
value.
.le;ATOGET
.p;Subroutine ATOGET allows the caller to obtain the value of
selected ATOPLT parameters.
.els
.hl 1 Components of ATOPLT
.p;ATOPLT is divided into a large number of modules that are called
at lower levels.  All modules have names of the form AP????.  Similarly,
there are several blocks of names COMMON with names AP????.
.note *** Warning ***
Users of ATOPLT should be careful to not use names of this form to be quite safe.
.end note
.hl 1 ATOPLT's Internal Data Base
.p;ATOPLT contains several named COMMON areas containing constant data
and data that is used during plot drawing.
.ls.lm -4
.le;COMMON /APPRM/
.p;APPRM contains all the parameters whose values may be changed by
the ATOPLT caller using the ATOPRM subroutine. Its definition is
.b.c;COMMON /APPRM/APPARM(45), APLO, APHI
.p;APPARM contains the parameter values; APLO is the lowest index (1)
and APHI holds the highest index (45). Indices higher than 45 are
reserved by La Trobe University for future versions of ATOPLT.
Users should extend APPARM locally by adding zero and negative indices,
by changing all occurences of the COMMON definition and by defining
the new parameter default values and APLO value in the subroutine
APDVIC in the plotter specific files APGLD.FOR and APTEK.FOR.
.p;In addition, if new parameters are added, their limits should be
added to the arrays HICHEK and LOCHEK in the DATA statements in
subroutine ATOPRM in file APLOT.FOR.
.p;Note that all parameters in APPARM are assumed to be REALs for
checking purposes.
.le;COMMON /APFIX/
.p;APFIX contains various common parameters used throughout the
ATOPLT package.
The values of the APFIX variables are defined in subroutine APNAME in
file APNAM.FOR.
.b.lm +15.ts 20
.p -15;X = 1	X index in all the 2-membered arrays that contain both
X and Y values
.p;Y = 2	Y index
.p;RV	rounding value used in floating point calculations where rounding
is important
.p;RD	used to round to 2 decimal places
.p;LU = 6	logical unit number for writing error messages to the
user's terminal
.p;MOV = 3	code for moving the pen with pen-up in Calcomp calling
sequences
.p;DRW = 2	code for moving the pen with pen-down
.lm -15
.le;COMMON /APVER/
.p 5;APVER contains version number details. VEDIT is an INTEGER edit
number. VERSIO is a 3 membered array containing the text 'ATOPLT v:2A',
and VCHAR is the length of the VERSIO string.
VERSIO and VCHAR are used to plot the ATOPLT identification message
on each plot.
APVER data values are defined in subroutine APNAME in file APNAM.FOR.
.le;COMMON /APINT/
.p;APINT holds values that are calculated internally for each plot
and used throughout the remainder of a drawing operation.
Each member is a 2-membered array for the X and Y values.
The values are calculated in the function APDATA and in the subroutine
APAXIS.
.b.lm +15
.p -15;ORGVAL	user's data values at the origin of the plot
.p -15;ENDVAL	user's data values at the extrema of the axes
.p -15;MINVAL	minimum of all the user's data values
.p -15;MAXVAL	maximum of all the user's data values
.p -15;TIKINC	increment in user values between two adjacent ticks
.p -15;TIKVAL	user fixed value to appear at some tick. Only used if
TIKTYP is non-zero
.p -15;TIKSPC	spacing between two ticks in plotter units (mm normally)
.p -15;TIKTYP	INTEGER type of tick value fixing (0 : none, 1 : one tick
fixed, 2 : origin fixed)
.p -15;FLINT	LOGICAL flag, .TRUE. for INTEGER tick labels
.p -15;TIKSIZ	height of the major ticks in plotter units
.p -15;NUMTIK	INTEGER number of ticks along the axis
.p -15;ENDPOS	coordinates of the ends of the axes in plotter units
.lm -15
.els
.hl 1 Data Checking and Initialisation of APINT
.p 5;APDATA is called to check the data and to build APINT.
It returns .TRUE. if there is some error, .FALSE. if all was
OK.
.p;The minimum and maximum data values are obtained by subroutine
APRANG, and they are checked for log-compatibility if necessary
by APLOGN.
.p;The various data that form APINT are gathered from APPRM
and then subroutine APAXIS is called to decide the origin value,
the value increment per tick and the tick spacing based on the
tick type code.
.p;Other useful APINTs are filled in.
.hl 1 Drawing the Graph Border, Labels and Titles
.p;Subroutine APBORD is called to draw the border, and calls
subroutines APOPEN, APVERS, APFRAM, APTITL and APLABL in order.
.p;APOPEN is a basic plotting subroutine that lives in file
APSUB.FOR and issues a call to the Calcomp-like routine PLOTS.
.p;APVERS draws the ATOPLT identification, version number
and date/time stamp in the bottom left hand corner of the
plot.
.p;APFRAM draws the frame and the ticks.
Subroutine APTICK is called once for each side of the box.
APTICK starts from the end of the last side and works along
the axis drawing ticks as it goes.
.p;APLABL draws a label at every other tick along the X and
Y axes.
It calls one of the routines
.b.nf
APSLAB	for normal labels (no logarithms)
APLLAB	for logarithmicly scaled labels
APCLAB	for character labels
.f.b
depending on whether ATOLOG or ATOCHL have been called for that axis.
APSLAB and APLLAB are subdivided into routines to draw REAL or INTEGER
labels.
.p;APTITL draws a title for the X and Y axes and a title for the entire
plot.
If APSLAB was used to write labels, APTITL adds an exponent factor to
the axis title, using subroutine APPSEX.
.hl 1 Drawing and Joining the Data Points
.p;One call to subroutine APLINE draws all points of all data sets
and joins them if required.
APLINE takes each point, log scales it if required, scales it to fit
in the axes, checks whether the point is in the data window by calling
function APWIND, and draws the line (up or down) and the next point
symbol.
If only part of the line between the points is within the window,
then only that part is drawn.
A count of the points drawn for each special symbol (1-14) is kept
in array FLNOT, for use by the notes-box drawing subroutines.
.p;Function APWIND finds the endpoints of the part of the line that
is within the window.
It returns:
.b.lm +15.ts 5 15
.p -10; 1	if the end is outside the window but the start is inside
.p -10; 0	if the finish is within the window
.p -10;-1	if both points are outside the window and the line does
not cross the window at all
.b.lm -15
APWIND uses subroutine APCROS to determine whether the line crosses
the window and the coordinates of the crossing points.
APCROS in turn uses subroutine APSECT to find the intersection of
the line with each side of the window, if any.
.hl 1 Adding the Notes Box
.p 5;APNOTE checks whether there are any notes to draw.
If so it draws a box at the end of the X-axis and then looks at array
FLNOT to see which symbols were used.
For each symbol used an entry is written in the notes box, taking
the title from data supplied by the caller in the NOTES array.
The notes box is only drawn for ATOPLT calls; never for ONEPLT.
.hl 1 Log Labelling
.p;ATOLOG merely sets a flag to say that log labelling is required on
one axis or the other and makes a dummy call to an entry point in
the log label writer, to ensure that it is loaded in preference
to the dummy routine.
When ATOPLT gets to the stage of writing the tick labels, it notices
that log labelling is in force and calls the log labeller, APLLAB.
APLLAB's special trick is to add an exponent to each tick label
when the values start to get too big to fit into the normal
width for a tick value (2 decimal places).
.p;Function APLOGN is used to take the log of a number, and to check
that the number is positive before it tries.
.hl 1 Drawing Character Labels
.p;Subroutine ATOCHL remembers that character labels are to be drawn
on a particular axis, and stores the array of label texts supplied
by the user.
This implies that there is a fixed limit on the number of labels
that can be used, but the alternative, using strict FORTRAN, is
to call a user routine for the next label each time.
.p;It is assumed that the user would want to fix the origin and
increment if using character labels, so he must also supply these
values.
.p;ATOCHL calls a dummy entry to the character label drawer, APCLAB,
so that it is loaded instead of the normal dummy.
.p;APCLAB is called to draw the labels instead of the standard
labelling routine.
.hl 1 Drawing Least Squares Lines
.p;ATOLSQ and ATOLSP flag that least squares drawing is required
for certain special symbol data sets.
Again they set flags and force the loading of the least squares
line drawer by calling a dummy entry point.
.p;After the main drawing is completed, ATOPLT calls APLSQC
and if there are any lines to be added, APLSQC calculates the
lines and draws them, using APLINE to ensure the correct
windowing.
.hl 1 Getting and Setting ATOParameters
.p;ATOGET merely looks up the values in APPARM and returns them,
given that the items required exist.
.p;ATOPRM checks the range of each value before setting it into
APPARM.
The arrays HICHEK and LOCHEK tell ATOPRM how to perform the
range checks.
If the value in the check arrays is less than 1000, then the
check is made against another ATOParameter whose index is the value
in the check array.
If the value is greater than 1000, the check is made against an absolute
value, to be found in array CONST in function APPVAL.
If the check is against the plot size, the scale factor is taken into
consideration.
.hl 1 Global Subprograms
.p;There are two important functions that are used in many places
inside ATOPLT.
.p;APPWR returns the exponent e, when the number is expressed in
the form "v#*#10_^e", and 1#&<#v#<#10.
This is used to determine the number if decimal places used by a number
for plotting tick labels and exponents.
.p;APRND returns the nearest multiple of m to v.
If m is positive, the multiple is above, otherwise below.
.hl 1 Subroutine Dependencies
.p;The order of the files within the library is important because
the library file is searched sequentially and the subroutines
must be located in the correct order.
.b.nf.ts 8 16
	APLOT	main subroutine package
	APSUB	basic plot subroutine interface
	APNAM	called by ONEPLT and ATOPLT but only to
		ensure that DATA blocks are filled
	APdev	device dependant subroutine called by APNAM
		to ensure that APPARM is filled.
.f