15 A graphics application

Before discussing the graphics application SNXPLOT, a comparable non-ADAM program (based on the simple XYPLOT program presented in SUN/90) is considered. This program uses the Simple Graphics System (SGS) together with the NCAR/AUTOGRAPH high-level facilities and the Starlink extensions to NCAR, (SNX)13. In the aforementioned program, the relevant code can be represented as follows:

  *  Read  X,Y data arrays and get number of points, NELM.
        .......
  *  Open SGS, then match the AUTOGRAPH co-ord system with the current zone.
  *  (Actually these two calls are usually packaged as SNX_AGOP.)
        CALL SGS_OPEN (WKSTN, ZONE, STATUS)
        CALL SNX_AGWV
  
  *   Plot.
        CALL SNX_EZRXY (X, Y, NELM, ’X-Label’, ’Y-Label’, ’Title’)
  
  *   Close down SGS.
        CALL SGS_CLOSE

The equivalent lines in an ADAM program would be:

  *  Open SGS, then match the AUTOGRAPH co-ord system with the current zone.
        CALL SGS_ASSOC (’DEVICE’, ’WRITE’, ZONE, STATUS)
        CALL SNX_AGWV
  
  *   Plot.
        CALL SNX_EZRXY (X, Y, NELM, ’X-Label’, ’Y-Label’, ’Title’)
  
  *   Close down SGS.
        CALL SGS_ANNUL (ZONE, STATUS)
        CALL SGS_DEACT (STATUS)

The differences are in the opening and closing of SGS; to summarize:

A full example program is contained in ADAM_EXAMPLES:SNXPLOT.FOR. The actual data arrays are obtained by mapping the AXIS(1) data and the main data array of a spectrum and passing these via pointers, but that is incidental.

Several other considerations should be borne in mind when writing graphics applications under ADAM:

Linking – the standard ADAM link, ALINK, automatically links in the ADAM version of SGS. The non-ADAM SGS link command procedure activated by SGS_DIR:SGSLINK must not be included. This can happen accidentally as it is included in several packaged link commands. For example, the standard NCAR/SNX link command is $ LINK prog,NCAR_DIR:SNXLINK which is a packaged version of:

  $ LINK prog,NCAR_DIR:AGPWRITX,AGCHNLZ,SNXLIB/L,NCARLIB/L,@SGS_DIR:SGSLINK

The link command for SNXPLOT is deduced by omitting SGS_DIR:SGSLINK from the NCAR link, i.e.

  $ ALINK SNXPLOT,NCAR_DIR:AGPWRITX,AGCHNLZ,SNXLIB/L,NCARLIB/L

Error checking. – Unlike standard SGS, SGS under ADAM uses inherited STATUS checking. A list of symbolic constants and the errors they represent is contained in the file with logical name SGS_ERR. These values can be used to perform tests such as:

        INCLUDE ’SGS_ERR’
  *      ...
        IF (STATUS.EQ.SGS__ZONTB) THEN
  *      Zone too big - take appropriate action.

Bad pixels – the program SNXPLOT.FOR is likely to crash if it encounters values 1.7E38 as will be the case if the input data contain bad pixels. However NCAR will ignore any data points which contain the current NCAR ‘null’ value. This value can be set to the bad value appropriate for the data type (see Section 12) causing NCAR to ignore bad pixels. The appropriate call is as follows, (see the NCAR users’ manual, available as a Starlink MUD for details).

        INCLUDE ’BAD_PAR’                   ! Make VAL__BADR etc. available
  *     ...
        CALL AGSETF (’NULL/1.’, VAL__BADR)  ! After SGS_ASSOC & before plotting

This modification has been made in ADAM_EXAMPLES:SNXPLOT1.FOR.

PGPLOT

An example program using PGPLOT is contained in ADAM_EXAMPLES:PGPLOT.FOR. The basic adaptation required when using PGPLOT is that after opening a device via a call to SGS_ASSOC14, it is necessary to inquire the workstation identifier, encode this as a character string and pass this string as the FILE (device) argument to PGBEGIN. The significant portion of the code is reproduced below:

        INTEGER ZONE, STATUS, IWKID, NCHAR
  *     ....
  *   Activate SGS.
        CALL SGS_ASSOC (’DEVICE’, ’WRITE’, ZONE, STATUS)
        IF (STATUS.NE.SAI__OK) GOTO 999
  
  *   Enquire the workstation identifier.
        CALL SGS_ICURW (IWKID)
  
  *   Encode IWKID into a character string as required by PGBEGIN.
        CALL CHR_PUTI (IWKID, WKID, NCHAR)
  
  *   Call PGBEGIN to initiate PGPLOT and open the output device.
        CALL PGBEGIN (0, WKID(1:NCHAR), 1, 1)
  
  *   Plot with PGPLOT.
  *     ...
  
  *  Finally, call PGEND to terminate things properly.
        CALL PGEND
  
  *   Deactivate SGS
        CALL SGS_ANNUL (ZONE, STATUS)
        CALL SGS_DEACT (STATUS)

The link command for this program is $ ALINK PGPLOT,PGPLOT_DIR:GRPSHR/LIB.

13Sounds daunting, however the combination of these packages enables a ‘default’ graph to be drawn with only a few simple subroutine calls. With a little more effort the programmer can alter the style of the plot in virtually every desirable way, e.g. size, labelling, tick mark appearance, histogram, logarithmic axes, etc.)

14Several restrictions exist on the use of PGPLOT over SGS; these are discussed in SUN/15.