Google
 

Trailing-Edge - PDP-10 Archives - decus_20tap4_198111 - decus/20-0126/apint.mem
There is 1 other file named apint.mem in the archive. Click here to see a list.
Program Description 36                                     Page 1


                        ATOPLT INTERNALS
                        ----------------


                            Rob Cook
                       La Trobe University
                         Computer Centre
                            6-Jul-77



1.0  INTRODUCTION

     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.

     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.

     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.

     This document refers to ATOPLT version 2A(47).



2.0  ENTRY POINTS

 1.  ATOPLT

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

 2.  ONEPLT

          Subroutine ONEPLT draws a graph containing 1 data  set.
     It is almost identical to ATOPLT but its calling sequence is
     simpler.

 3.  ATOLOG

          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
Program Description 36                                     Page 2


     subprograms in preference to dummy routines that are  loaded
     otherwise.

 4.  ATOCHL

          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.

 5.  ATOLSQ, ATOLSP

          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.

 6.  ONELSP

          ONELSP is identical  to  ONEPLT  except  that  a  least
     squares line is added, by calling ATOLSQ before ONEPLT.

 7.  SIMPLT and SIMPLS

          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.

 8.  ATOPRM

          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.

 9.  ATOGET

          Subroutine ATOGET allows the caller to obtain the value
     of selected ATOPLT parameters.




3.0  COMPONENTS OF ATOPLT

     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????.
Program Description 36                                     Page 3


                         *** Warning ***

               Users of ATOPLT should  be  careful
               to not use names of this form to be
               quite safe.





4.0  ATOPLT'S INTERNAL DATA BASE

     ATOPLT  contains  several  named  COMMON  areas   containing
constant data and data that is used during plot drawing.

 1.  COMMON /APPRM/

          APPRM contains all the parameters whose values  may  be
     changed  by  the  ATOPLT caller using the ATOPRM subroutine.
     Its definition is

              COMMON /APPRM/APPARM(45), APLO, APHI

          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.

          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.

          Note that all parameters in APPARM are  assumed  to  be
     REALs for checking purposes.

 2.  COMMON /APFIX/

          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.


     X = 1          X index in all  the  2-membered  arrays  that
                    contain both X and Y values

     Y = 2          Y index

     RV             rounding  value  used   in   floating   point
                    calculations where rounding is important

     RD             used to round to 2 decimal places
Program Description 36                                     Page 4


     LU = 6         logical  unit  number   for   writing   error
                    messages to the user's terminal

     MOV = 3        code  for  moving  the  pen  with  pen-up  in
                    Calcomp calling sequences

     DRW = 2        code for moving the pen with pen-down

 3.  COMMON /APVER/

          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.

 4.  COMMON /APINT/

          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.


     ORGVAL         user's data values at the origin of the plot

     ENDVAL         user's data values at the extrema of the axes

     MINVAL         minimum of all the user's data values

     MAXVAL         maximum of all the user's data values

     TIKINC         increment in user values between two adjacent
                    ticks

     TIKVAL         user fixed value  to  appear  at  some  tick.
                    Only used if TIKTYP is non-zero

     TIKSPC         spacing between two ticks  in  plotter  units
                    (mm normally)

     TIKTYP         INTEGER type of tick value fixing (0 :  none,
                    1 :  one tick fixed, 2 :  origin fixed)

     FLINT          LOGICAL flag, .TRUE.  for INTEGER tick labels

     TIKSIZ         height of the major ticks in plotter units

     NUMTIK         INTEGER number of ticks along the axis

     ENDPOS         coordinates  of  the  ends  of  the  axes  in
                    plotter units
Program Description 36                                     Page 5


5.0  DATA CHECKING AND INITIALISATION OF APINT

     APDATA is called to check the data and to build  APINT.   It
returns .TRUE.  if there is some error, .FALSE.  if all was OK.

     The  minimum  and  maximum  data  values  are  obtained   by
subroutine  APRANG, and they are checked for log-compatibility if
necessary by APLOGN.

     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.

     Other useful APINTs are filled in.



6.0  DRAWING THE GRAPH BORDER, LABELS AND TITLES

     Subroutine APBORD is called to draw the  border,  and  calls
subroutines APOPEN, APVERS, APFRAM, APTITL and APLABL in order.

     APOPEN is a basic plotting subroutine  that  lives  in  file
APSUB.FOR and issues a call to the Calcomp-like routine PLOTS.

     APVERS draws the ATOPLT identification, version  number  and
date/time stamp in the bottom left hand corner of the plot.

     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.

     APLABL draws a label at every other tick along the X  and  Y
axes.  It calls one of the routines

APSLAB              for normal labels (no logarithms)
APLLAB              for logarithmicly scaled labels
APCLAB              for character labels

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.

     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.



7.0  DRAWING AND JOINING THE DATA POINTS

     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
Program Description 36                                     Page 6


drawn  for each special symbol (1-14) is kept in array FLNOT, for
use by the notes-box drawing subroutines.

     Function APWIND finds the endpoints of the part of the  line
that is within the window.  It returns:


     1         if the end is outside the window but the start  is
               inside

     0         if the finish is within the window

     -1        if both points are outside the window and the line
               does not cross the window at all

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.



8.0  ADDING THE NOTES BOX

     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.



9.0  LOG LABELLING

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

     Function APLOGN is used to take the log of a number, and  to
check that the number is positive before it tries.



10.0  DRAWING CHARACTER LABELS

     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.
Program Description 36                                     Page 7


     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.

     ATOCHL calls a dummy entry to the  character  label  drawer,
APCLAB, so that it is loaded instead of the normal dummy.

     APCLAB is called to draw the labels instead of the  standard
labelling routine.



11.0  DRAWING LEAST SQUARES LINES

     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.

     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.



12.0  GETTING AND SETTING ATOPARAMETERS

     ATOGET merely looks up the  values  in  APPARM  and  returns
them, given that the items required exist.

     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.



13.0  GLOBAL SUBPROGRAMS

     There are two important functions  that  are  used  in  many
places inside ATOPLT.

     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.

     APRND returns the nearest multiple of  m  to  v.   If  m  is
positive, the multiple is above, otherwise below.
Program Description 36                                     Page 8


14.0  SUBROUTINE DEPENDENCIES

     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.

        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.