Appendix B: PPLUS Users Guide 

Note: This is the Users Guide for PPLUS, also called Plot Plus, a Scientific Graphics System written by  Donald W. Denbo  April 8, 1987. Its graphics calls are the basis for Ferret's graphics. In this appendix the PPLUS Users Guide is included unchanged, except for formatting changes and without its table of contents or index to avoid confusion. Note that some of the information is not relevant to the purpose of making PPLUS calls from Ferret. If there are differences, adhere to the information in the main Ferret Users Guide. See particularly the chapter  "Customizing Plots" in the Ferret Users Guide (p. 183) for discussion of how Ferret interacts with PPLUS 

Appendix B Sec1  INTRODUCTION 

 Plot  Plus  (PPLUS)  is   an   interactive,   command-driven general-purpose  program  for plotting user supplied data. PPLUS  recognizes data in standard Fortran  formatted,  unformatted  and free  format  files  as well as some specialized formats (see the  section on Data Formats). Data can  also  be  entered  from  the keyboard. 

The major use of PPLUS is the plotting of contour  data  and  X-Y  pairs. A  very  small  number  of commands are required to  generate a plot, making  use  of  the  many  defaults  available. However,  it  is  also possible to control almost every aspect of  the plot and to generate a final product which looks as though it  were  professionally  drafted. Over  thirty  character sets are  available, including special  Greek  and  Math  symbols. It  is  possible  to make a composite of several plots of different kinds  (or the same kind) on a single page and to add  text  information  anywhere on the plot. 

 PPLUS  commands  can  be  entered  interactively  from   the  keyboard or from a command file much like a VAX/VMS command file. PPLUS   command   files   support   parameter   passing,   symbol  substitution,  and logic structures such as WHILE loops and block  IF statements. The PPLUS command files  are  simple  ASCII  disk  files which are easily edited with any VAX/VMS editor. 

Interactive help is available with the VAX/VMS command  HELP  PPLUS. (First,  PPLUS definitions must have been established as  indicated in the Getting Started chapter.)
 

Appendix B Sec2  GETTING STARTED 

Appendix B Sec2.1  VAX/VMS 

To get a copy of this manual, type the  following  lines  on your terminal in response to the VAX/VMS prompt: 

  $ @DISK1:[OC.SYMBOLS]PLOT5
 $ PPLUS_MANUAL
 $ PPLUS_FONTS 

  The manual will be printed on the laser printer,  and  the  PPLUS  character fonts will be plotted on the Versatec plotter. 

Appendix B Sec2.2  Required Definitions 

PPLUS  requires  several  assignments  and  definitions   to   execute  under  VMS. The  following  should be included in your  LOGIN.COM file prior to running PPLUS: 

  $ @DISK1:[OC.SYMBOLS]PLOT5.COM
 $ GRAPHTERM :== xxxx,
 

  where xxxx describes your graphics terminal and has the following  allowed values: 

    VT240
   GVT+
   ZENITH
   TEK4010
   MAC
   TEK41XX
   TEK4105
   TAB 

  In order to provide automatic entry and  exit  into  and  out  of   graphics  mode  you  should use the GRAPHTERM that corresponds to   your  terminal. If  your  terminal  is  a  TEK4010  or  TEK4014   compatible,  but  not  one of the above, then place your terminal   into graphics mode before plotting and use GRAPHTERM :== TEK4010. The  execution  of PLOT5.COM will define any other symbols needed by PPLUS. 

PPLUS is entered interactively by typing PPLUS (or just PPL)   in response to the VAX/VMS prompt. 

 Interactive help  is  available  by  typing  HELP  PPLUS  in   response  to  the  VAX/VMS  prompt. If you are in PPLUS, help is   available by typing HLP. 

Appendix B Sec2.2.1  Optional Definitions 

 In addition to the above, the following VAX/VMS symbols  and logicals may optionally be defined by the user: 

Example definitions: 

DEFINE PPL$RESET DISK1:[your-directory]your-reset.file
DEFINE ECHO your-echo.file
PPL$STARTUP :== DISK1:[your-directory]your-startup.file 

Appendix B Sec3  COMMAND FORMAT 

Appendix B Sec3.1  THE COMMANDS 

The basic format for PPLUS commands is: 

COMM[/Q1/Q2 ... ][,arg1,arg2,arg3...][,sarg1,sarg2...] 

