----------------------------------------------------------------------------

                              LAPLOT.TXT

----------------------------------------------------------------------------
  Descriptions of the arguments and subroutines in subroutine suite LAPLOT
----------------------------------------------------------------------------
COMPUTER :       Digital PDP 11 with serial interface
PLOTTER  :       Apple LaserWriter
LANGUAGE :       RT11 Fortran IV and Macro
AUTHOR   :       Chris Bertram
                 Centre for Biomedical Engineering,
                 University of New South Wales, Australia
-----------------------------------------------------------------------------

HISTORY:-

Plotting routines by Neil Bacon of the C.S.I.R.O. were used by Rupert K.C.
Mok of the C for BME to generate a subroutine suite called WAPLOT for use
with a Watanabe WX4675 pen plotter.  The suite was subsequently modified
by C.D.B., then used as the basis of a similar suite for the LaserWriter,
to the extent that the low-level operations use the Watanabe code numbers,
e.g. I for relative draw.  It was intended that the two suites be similar
except at the lowest levels, but the project involved a re-writing of the
existing low-level routines for the Watanabe which has not happened, and
the LAPLOT suite now includes features (e.g. symbols) which were not
present in WAPLOT.

SPECIFICATIONS:-

(1) Number of axes: a maximum of 8 in either direction (horizontal or
                    vertical), or any combination giving a total number
                    less than 9, can be drawn.
   (e.g. 4 vertical axes and 2 horizontal axes giving a total of 4*2=8)

(2) Number of waveforms: a maximum of 8 waveforms can be plotted on each
                         pair of axes.

(3) Time scale: is always on the x-axis; if 'time' (xtimod(i)) is less than
                0. (no specified value), a normalised range from 0.0 to 1.0
                is assumed. [see also the description of xtimod below]
                The latest version allows X-Y & T-Y plots
                on the same graph (piece of paper) but not on the same axes.

(4) X-Y plot: {a}. on each pair of axes, a maximum of 8 pairs of different 
                   x-y plots can be obtained; the channels chosen for x or y
                   can be interchanged and repeated between x and y.
              {b}. if more than one waveform is plotted in one set of 
                   axes, the upper and lower bounds are the overall values
                   for all waveforms which share the same axis.

(5) In one LAPLOT subroutine call, both X-Y plots and T-Y plots can be
           chosen for different pairs of axes on the one piece of paper.

(6) Each pair of axes is assigned to a particular number in such a way that
           the left hand upper corner is no. 1, the one below it is no. 2,
           and so on. The number is increased downward and then further
           increased when it goes to the next row.

------------------------------------------------------------------------------

SUBROUTINE CALL:-  call laplv (nax,nay,xtimod,wave,npnt,join,ixchn,
                  &             iychn,xtil,ytil,gtil,curtil,isym)          

----------------------------------------------------------------------------

DIMENSIONS:-

xtil(i,j), ytil(i,j), gtil(j)   i: the assigned axes number
                                j: buffer capacity for the titles

ixchn(i,k), iychn(i,k), join(i,k), curtil(k), npta(i,k), isym(i,k)
         i: the assigned axes number
         k: the plotted waveform number
            e.g. ixchn(2,4)=7; in the 2nd pair of axes, the 4th plotted
            waveform is chosen from channel 7 in the array 'wave' for x axis.
         n.b. curtil is a double precision array

xtimod(i) i: the number of the x-axis

wave(l,m) is a single-precision (double in WAPLOV) real virtual array
          l: the channel number
          m: storage capacity of that channel
            m can be modified according to the amount of memory available.
            If m is changed, subroutine MXNPNT (VXNPNT for virtual arrays)
            also has to be modified accordingly.

         Note: Do not confuse m with the axes number i, the waveform number k
               and the channel number l.
         Each pair of axes can have up to eight waveforms.
         Each waveform is made up of one channel of data in a T-Y plot
         or 2 channels of data in an X-Y plot.

At present, the dimensions are i = 8
                               j = 7 (10 in gtil)
                               k = 8
                               l = 8
                               m = 1281 (641 in WAPLOV)
so that the necessary dimension statements in the calling program are:-

      virtual wave(8,1281)
      real*8 curtil(8)
      real*4 xtil(8,7),ytil(8,7),gtil(10),xtimod(8)
      integer*2 ixchn(8,8),iychn(8,8),join(8,8),npta(8,8),isym(8,8)

where dimension can replace real*4 and integer*2 in the above according to taste.