where  COMM  is  the  PPL   command. The numeric arguments arg1,arg2,... may be numbers in any fortran format (e.g. 1.E-5,  -6,  10.23)   or   blank. The   character   string   arguments           sarg1,sarg2,... must  begin with a non-numeric character string or be enclosed in quotes ("), i.e., "100". If  the  numeric  or character  string  arguments  are  blank, the input is considered null and the default is used. Where all numeric arguments are to be  defaulted,  they may be omitted entirely (i.e., blank entries need not be made). 

 PPLUS commands may have optional qualifiers (Q1, Q2 etc...). The  format  for qualifiers is "/value" or "/novalue" for true or false, respectively.  

All parameters must be separated by commas or blanks, except null entries which must have separating commas. Null entries are allowed except where noted in the specific command description. 

Note that if you use commas, a blank followed by a comma will be interpreted as a null entry. e.g. 

PPL AXLEN  2 , 1           ! Is interpreted as   PPL AXLEN 2(, null)
PPL AXLEN  2, 1            ! Is interpreted as   PPL AXLEN 2,1
PPL AXLEN  2  1            ! Is interpreted as   PPL AXLEN 2,1 

Commands can be continued on sequential lines by inserting a "-" (minus sign) at the end of the line to be continued. 

 All commands/parameters may be entered upper or lower  case. Conversion   to   upper  case  is  performed  automatically  when required. 

Appendix B Sec4  COMMAND SYNOPSIS 

This is intended as a brief overview of the PPLUS  commands. Commands  are fully described in the Command Description chapter. Examples illustrating  their  use  are  in  the  Beginners  Guide section. 

Appendix B Sec4.1  FILES 

Appendix B Sec4.1.1   Data Files 

These commands are used to extract the  information  from  a file containing the data to be plotted. 

Appendix B Sec4.1.2   Other Data Entry 

The following commands allow data entry from a  souce  other than a file. 

ENTER   Allows data entry from the keyboard. 

LINFIT  Does a linear least squares fit on data already in a line and inserts the least squares line into the next available line. 

Appendix B Sec4.1.3  PPLUS Output Files 

Appendix B Sec4.1.4   PPLUS Command Files 

Appendix B Sec4.2  AXIS 

     The  following   commands   control   axis   labelling   and appearance. 

Appendix B Sec4.2.1  X- And Y-axis 

XAXIS    Controls numeric labeling and tics on the x-axis. 

YAXIS    Controls numeric labeling and tics on the y-axis. 

AXATIC    Sets number of large tics automatically for x and y. 

AXLABP    Locates axis labels at top/bottom or left/right of plot. 

AXLEN    Sets axis lengths. 

AXLINT    Sets label interval for axes. 

AXLSZE    Sets axis label heights. 

AXNMTC  Sets number of small tics between large tics on axes. 

AXNSIG     Sets no. significant digits in numeric axis labels (auto only). 

AXSET    Allows omission of plotting of any axis. 

AXTYPE    Sets axis type for x- and y-axis. 

TICS    Sets axis tic characteristics 

XFOR    Sets format of x-axis numeric labels. 

YFOR    Sets format of y-axis numeric labels. 

XLAB    Sets label of x-axis. 

YLAB    Sets label of y-axis. 

Appendix B Sec4.2.2  Time Axis 

TIME    Sets start and end of time axis, start time of data. 

TAXIS    Sets time axis on, sets time series delta-t (minutes),orients axis. 

TXLABP    Establishes time axis label position (or absence). 

TXLINT    Specifies which tics will be labeled. 

TXLSZE    Sets height of time axis labels. 

TXNMTC Sets number of small tics between large tics. 

TXTYPE     Sets type and style of time axis. 

Appendix B Sec4.3   LABELS 

LABS    Makes a moveable label (up to 25 labels allowed). 

HLABS    Sets height of each moveable label. 

RLABS    Sets angle for each moveable label. 

LABSET    Sets character heights for labels. 

LLABS    Sets start position for a line to location of each moveable label. Draws a line from the label to a point. 

CONPRE    Sets prefix for contour labels (characters, color, font). 

CONPST    Set suffix for contour labels (characters, color, font). 

TITLE    Sets and clears main plot label (without making a plot). 

XLAB    Sets label of x-axis. 

YLAB    Sets label of y-axis. 

Appendix B Sec4.4  COMMAND PROCEDURES 

@     Initiates reading of commands from a PPLUS command file. 

DEC      Decrements a counter. 

INC    Increments a counter. 

IF        Block IF statement. 

ELSE    Block IF statement. 

ENDIF    Block IF statement. 

WHILE    WHILE loop construct. 

ENDW     WHILE loop construct. 

SET     Sets the value of a PPLUS symbol. 

SHOW     Shows the value of a PPLUS symbol. 

LISTSYM  Lists values of defined PPLUS symbols. 

Appendix B Sec4.5  COLOR AND FONTS 

 Commands to change the pen number or the character font  can be  embedded  in  any labels character string. See the preceding section for label commands and the chapter on LABELS. 

@Pn    Sets pen number "n" when embedded in a label, where n is less than 10 

@Cnnn    Sets color to number "nnn" when embedded in a label. 

PEN    Sets pen number for each data line. 

DFLTFNT Sets default character font for all labeling. 

LEV    Sets pen numbers (colors) for contour plots. 

Appendix B Sec4.6   PLOT APPEARANCE 

 The following commands control various aspects of the plot's appearance. 

ORIGIN    Sets distance of plot origin from lower left corner of the box. 

SIZE    Sets size of entire plotting region. 

BOX    Controls drawing of a box around the entire plotting region. 

CROSS    Controls drawing of lines through the point x=0, y=0 on graph. 

LINE    Sets characteristics for each X-Y plot line. 

MARKH    Sets character size for each X-Y plot line marks. 

MULTPLT Allows a composite of several plots (all kinds) on onepage. 

ROTATE    Rotates plot by 90 degrees on screen and plotter. 

Appendix B Sec4.7   PLOT GENERATION 

The following commands select the plot type and generate the plot. 

PLOT    Plots x-y pairs for all lines of data. 

PLOTUV    Makes stick plot of vector data for U,V pairs in line1. 

PLOTV    Makes stick plot of vector data for U in line1 and V in line2. 

CONTOUR Makes contour plot. 

VIEW    Makes a 3-D surface plot. 

VPOINT    Sets the viewpoint for a 3-D surface plot. 

VECTOR     Makes a plot of a vector field 

VELVCT     Makes vector plot of U,V pairs located at X,Y locations. 

MULTPLT Allows a composite of several plots (all kinds) on one page. 

Appendix B Sec4.8  DATA MANIPULATION 

LINFIT        Does a linear least squares fit on data already in a line and inserts the least squares line into the next  available line. 

TRANSXY     Applies a linear transformation to variables x and y. 

SMOOTH      Controls smoothing of contour type data. 

LIMITS          Sets testing values for good data points. 

WINDOW      Controls windowing of data within axis bounds. 

Appendix B Sec4.9  HELP 

HELP     VAX/VMS on-line help for PPLUS. 

HLP    Access on-line help from within PPLUS. 

Appendix B Sec5  BEGINNERS GUIDE 

To use PPLUS a minimum of preparation is required. See  the chapter  on  Getting  Started for the symbol definitions that are required. Once this has been done PPLUS can be entered by typing PPLUS (or just PPL) in response to the VAX/VMS prompt. 

The minimum number of commands needed to read  in  data  and then  plot  the data are:  FORMAT (sets the input format), SKP (a command to position the file to a  given  record). VARS  (tells PPLUS  how  the  data is arranged in each data record), RD (reads the data) and PLOT (create the plot) or CONTOUR (create a contour plot). The name of the file containing the data can be specified with the RD or SKP commands. Following are discussions of  these commands  and  some examples of how these commands are used. For more information see the Command Description chapter. 

Appendix B Sec5.1  FORMAT 

FORMAT informs PPLUS the type  of  the  data  file  and  the format the data has within this file. Valid formats are: 

 UNF   -- the data is unformatted  (data type REAL) 

 FREE  -- the data is formatted and in free form 

 (xxx) -- the data is formatted with a format of xxx, where xxx is a legal FORTRAN format, i.e., (3F10.2) 

Appendix B Sec5.2  5.2  VARS 

The next command you need to know about is VARS. VARS is  a complicated  command  because  it allows great flexibility in the organization of the data within each file  record. Position  of the  characters  1,  2,  and  3 within the command line indicates the  position of the X, Y, and Z variables  within  the  data  record. The format of the command is: 

      VARS,NGRP,A1, ... ,Ai 

 where i is the number of data values per data group 

NGRP = number of groups per record. For example, if the data file has Depth,Temperature pairs packed 3 pairs per record with a format of 3(F6.1,F6.2) then NGRP=3. 

Aj = 1, 2, 3 or blank to indicate that the variable in this position within the group is to be plotted as X (Aj = 1), Y (Aj = 2), Z (Aj = 3), or is not to be read at all (Aj = blank). An example will make this clearer. 

     EXAMPLE:   VARS,1,,2,1 

     First arg is 1 -->      there is only 1 group per record (e.g. 1 scan per line of data) in the data file 

   Second arg is blank --> Variable 1 in the data record is not to be read. (A1 = blank) 

   Third arg is 2 -->      Variable 2 in the data record is to be plotted as Y (A2 = 2) 

   Fourth arg is 1 -->     Variable 3 in the data record is to be plotted as X (A3 = 1) 

   No variable is to be read as Z. 

The default is VARS,1,1,2 (i.e. one group per record, first variable is X, second is Y) 

The following are examples of the VARS command. 

VARS,1,,,1  tells PPLUS that there is one group of  data  per>record  and  to  read  the  third  number  in the record as the X variable. Since no Y variable location has been specified the  Y variable will contain the sequence number. VARS,5,1,2 lets PPLUS know that there  are  five  groups  of data  pairs  per record. Again the X variable is first and the Ysecond. 

VARS,1,1,2,3  informs PPLUS that the data is  X,Y,Z  triplets with  one  group  per  record. The fact that X,Y, and Z appears tells PPLUS that the data is not on  a  regular  grid  and  PPLUS should  place  it  on an even grid. The method used to place the data on a regular grid and the grid itself are determined by  the RD and CONSET commands. 

VARS,1,,,,2,1 tells PPLUS that there is one  group  of  data per  record  where  the Y variable is the fourth number and the X the fifth number in the record. 

VARS,1,3 tells PPLUS that there is one  group  of  data  per record  and  Z  is  the  only variable in the group. This is for contour data which is already gridded. The  RD  command  defines how the data is stored, i.e., which index varies fastest. 

Appendix B Sec5.3  SKP AND RD 

The name of the file containing the data to be  plotted  can be  specified  with  either  the  SKP or the RD command. The SKP command tells PPLUS to skip  records  in  the  data  file  (e.g., header  records or data which should not be plotted). Its format is SKP,N,FILE_NAME where N is the number or records to skip,  and FILE_NAME  is  the  name  of  the  data  file  and is an optional parameter. If the name of the data file is  included,  the  data file  will  be rewound before skipping. If the data file name is omitted, the file will not be rewound before skipping. 

The RD command informs PPLUS how many records  to  read  and what  file  to  read  them from. If you are not making a contour plot, the format of the command is RD,NX,FILE_NAME  where  NX  is the  number of points to read from the data file and FILE_NAME is the name of the data file and is an optional parameter. If  the data  file name is included, the data file will be rewound before the data is read. If the data file name  is  omitted,  the  file will not be rewound before reading. 

If you are making a contour plot, the RD command  format  is somewhat  different. If  Z  is  being  read  (a  3  in the VARS command), RD defines the size of the plotting  grid  and  prompts the user for the minimum and maximum values of X and Y to be used for   the   plotting   grid. The format for RD is 

RD,NX,NY,TYPE,FILE_NAME  where NX and NY set the size of the grid for contour data read. Specifically,  when  X,Y,Z  triplets  are being  read for contouring, the grid on which the data is plotted can be either coarser or finer or the same as the input data. If NX=50 and NY=21, then the data will be plotted on a grid which is 50 x 21 points (regardless of input  data  limits  or  gridding). TYPE  tells  PPLUS  whether  the data is stored by rows (X varies fastest)  or columns (Y varies  fastest) if the data is already-gridded contour data. Finally,  FILE_NAME is the data file name. If the data file name is included, the data file will be  rewound  before  the  data is read. If the data file name is omitted, the file will not be rewound before reading. 

Appendix B Sec5.4  PLOT AND CONTOUR 

PLOT or CONTOUR initiates plotting. An optional  label  can be  included  and this label will be used to title the plot. The label must start with a  non-numeric  character. See  following section on labels. 

Appendix B Sec5.5   EXAMPLES 

All the examples in this  section  can  be  typed  in  while running PPLUS interactively after typing PPLUS in response to the VAX/VMS prompt. Just be sure you have first  defined  the  PPLUS symbols  according  to the Getting Started chapter before you try to do this. Once the plot appears on your terminal,  enter  <CR> to  exit  from  graphics  mode and continue. To exit from PPLUS, type EXIT. 

Appendix B Sec5.5.1  Unformatted Data, X-Y Plot 

The following example reads in data from an unformatted filewith  one group of data per record. The data to be plotted has Xin the second position and Y in the first. The data file has 296data  points in it but we will read only 100 at a time. The datafile also has an 8 record header that contains character data andmust be skipped. 

ppl>FORMAT UNF 

ppl>VARS,1,2,1 

ppl>SKP,8,PPL$EXAMPLES:DEEP3000.AVG 

ppl>RD,100 

ppl>PLOT,The first 100 data points 

ppl>RD,100 

ppl>PLOT,The second 100 data points 

Appendix B Sec5.5.2  Pre-gridded Data, Contour Plot 

The  next  example  illustrates  reading  in  data   to   be contoured. The  data  file is unformatted and does not have any  header. The data is already  gridded  with  1  value  of  Z  per  record. Since only Z is read from the data file, the input grid  and the plotting grid must be identical, and are specified by the  RD  command. The  grid  is  34  points in the x-direction and 5  points in the y-direction. The PPLUS RD command prompts for  the  minimum  and  maximum  for  the  X-Y  contouring  grid. In this  example, the grid is 34 points in the x-direction from 10 to -6.5  units  and  is 51 points in the y-direction from 0 to -500 units. PPLUS will read Z values from the data  file  assuming  x  varies  fastest. This  means  that  the  Z  values  on  the  data  file  correspond to the following x,y pairs: 

     x     y
 10.0     0
  9.5     0
  9.0     0
   .
   .
 -6.5     0
 10.0   -10
  9.5   -10
  9.0   -10
   .
   .
 -6.5   -10
   .
   . 

ppl>FORMAT,UNF 

ppl>VARS,1,,3 

ppl>RD,34,51,1,PPL$EXAMPLES:CTDDAT.DAT 

ENTER XMIN,XMAX,YMIN,YMAX 

rd>10,-6.5,0,-500 

ppl>CONTOUR,A test plot for contouring 

Appendix B Sec5.5.3  Ungridded Data, Contour Plot 

This example shows the reading in of ungridded contour data. The data is unformatted with Y,X,Z the order of the triplets. We  define the grid for plotting to be 22 x 11 with X and Y limits of  1,22  and -.033,.0576. Although the data file contains less than  1000 points, we can give PPLUS a much larger number to read,  and  it will stop at the end-of-file without error.  

ppl>FORMAT,UNF 

ppl>VARS,1,2,1,3 

ppl>RD,22,11,PPL$EXAMPLES:GRIDWI.FMT 

ENTER NUMBER PTS TO READ 

rd>1000 

ENTER XMIN,XMAX,YMIN,YMAX 

rd>1,22,.033,.567 

ppl>CONTOUR,An example of contouring with ungridded data 

Appendix B Sec5.5.4  Time Series Plot 

This example demonstrates the reading in of time series data  and  setting  up  the  x  axis  to be a time axis. The data file  contains a sequence number, which is  the  day  of  the  year  or  Julian Day and temperature. Since the sequence number increments  by 1 for 1 day, and delta-time is 1  day  by  default  in  PPLUS,  there  is no need to include the delta-time in the TAXIS command. The TAXIS  command  tells  PPLUS  that  the  time  series  has  a  delta-time  of  1440 minutes (the default) and that the time axis  is to be turned on. (The alternate form  of  the  TAXIS  command  would  be "taxis,1440,on".) The TIME command tells PPLUS that the  time axis will start at 0000 1 Jul 85, end at 0000 1 Dec 85,  and  that  a  sequence number of 1 corresponds to a time of 1200 1 Jan  85. The YLAB command sets the y-axis label. The LIMITS  command  tells  PPLUS  to  omit data where Y = 0. The VARS command is not  needed since the data is formatted with one  group  of  data  per  record,  with  the  X  variable  first and the Y variable second,  which is the VARS command default. The CROSS command  suppresses  the  drawing  of  a solid line through x=0, y=0 on the plot. The  BOX command suppresses the drawing of a  box  around  the  entire  plotting  region. The SKP command names the data file and skips  past the 5 header records at the beginning of the data file. The  RD  command reads the data. The PLTYPE command sets the plotting  medium to be both Tektronix compatible and  binary  suitable  for  routing  to  hardcopy  devices. The PLTNME sets the name of the  output plot file. The PLOT command generates the plot. See  the  Command  Description  chapter for a full description of all PPLUS  commands. 

ppl>format (17x,f3.0,7x,f5.0) 

ppl>taxis,on 

ppl>time,W8507010000,W8512010000,W8501011200 

ppl>ylab,Air Temperature 

ppl>limits,0,yeq,on 

ppl>cross,0 

ppl>box,off 

ppl>skp,5,ppl$examples:atlas.dat 

ppl>rd 

ppl>pltype,2 

ppl>pltnme,atlas.plt 

ppl>plot,ATLAS Air Temperature at 2N 165E 

Additional examples are in the directory PPL$EXAMPLES in the  form  of  PPLUS command files, which are the files with extension .PPC. Use the VAX/VMS command "DIR  PPL$EXAMPLES:*.PPC"  to  see  what  the  file  names are. You can run these command files with  the VAX/VMS command "PPLUS PPL$EXAMPLES:xxx.PPC",  where  xxx  is  the  name  of  the  PPLUS command file. The file will generate a  plot on your terminal. Enter a <CR> to exit from  graphics  mode  and  return  to the VAX/VMS prompt. (Be sure that you have first  defined the  PPLUS  symbols  according  to  the  Getting  Started  chapter before you do this.) See the chapter on Command Files for  more information about using PPLUS command files. 

You can copy these PPLUS command files to your own directory  with  the VAX/VMS command "COPY PPL$EXAMPLES:*.PPC []". Then you  can run them with the VAX/VMS command "PPLUS xxx.PPC", where  xxx  is  the  name of the PPLUS command file. You can experiment with  PPLUS commands by editing the PPLUS command file  to  change  the  appearance  of  the  plot, and then run PPLUS again with your new  command file. 

Appendix B Sec6  ROUTING PLOT FILES 

Appendix B Sec6.1  VAX/VMS 

Appendix B Sec6.1.1  Plot Files And Mom 

PPLUS plot files are named ZETA.PLT by default (this can  be  changed  with  the  PLTNME  command). A  graphics postprocessor  called MOM is available to reformat these binary plot  files  and  route  them  to  a  graphics  device. MOM submits a batch job to  BETA$LOPRI or BETA$BATCH. When the batch job has  finished,  the  original  plot  files  will  have  been  renamed from file.ext to  file.PLT_HHMMSS, and the plots queued to the appropriate  device. A log file with the name MOM_HHMMSS.LOG is placed in the original  directory when the MOM option /LOG is selected. 

The command is (brackets [] enclose optional information): 

     MOM [arg1 [arg2 ...]] 

The  arguments  for  MOM  are  order  independant  and   are  separated by spaces. The arguments are: 

 [F[ILE]=]file name  (default  ZETA.PLT) 

 [D[EVICE]=]device   (e.g. TEK, VER etc, default VER) 

 S[CALE]=scale factor (default 1) 

 G[RACE]=grace distance  (inches, default = 0.25) 

 W[IDTH]=width (paper width CAL only, default = 11.5) 

 C[PLOT]="cplot arguments" (CPLOT parameters CAL only, default=NULL) 

 [NO]ROT[ATE]   (rotate the plot, default NOROT) 

 [NO]CEN[TER]   (center the plot, default CENTER) 

 /[NO]SAVE      (save the input file, default /SAVE) 

 /[NO]LOG       (create a batch log file, default /NOLOG) 

 /SMALL, /LARGE or /TRANS  (type of hard copy made,  default /SMALL) 

 File names which are the same as a legal device name  (e.g. VER, TEK, etc.) are not allowed. The file name  can contain any wild carding that is valid with the VAX/VMS rename command. The default file extension is .PLT. 

Appendix B Sec6.1.2  Plotting Devices 

VER Batch plot on Versetec V80 printer/plotter 

TEK Interactive plot on Tekronix compatible terminal 

CPY Batch plot on Tekronix 4691 hardcopy unit 

CAL Batch plot on CALCOMP plotter 

HP Batch plot on HP7550A plotter 

LN03 Batch plot on TMAP1::  LN03 printer/plotter 

HPT Batch plot on TMAP1::  HP7475 

Appendix B Sec6.1.3  Examples 

     1) $MOM question 

Will cause MOM to prompt for inputs. If the CPLOT  argumentis a ?  you are then prompted for the CPLOT inputs. 

     2) $MOM CTD110W VER SCALE=1.25 ROTATE 

Will instruct MOM to create a VERSATEC plot  from  the  metafile  CTD110W.PLT,  rotate  the  plot 90 degrees on the paper and rescale the plot by a factor of 1.25. 

     3) $MOM CAL CPLOT="" 

Will have MOM create a CALCOMP plot using ZETA.PLT and  cal lCPLOT  with the default parameters. If CPLOT is omitted then MOM will prompt for the CPLOT command line (omitting CCFILE). 

4) $MOM TEMP.PLT;* CAL CPLOT="/P1=BLK:.3" 

Will cause MOM to send all the versions of TEMP.PLT  to  the CALCOMP with operator instructions to have pen 1 be black ink pen of 0.3 mm width. 

5) $MOM HP *.MYPLOT;* /TRANS 

Will send all plots with extension .MYPLOT  to  the  HP7550 plotter with operator instructions to plot on transparencies. 

Appendix B Sec7  PPLUS COMMAND FILES 

Appendix B Sec7.1  INTRODUCTION 

PPLUS can be run using a PPLUS command  file  that  contains the same commands used by PPLUS interactively. The file can have any name or extension, but the default extension is .PPC. To run a PPLUS command file named CMD.PPC, you can enter PPLUS by typing PPLUS CMD.PPC in response to the VAX/VMS prompt, or you can enter PPLUS in the usual way and give the PPLUS command @CMD.PPC. (See @ in the chapter on Command Description.) 