The subroutine LAPLXY is an alternative to LAPLV in which these dimensions
are varied to allow up to 16 different curves, each with a different symbol
type, on one XY-plot.  Whereas WAPLOT and its derivatives as far as LAPLV
are intended to be incorporated into the user's own program, a calling
program called XYPLOT is provided for use with LAPLXY where data are to be
entered manually.
----------------------------------------------------------------------------

ARGUMENTS:-

nax,nay
        The total number of axes on horizontal and vertical axes respectively;
        nax times nay must be less than or equal to 8.
        For the LaserWriter, nax must be negative, requesting an A4 size plot.
        By default, the longer axis is the horizontal one; a negative value
        for nay requests a plot with the longer axis vertical.

xtimod
        A real array, the element of which indicates the mode of operation 
        on the x axis designated by the array argument.
        = 0.          : X-Y plot
        = t.(constant): T-Y plot; t is divided into 5 to form labels
                        for the sub-divisions on the time axis.
        =-1.          : T-Y plot; standard or normalised time axis,
                        where the time axis is labeled from 0.0 to 1.0

wave
       Storage of 8 channels of data points. Each channel can have a
       maximum of 1281 points currently (641 in version WAPLOV).

npnt
       Number of points which are to be plotted on the specified pair of axes,
       i.e. one can have different numbers of data points plotted on different
       pairs of axes, but the number of points must be the same for waveforms
       which share the same axes.
       This restriction in LAPLOV has been removed in LAPLV, in which npnt
       has been replaced by the array npta(i,k), organised as described above
       for join, etc.

join
       Its contents indicate the width and the type (solid or dashed) of lines
       for the specified waveform; it is a 2 digit number.
       [see the description of subroutine PEN for details]

ixchn,iychn
       (1) Their contents indicate the chosen x & y channels resp. for the
           specified waveforms.
       (2) If the content is zero, a previous channel number is assumed.
       (3) If 'time' .ne. 0., all the contents of ixchn must be zeroes,
           therefore in a time-y plot program, one does not have to
           assign any data values to ixchn.
       (4) They correspond one to one,
           e.g. ixchn(1,1),ixchn(1,2),ixchn(1,3)  /1,2,3/
                iychn(1,1),iychn(1,2),iychn(1,3)  /4,5,6/
                means that in the 1st pair of axes,
                  waveform 1 is ch.1 vs ch.4
                  waveform 2 is ch.2 vs ch.5
                  waveform 3 is ch.3 vs ch.6
           if '5' & '6' are replaced by 0s, then the y-axis has all 3
           waveforms from ch.4.
           To avoid confusion it is better to put /4,4,4/ than /4,0,0/
       (5) The channel numbers can be interchanged and repeated between
           and within both axes.

xtil,ytil
       Titles on the x- & y-axis respectively.
       (1) If the first element of the title in a particular pair of axes is
           '1'-- only numerical labels are printed on that axis
           '0'--neither numerical labels nor title are printed
       (2) Maximum 28 characters for each axis title
       (3) Auto scaling of characters' size is programmed, therefore it is
           recommended that the same number of characters are used in a
           multi-axes plot.
           Note that a ' ' is also counted as one character.
       (4) If (say) the first and third elements are assigned characters but the
           second is not, the third will be printed in the place of the second.
        
gtil
       Graph title, plotted at the top of a page; the maximum number of
       characters is 40 and a fixed size is programmed.

curtil
       Curve (or waveform) title, printed on the right hand corner of each
       pair of axes with a sample of the corresponding solid or dotted line.
       This can be suppressed by assigning the string '12345678' to the
       appropriate element(s) of the array.

Remember to break up the total title string in (e.g.) gtil by data-statement
punctuation as normal, respecting the array dimensions and element lengths!

isym
       Each element is a three-digit integer prescribing the symbol type,
       size and fill for the corresponding curve by the units, tens and
       hundreds digits respectively. Thus type can take the values
       1 (circle), 2 (diamond), 3 (square), 4 (triangle), 5 (inverted
       triangle). Fill may have the values 0 (outline only), 1 (filled,
       i.e. black) and 2 (half-filled).
       If isym(i,k) is negative, lines between the symbols are omitted.
       If isym(i,k) is zero, symbols are omitted.

--------------------------------------------------------------------------------

SUBROUTINES CALLED BY LAPLV:-