Each time PPLUS is used, an echo  file  (named  ECHO.DAT  by default)  is  generated. This  file can be edited (it should be renamed) with any VAX text editor and used  as  a  PPLUS  command file in subsequent PPLUS sessions. 

Appendix B Sec7.2  SYMBOL SUBSTITUTION 

PPLUS allows symbol substitution  in  a  manner  similar  to VAX/VMS  symbols. Global  and  local  symbols  are supported in conjunction with nested command files and parameter passing. The SET  and SHOW commands create, modify and list the symbols. When initially entering PPLUS (i.e., at the first command  level)  the symbols  are global and available to all command levels. At each subsequent command level, local symbols are created and  used  by default. Global  symbols  are used when no local symbol exists. If the symbol name is preceded by a star (*), the  global  symbol will be created, modified or substituted. 

 Parameters passed via the @ command line are named  P1,  P2, P3,  etc... just as they are in VAX/VMS. Symbols are recognized by PPLUS by being enclosed by single quotes. Character  strings can be enclosed in double quotes. For example: 

 SET TEMP "This is a test label"
XLAB 'temp' 

 will have the same effect as: 

 XLAB This is a test label 

Several symbols  are  predefined. 'DATE'  and  'TIME' contain  the  current  date  and time. Date and time formats are dd-mmm-yy and hh:mm:ss. In addition,  P1  through  Pn  are  also predefined  if  the  corresponding  argument was passed via the @ command. For example, the command procedure PLOTIT.PPC could  be executed  in  PPLUS  by typing @PLOTIT 110W Temperature. Then in the procedure PLOTIT, the symbol P1 will have  the  value  "110W" and the symbol P2 will have the value "Temperature". 

Symbols can also be defined and used  in  an  array  format, i.e.,  'P(3)'  will  get  symbol  P3  and 'label(12)' will access symbol LABEL12. 

To have a single quote (') in the symbol or command line two single  quotes  must be used (''). To have a double quote (") in the command line two double quotes ("") are required. 

Here is a sample PPLUS command file which demonstrates  some of the new, powerful PPLUS features. In this example, the symbol P1 has the value 110W.  

 pltnme,'p1'.plt
format,(f5.0,15x,f15.0)
vars,1,1,2
skp,1,'p1'.dat
rd,60
debug,on
show p1
debug,off
plot,@TRMonthly data 1979-83 at 'P1' ('date' 'time') 

The proceeding PPLUS command file (named  PLOTIT.PPC)  could be  called  repeatedly  in  PPLUS  for different data files named 110W.DAT, 140W.DAT, etc. by entering the PPLUS commands  @PLOTIT 110W,  @PLOTIT  140W,  etc. The  resulting plot files, ECHO.DAT files and graphs would be identified by the data  file  names  of 110W,  140W, etc. The graph title will also include the time and date when the graph was made. 

Appendix B Sec7.3  GENERAL GLOBAL SYMBOLS 

The global symbols set by PPLUS to allow information  to  be available in the command procedure are: 

command           SYMBOL             COMMAND      DESCRIPTION 

   DATE                             The current date dd-mmm-yy 

   PPL$COMMAND_FILE    @            The current command file name. 

   PPL$EOF             RD,RWD,SKP   "YES" if an EOF was read. 

   PPL$FORMAT          FORMAT       The current format. 

   PPL$HEIGHT          SIZE         Height of the box. 

   PPL$INPUT_FILE      RD,SKP,RWD   The current input file. 

   PPL$LF_A            LINFIT       Constant from fit y= a + b*x 

   PPL$LF_A_STDEV      LINFIT       Standard error of A. 

   PPL$LF_B            LINFIT       Constant from fit. 

   PPL$LF_B_STDEV      LINFIT       Standard error of B. 

   PPL$LF_R2           LINFIT       Regression coefficient squared. 

   PPL$LF_RES_VAR      LINFIT       Residual variance. 

   PPL$LF_VAR          LINFIT       Total variance. 

   PPL$LINE_COUNT      -            The number of the last line 

                                    read. 

   PPL$PLTNME          PLTNME       The name of the plot file. 

   PPL$RANGE_INC       %RANGE       See Advanced Commands Chapter 

   PPL$RANGE_HIGH      %RANGE       See Advanced Commands Chapter 

   PPL$RANGE_LOW       %RANGE       See Advanced Commands Chapter 

   PPL$TEKNME          TEKNME       The name of the tektronix file. 

   PPL$VIEW_X          VPOINT       X viewpoint 

   PPL$VIEW_Y          VPOINT       Y viewpoint 

   PPL$VIEW_Z          VPOINT       Z viewpoint 

   PPL$WIDTH           SIZE         Width of the box. 

   PPL$XFACT(n)        TRANSXY      Xfact for line n. 

   PPL$XLEN            AXLEN        Length of X axis. 

   PPL$XOFF(n)         TRANSXY      Xoff for line n. 

   PPL$XORG            ORIGIN       Distance between origin and left 

                                    edge. 

   PPL$XFIRST(n)       -            X value for first data point in 

                                    line n. 

   PPL$XLAST(n)        -            X value for last data  point in 

                                    line n. 

   PPL$XMAX            RD           Xmax of contour grid 

   PPL$XMIN            RD           Xmin of contour grid 

   PPL$XMAX(n)         -            Xmax for valid data in line n. 

   PPL$XMIN(n)         -            Xmin for valid data in line n. 

   PPL$YFACT(n)        TRANSXY      Yfact for line n. 

   PPL$YLEN            AXLEN        Length of Y axis. 

   PPL$YOFF(n)         TRANSXY      Yoff for line n. 

   PPL$YORG            ORIGIN       Distance between origin and 

                                    bottom edge. 

   PPL$YFIRST(n)       -            Y value for first data point in 

                                    line n. 

   PPL$YLAST(n)        -            Y value for last data  point in 

                                    line n. 

   PPL$YMAX            RD           Ymax of contour grid 

   PPL$YMIN            RD           Ymin of contour grid 

   PPL$YMAX(n)         -            Ymax for valid data in line n. 

   PPL$YMIN(n)         -            Ymin for valid data in line n. 

   PPL$ZMAX            -            Zmax for valid contour data. 

   PPL$ZMIN            -            Zmin for valid contour data. 

   TIME                -            The current time hh:mm:ss 

Appendix B Sec7.4  EPIC GLOBAL SYMBOLS 

     The  following  global  symbols   set   by   PPLUS   contain information from EPIC time series data headers: 

    SYMBOL                    COMMAND DESCRIPTION 

   PPL$EPIC_COMMENT_DATA(n)   RD      Data comment from header. 

   PPL$EPIC_COMMENT_FIRST(n)  RD      Data comment from header. 

   PPL$EPIC_COMMENT_SECOND(n) RD      Data comment from header. 

   PPL$EPIC_DEPTH(n)          RD      Depth of measurement. 

   PPL$EPIC_DESCRIPT(n)       RD      EPIC series descriptor. 

   PPL$EPIC_EXPERIMENT(n)     RD      Experiment identifier. 

   PPL$EPIC_LATITUDE(n)       RD      Latitude. 

   PPL$EPIC_LONGITUDE(n)      RD      Longitude. 

   PPL$EPIC_MOORING(n)        RD      Mooring identifier. 

   PPL$EPIC_PROJECT(n)        RD      Project identifier. 

   PPL$EPIC_XLAB(n)           RD      X-axis label. 

   PPL$EPIC_YLAB(n)           RD      Y-axis label. 

     The  following  global  symbols   set   by   PPLUS   contain information from EPIC CTD data headers: 

    SYMBOL                    COMMAND DESCRIPTION 

   PPL$EPIC_CAST(n)           RD      CTD Cruise and Cast identifier 

   PPL$EPIC_COMMENT_FIRST(n)  RD      Data comment from header. 

   PPL$EPIC_COMMENT_SECOND(n) RD      Data comment from header. 

   PPL$EPIC_DATE(n)           RD      CTD Cast Date (GMT) 

   PPL$EPIC_LATITUDE(n)       RD      Latitude. 

   PPL$EPIC_LONGITUDE(n)      RD      Longitude. 

   PPL$EPIC_XLAB(n)           RD      X-axis label. 

   PPL$EPIC_YLAB(n)           RD      Y-axis label. 

The  following  global  symbol   set   by   PPLUS   contains information about the EPIC data file: 

 SYMBOL                    COMMAND DESCRIPTION 

   PPL$EPIC_DATAFILE(n)       RD      Data file name 

   PPL$INPUT_FILE                     RD EPIC/pointer file 

Appendix B Sec7.5  COMMAND FILE LOGIC 

There are several commands that  enable  the  user  to  make command  files  more  like  small  programs. These commands are similar to FORTRAN's block IF and C's WHILE loops. Commands have been introduced that enable the user to increment and decrement a counter stored in a symbol by one. In  order  to  make  command files more readable leading blanks and tabs are ignored.  

The syntax for the PPLUS commands is given  in  the  Command Description chapter. 

EXAMPLES: 

In this example, PPLUS is exited when an end-of-file is  encountered by the RD command. This illustrates both the block IF and the use of the global PPLUS symbol PPL$EOF. 

RD 

IF PPL$EOF .EQ. "YES" THEN 

    EXIT 

ENDIF 

In the following example, the size of the plot is set to val by val inches if the value of the symbol val is less than or equal to 13 otherwise the size is set to 13 x 13. 

IF VAL .LE. 13 THEN 

    SIZE 'VAL' 'VAL' 

ELSE 

    SIZE 13 13 

ENDIF 

In the next example, if P1 is null then P1 is set to TEMPORARY.PLT and then the plot name is set to the value of the symbol P1. 

IF P1 .EQ. "" THEN 

    SET P1 TEMPORARY.PLT 

ENDIF 

PLTNME 'P1' 

This WHILE loop results in 10 plots of 100 points each from data file DLDK1039.DAT. (PPL$LINE_COUNT is a PPLUS defined  symbol for the sequence number of the last data line read.) 

SKP,DLKD1039.DAT 

WHILE PPL$LINE_COUNT .LE. 10 THEN 

    RD,100 

    PLOT 

ENDW 

Appendix B Sec7.6  ARITHMETIC 

Simple arithmetic can be performed using PPLUS symbols. The commands  that  perform these function are SET, INC and DEC. The INC and  DEC  functions  are  primarily  used  to  increment  and decrement counters in WHILE loops. The following WHILE loop uses the counter to set the line type to a solid line for each line to be  plotted  (PPL$LINE_COUNT  is  a  PPLUS defined symbol for the number of the last data line read): 

SET COUNT 1 

WHILE COUNT .LE. PPL$LINE_COUNT THEN 

    LINE,'COUNT',,0 

    INC COUNT 

ENDW 

The SET command can be used to perform simple arithmetic  on PPLUS  symbols. The syntax for these arithmetic expressions have the form: 

     num1 op num2, 

where op is +, -, * or / (addition,  subtraction,  multiplication or  division)  and num1 and num2 are numbers. The numeric values must be separated from the operator op  by  spaces. The  string will  be  used exactly as it appears if enclosed by double quotes ("). The following example centers a moveable label  0.5  inches above  the  top axis (PPL$XLEN and PPL$YLEN are PPLUS symbols for the X and Y axis lengths): 

SET XPOS 'PPL$XLEN' / 2.0 

SET YPOS 'PPL$YLEN' + 0.5 

LABS/NOUSER,1,'XPOS','YPOS',0,"A centered label" 

Appendix B Sec7.7  SYMBOL ARRAYS 

As described  in  the  SYMBOL  SUBSTITUTION  section,  PPLUS symbols  can  be  defined  and used as arrays. There are several general PPLUS global symbols which are also  defined  as  arrays, such  as  PPL$XLAST(n)  and PPL$YLAST(n), the last x and y values for data line n. The array index, in parentheses, can be  either a number or a PPLUS symbol. Examples will illustrate this. 

The following piece of a PPLUS command  file  uses  moveable lables  to  write  the line number to the right of the last point plotted for the last line read in. It  uses  the  global  PPLUS symbols PPL$XLAST(n), PPL$YLAST(n) and PPL$LINE_COUNT. 

SET XPOS 'PPL$XLAST(PPL$LINE_COUNT)' 

SET YPOS 'PPL$YLAST(PPL$LINE_COUNT)' 

LABS 'PPL$LINE_COUNT','XPOS','YPOS',-1,'PPL$LINE_COUNT' 

The array index can also be a user defined symbol. In  the following  example, the array MON contains the names of the first 3 months of the year. The graph title will be "Daily Values  for the Month of FEBRUARY". 

set mon(1) "JANUARY" 

set mon(2) "FEBRUARY 

set mon(3) "MARCH" 

. 

. 

. 

set count 2 

. 

. 

. 

plot,"Daily Values for the Month of 'mon(count)' 

The  index  of  an  array  (inside  parentheses)   will   be interpreted  according  to  the  following  rules:  1) if it is a number, that number will be used as the array index, 2) if it  is not  a number, it will be interpreted as a symbol, 3) if it is in single quotes, it will be interpreted as a symbol. 