(1) GRID (nax,nay,ixdim,iydim,ixo,iyo,ia,iv,ixgap,iygap,
          ixstt,ityn,itxn,iystt,lxoffx,lyoffx,lxoffy,lyoffy,
          iszn,insetx,insety,icusiz,length,iyspc,iszct,iszgt)

    specifies the device-dependent (LaserWriter or Digi-Plot) co-ordinate
    grid limits.  See the comments within GRID for explanation of the
    arguments.  Ideally(!) only this subroutine and the low-level SEND
    would require changing to convert the whole subroutine suite for use
    with another plotter device.  In practice this has not been realized, 
    due mainly to differences in start-up procedures and command syntax.

(2) MXNPNT (wave,nptchn,rmax,rmin)
           finds the max. and min. values for each channel in array 'wave'.
    {a}. 'nptchn(j)' is the number of points (starting from 1) from 'wave',
         to be plotted; within this range, the max. & min. are found.
         j is the channel number as in 'wave'
         nptchn(j)=n, n must be less than or equal to the dimension m of
         array 'wave' (currently 161 in WAPLOT and MXNPNT, 641 in WAPLOV
         and VXNPNT.
    {b}. ll channels' max. & min. values are stored in array 'rmax(8)'
         & 'rmin(8)'; 0s are assigned if the channel no. is not called
         (i.e. nptchn(j)=0 ).
    {c}. Version VXYPNT instead of VXNPNT is called by LAPLXY.

(3) IOVIR
         is called if TSX+ is running to change the mapped I/O page from
    the last 4k words of low memory (PAR 7) to the penultimate 4k (PAR 6)
    to avoid a clash with the use of PAR 7 for handling Fortran virtual
    arrays under TSX+.

(4) SENDL - see below

(5) EXTREM (rmax,rmin,rup,rlo,ntic,tico,ticp,ticlen,ialgm)
           given as input the maximum and minimum of the axis data,
    finds rounded-off upper and lower bounds for the axis,
    the no. of ticks, length between ticks, and the values for the
    first and the last (lowest and uppermost) ticks.
    Subroutine ROUNF is called to find the above values for positive
    max. and min. inputs; EXTREM adjusts the input and output values
    to suit 3 cases:     max.         min.
                         positive     negative
                         positive     positive
                         negative     negative
    In the first case subroutine TICKS is also called by EXTREM.
    {a}. rmax-     input maximum
    {b}. rmin-     input minimum
    {c}. rup -     round-off upper value
    {d}. rlo -     round-off lower value
    {e}. ntic-     number of ticks on the axes
    {f}. tico-     value for the lowest tick
    {g}. ticp-     value for the uppermost tick
    {h}. ticlen-   length between the uppermost and lowest ticks
    {i}. ialgm -   equal to either 1 or 2, the algorithm which is used
                   to determine the number of ticks.
   
   EXTREM and its subroutines were written by R.M. to provide a better
   solution than the usual algorithms to the problem of providing round-
   number axis graduations without large amounts of wasted space at the
   extremities of the data and without resorting to large numbers of
   graduations.  The resulting algorithm is complex, and the code is
   hard to follow.  Occasionally the algorithm chooses a way of dividing
   the axis that seems idiosyncratic, but problems of this nature can be
   overcome by plotting isolated well-chosen data points that force the
   algorithm to recalculate.  Caveat: the algorithm is not fool-proof;
   it is expected that the user will plot data in units that allow a
   data range between about one and a few thousand.

(6) LINTYP (ilnpen)

       ilnpen is a two-digit integer.
       The ten digit denotes line type (0-9)
              0: solid line
            1-9: broken line, half-pitch = (1-9)*10 units
       The unit digit denotes pen no., i.e. line width (1-6)

(7) LADRAW (ibit1,ibit2,ixp1,iyp1,ixp2,iyp2,mode,iasc,iarq,isym,
            inter,rumbr,char4,char8,log)

    is a multi-function subroutine to command the operations
    of the plotter.

     ibit1  ibit2   operation 1           operation 2
                    to 1st coord.         to 2nd coord.

       0      0     abs. move             abs. draw
       0      1          "                rel.   "
       1      0     rel. move             abs. draw
       1      1          "                rel.   " 
       2      2     abs. draw             abs. move
       2      3          "                rel.   "
       3      2     rel. draw             abs. move
       3      3          "                rel.   "
       4      0     abs. move to 1st coord.
       5      0     rel. move       "
       6      0     abs. draw       "
       7      0     rel. draw       "            

     mode 1: mark with different symbol (isym = 1 to 6)
          2: print number with an integer input, field: i5
          3: print number with a real no. input, field: f5.0
          4: print number with a real no. input, field: f5.1
          5: print number with a real no. input, field: f5.2
          6: print characters with Real*4 as input (normal form)
          7: print characters with Real*8 as input (double precision)
          8: print characters with Logical*1 as input

     iasc, iarq are the scale and rotation of characters, which
                must be specified for modes 6-8.
     inter stores the numerical labels (mode 2);
     rumbr stores the numerical labels (mode 3-5).
     char4 stores the title for mode 6;
     char8 stores the title for mode 7;
     log   stores the title for mode 8.

    LADRW is a later version of LADRAW which calls subroutine ASMBL.

(7) AXISLW (ixy,intlen,intnos,ixorn,iyorn)

           draws an x or y axis from the specifed origin.

    {a}. ixy=0 draw y axis
             1 draw x axis
    {b}. ixorn,iyorn is the start origin
    {c}. intlen is the length of interval between ticks
    {d}. intnos is the number of intervals (no. of ticks=intnos+1)

(8) PARSE (tchar,mxchr,nchar)

     rearranges the characters in a title so that no more than one space
     separates words, and returns the total number of characters up to
     the last non-space. The parameter nchar must be supplied when the
     routine is called; it should be minimised by prior use of 'len',
     as in LAPLV.

--------------------------------------------------------------------------------

LOWER-LEVEL SUBROUTINES:-

(1) DIGIT (reval,baseln,idig)
          finds each digit of the input real value 'reval', storing them
    in the array 'idig', and baseln, the multiplier of the first digit
    of the real input number (e.g. baseln = 10 for reval = -15.7).

(2) ROUNF (rmax,rmin,iaxdig,iindig,raxbas,rinbas,rup,rlo,ntic,tico,
           ticp,ticlen,ilogm)
    is called by EXTREM to find upper, lower values of the axes and 
    the ticks; also finds the no. of ticks and the length between
    upper & lower ticks by assuming rmax and rmin are positive.

(3) TICKS adjusts the no. of ticks according to the distance between them

(4) ROTAT (ntimes)

     rotates characters anticlockwise by 90 degrees ntimes (0-3)
     w.r.t. the x-axis.

     The coordinate frame stays rotated until ROTAT is called
     again with the corresponding negative argument.

(5) SIZ (isize)

     sets the size of characters according to the supplied integer (0-15)

(6) LPR (text,n)

     prints the given text on the LaserWriter page


(7) PEN, BROK

     PEN (iwhich) sets line width according to the supplied integer (1-6)

     BROK (lpitch,lgap) receives broken line pitch and mark/space ratio
     in 0.1mm units, which are converted to 1/72" units.

(8) ASMBL (ismbl,ix,iy)

     draws a data symbol at the point ix,iy according to the
     instructions supplied by the ismbl digits: iwhich (1-5)
                                                isize  (0-9)
                                                ifill (0 1 or 2)
     For example ismbl = 152 means fill a size-5 diamond.
     ismbl is set negative by the subroutine to indicate that a symbol
     procedure has been defined and can be used subsequently.  The
     argument ismbl encodes all but idone of the arguments iwhich, idone,
     isize and ifill for the earlier routine SSMBL, which was itself a
     version of SMBL using Postscript procedure definitions.

(9) IEVEN, IRND are statement functions which return the nearest round
                or even integer to the real number supplied.

(10) AXL (ixy,lseg,nseg)

     draws an axis on the Laserwriter page. The arguments are
     specified as for the corresponding WX4675 command.

(11) HMARK draws a horizontal subdivision of the vertical axis being
      produced by AXL, which calls this routine.

     VMARK draws a vertical subdivision of a horizontal axis.

(12) IDIGT (input,iunit,itens,ihund,ithou)

     returns the values of the digits making up the supplied integer,
     currently up to a maximum size for input of 9999.  It is called by
     ASMBL to decode the argument ismbl.

(13) LGO (how,ix,iy)

     is a graphical primitive for the LaserWriter.
     The variable 'how' is encoded as for the Watanabe plotter.

      how = 'M' 	 move to absolute ix,iy
      how = 'R' 	 move to relative ix,iy
      how = 'D' 	 line to absolute ix,iy
      how = 'I' 	 line to relative ix,iy

(14) SENDL (pltcmd,nchar)
          transfers the commands through the interface to the plotter,
          and tests the transfer & receive operations
    {a}. pltcmd-  the array of command characters
    {b}. nchar -  the number of characters to be transferred
---------------------------------------------------------------------
                         END
---------------------------------------------------------------------
                                                                                                                                                                                                                                                                                                                                                                                          