Appendix B Sec7.8  SPECIAL FUNCTIONS 

The functions described in this sections  are  all  accessed with  the  SET  command. They can be accessed only with the SET command. The functions enable string manipulation and formatting within  PPLUS  symbol values. The PPLUS functions are similar to some of the VAX/VMS lexical functions. 

The general syntax is : 

SET sym $function (arg1, arg2,...), 

where "sym" is the symbol set by the function and  "function"  is the  name  of  the  PPLUS  function. PPLUS  functions and their arguments  are  described  in  the  following  sections. Where function  arguments  are indicated as symbols, they must be PPLUS symbols and cannot be  strings. Where  function  arguments  are indicated as strings, they can be enclosed in double quotes. 

Appendix B Sec7.8.1  $EDIT 

The command is : 

SET sym_out $EDIT (sym_in, arg1 [ arg2 arg3...] ) 

where: 

sym_out = symbol set by the function 

sym_in  = symbol on which function is to work 

arg1    = UPCASE - changes string in sym_in to upper case
          = TRIM - trims leading and trailing blanks from sym_in
             = COMPRESS - removes extra blanks from sym_in (reduces each group of blanks to a single blank)
          = COLLAPSE - removes all blanks from sym_in 

If multiple arguments are used, they can be separated  by blanks, e.g., SET sym $EDIT(sym_in,UPCASE COLLAPSE). If commas are used as separaters, the entire set of  arguments must be enclosed in quotes, e.g.,
SET sym $EDIT(sym_in,"UPCASE,COLLAPSE").  

 Example: 

SET S1 "depth" 

SET S2 $EDIT (S1,UPCASE) 

This results in S2 having the value "DEPTH". 

Example: 

SET S1 "  depth    " 

SET S2 $EDIT (S2,UPCASE TRIM) 

This results in S2 having the value "DEPTH". 

Appendix B Sec7.8.2  $EXTRACT 

     This function extracts selected characters  from  the  input string. The first character in the string is in position 1. The command is : 

SET sym_out $EXTRACT (start,length,sym_in) 

where: 

sym_out = symbol set by the function 

start   = starting character position 

length  = length of character string to be extracted 

sym_in  = symbol on which function is to work 

Example: 

SET S1 "February"
SET S2 $EXTRACT(1,3,S1) 

This results in S2 having the value "Feb". 

Appendix B Sec7.8.3  $INTEGER 

This function converts a  number  to  integer  format. The command is : 

SET sym_out $INTEGER (sym_in) 

where: 

sym_out = symbol set by the function 

sym_in  = symbol on which function is to work 

Example: 

SET MON 1
.
.
INC MON
SET INT_MON $INTEGER(MON) 

In this example, the symbol MON has been incremented,  and will have the value "2.00". The symbol INT_MON will have the value "2". 

Appendix B Sec7.8.4  $LENGTH 

 This function returns the length of the input  string. The command is : 

SET sym_out $LENGTH (sym_in) 

where: 

sym_out = symbol set by the function 

sym_in  = symbol on which function is to work 

Example: 

SET S1 "February"
SET S2 $LENGTH(S1) 

This results in S2 having the value "8". 

Appendix B Sec7.8.5   $LOCATE 

[This function is deprecated; see the Ferret function SUBSTRING]  This function locates a substring in the input string. The first character in the string is in position 1. The command is : 

SET sym_out $LOCATE (substrg,sym_in) 

where: 

sym_out = symbol set by the function 

substrg = string to be located. The first 30 characters of this string are compared with sym_in. 

sym_in  = symbol function on which function is to work 

Example: 

SET S1 "JAN 21,1987"
SET S2 $LOCATE(",",S1) 

This results in S2 having the value "7". 

Appendix B Sec7.8.6  $ELEMENT 

This function extracts an element from an  input  string  in which  the  elements are separated by a specified delimiter. The command is : 

SET sym_out $ELEMENT (pos,delim,sym_in) 

where: 

sym_out = symbol set by the function 

pos     = position of element to be extracted 

delim   = delimiter 

sym_in  = symbol on which function is to work 

Example: 

SET MONTH "JAN/FEB/MAR/APR/MAY/JUN/JUL"
SET MON $ELEMENT(3,"/",MONTH) 

This results in MON having the value "MAR". 

Example: 

SET MONTH "JAN/FEB/MAR/APR/MAY/JUN/JUL"
SET COUNT 1
WHILE COUNT .LE. 7 THEN
    SET MON(COUNT) $ELEMENT('COUNT',"/",MONTH)
    INC COUNT
ENDW 

This results in MON(1) = "JAN", MON(2) = "FEB", MON(3) = "MAR", MON(4) = "APR", MON(5) = "MAY", MON(6) = "JUN", MON(7) = "JUL". 

Appendix B Sec7.9  LABELS 

Appendix B Sec7.9.1  AXIS LABELING 

Commands affecting the labeling of the axes are: 

The numeric axis labels are drawn such  that  zero  will  be labelled  if  it occurs between the low and high axis limits. If zero does not occur, then the first large tic (from the bottom or left)  will  be  labelled. The large tics are forced to occur at integer multiples of the tic interval.  

Appendix B Sec7.9.2  EMBEDDED STRING COMMANDS 

Fonts 

All labels in PPLUS can be  plotted  using  any  one  of  21 character  fonts  and  11  symbol  fonts. The default font is SR (Simplex Roman) and other fonts are called by preceding their two letter  abbreviation  by  an  @,  i.e.,  @CI for complex itallic. 

Symbol fonts are called by using the symbol number,  i.e.,  @MA01 plots  the  first  symbol in MATH and @MA12 will plot the twelfth symbol. Font changes (of the form @XX) can be  imbedded  in  any label string (e.g., XLAB, YLAB, PLOT commands). 

 @font selects "font" as the character or symbol font  to  be used, where the font abbreviations are listed below. 

 Character Fonts 

Tables showing these fonts are linked to the web page: 

http://ferret.pmel.noaa.gov/FERRET_17sep07/Documentation/Users_Guide/pplus_char_fonts.html

Symbol Fonts 

Tables showing these fonts are linked to the web page: 

http://ferret.pmel.noaa.gov/FERRET_17sep07/Documentation/Users_Guide/pplus_symbol_fonts.html