10 Panic Section

 10.1 Getting help in ICL
 10.2 BEGPLOT or DEVICE does not work in ICL
 10.3 READF cannot find a column label
 10.4 Strange behaviour of DLIMITS
 10.5 Error messages from SHOWPONGO in ICL
 10.6 AGI problems
 10.7 RESET peculiarity (ICL only)
 10.8 Plotting large numbers of positions

10.1 Getting help in ICL

When in ICL, on-line help on PONGO may be examined using the command:

  ICL> help pongo

This will provide a brief description of the package and how to begin and end a PONGO plotting session. Once the PONGO commands have been made available within ICL, i.e. by typing

  %  pongo

at the C-shell prompt or:

  ICL> pongo

at the ICL> prompt, on-line help on any PONGO command may be examined using the command:

  ICL> help <pongo command>

The command:

  ICL> help pongo

will produce a brief introduction to PONGO, and the command:

  ICL> help introduction

will produce a more detailed introduction to PONGO and how to get started. These help commands are also available at the PONGO> prompt. A classified list of PONGO applications (HELP CLASSIFIED) is provided within the help system and help is also provided on running the PONGO examples (HELP EXAMPLES).

If difficulties are encountered with PONGO and the on-line help system does not reveal the cause, it is recommended that the relevant sections of this document are read, or re-read. It may be that this document does not provide enough detail concerning the behaviour of the PGPLOT graphics package: for detailed information regarding PGPLOT, the PGPLOT manual should be consulted (available as a Miscellaneous User Document, MUD, at all Starlink sites). As a last resort, the problem may be regarded as a software bug and reported to the Starlink Software support mailing list (starlink@jiscmail.ac.uk).

10.2 BEGPLOT or DEVICE does not work in ICL

If the error message:

  TOOFEWPARS   Not enough procedure parameters

is returned after the BEGPLOT or ENDPLOT commands have been invoked, the reason is that another application package or ICL procedure has switched parameter checking on within ICL (SG/5). The problem is simply overcome by typing the command:

  ICL> set nocheckpars

The PONGO commands will then work correctly.

10.3 READF cannot find a column label

If a column label is used with the READF command instead of the column number (see §5) and READF fails, e.g. :

  PONGO> readf myfile.dat xcol=1 ycol=3 zcol="ZCOL"
  File: /disk/scratch/jbloggs/plots/myfile.dat
  XCOL - 1 is column number 1.
  YCOL - 3 is column number 3.
  !! ZCOL incorrectly specified as ZCOL.
  !  READF: Data could not be read.

then either the data file does not have column labels or the incorrect column label has been used. It is of particular significance here that the column labels are case-sensitive. In fact, JBLOGGS found that the column label for his ZCOL data was Zcol:

  PONGO> readf myfile.dat xcol=1 ycol=3 zcol="Zcol"
  File: /disk/scratch/jbloggs/plots/myfile.dat
  XCOL - 1 is column number 1.
  YCOL - 3 is column number 3.
  ZCOL - Zcol is column number 5.
  EXCOL - 0 is column number 0.
  EYCOL - 0 is column number 0.
  LABCOL - 0 is column number 0.
  SYMCOL - 0 is column number 0.
  42 data points read.

10.4 Strange behaviour of DLIMITS

If PONGO does not seem to be doing something correctly, it is often because there are unwanted data in the error columns. This can come about when a file that does not contain errors is read (the appropriate parameters to READF have been set to zero), following one where there have been errors. Here, it should be noted that setting a column parameter in READF to zero means that no data will be read from the file into that particular area, it does not clear the data values. This is a feature rather than a bug, because it allows X and Y data from two different files to be plotted together, as long as each file contains the same number of points (the number of points read from the second file is assumed to be the number required). Although advantageous, it is possible for the internal data areas to get into a mess with this arrangement. If this seems to have happened then the command:

  PONGO> clear data

should be used to clear all the data areas.

10.5 Error messages from SHOWPONGO in ICL

The commands SHOWPONGO may sometimes deliver the error messages

  !! Object ’PONGO_<param>’ not found.
  !! DAT_FIND: Error finding a named component in an HDS structure.

when invoked (<param> refers to a PONGO parameter name in this context). The reason is simply that no global parameter of that name currently exists. This can either be because PONGO has not been used before (or not a lot), or because the ADAM global parameter file ($HOME/adam/GLOBAL.sdf) has been deleted since the last PONGO session. Although the error messages look alarming, they are harmless. To stop these error messages being output, the command RESETPONGO should be executed. This command will assign a default value to each of the PONGO global parameters except PONGO_DATA, the data file name used by READF, and SHOWPONGO will be subsequently more informative.

10.6 AGI problems

The AGI database is normally kept in a separate HDS file (SG/4) for each machine in your $HOME directory. The command BEGPLOT opens the AGI database and reads database information relevant to the graphics device being used. During a PONGO plotting session, the database file is held open to update the database as the plotting session proceeds. At the end of plotting, when ENDPLOT is executed, the update of the database is completed and the database file is closed. If another non-PONGO application which uses AGI is run before the current PONGO plotting session has been ended (i.e. using ENDPLOT), it will be unable to access the AGI database and will subsequently fail. In the event of this happening, using the PONGO ENDPLOT command will restore the correct behaviour of the non-PONGO application.

What is more important, in order to use AGI successfully, is the use of ENDPLOT before exiting ICL or CL. Because PONGO keeps the AGI database file open throughout a plotting session it is possible to exit ICL or CL without having first executed ENDPLOT. If this is done, it is likely that the AGI database will not have been fully updated before being closed, with the result that the next time AGI is used it will behave inconsistently. PONGO crashing during a plotting session (hopefully, a rare event) can also result in a corrupted AGI database. There is no solution to this problem other than to delete the database file and start again. The AGI database files are kept in the directory $HOME and have names of the form agi_<machine>.sdf, where <machine> is the name of the machine on which AGI is being used. This file may be deleted at any time before a BEGPLOT command or after an ENDPLOT command. The BEGPLOT command may then be used to begin a new PONGO plot, creating a new AGI database as a result.

10.7 RESET peculiarity (ICL only)

When using the ADAM parameter system (SG/4) RESET qualifier to set parameters back to their default values (this facility would be particularly useful for BOXFRAME, for example), there will be no effect on parameters which get their values from global parameters. Use the RESETPONGO command to reset global parameters, or alternatively (somewhat drastically) delete the GLOBAL.sdf file.

10.8 Plotting large numbers of positions

PONGO can store 5000 positions at any time. This can very occasionally cause problems for specific types of use. One way in which you can actually plot more positions than this, is by reading in the data in chunks (of 5000 points) and plotting these. The following ICL procedure shows one way in which you might do this:

  proc superplot file, x1, x2, y1, y2, n
    begplot xwindows xmin=(x1) xmax=(x2) ymin=(y1) ymax=(y2)
    limits (x1) (x2) (y1) (y2)
    loop for i = 0 to (n) step 1
      j = i + 1
      print "Plotting points from" (i*5000) " to " (j*5000-1)
      readf data=(file) xcol=1 ycol=2 from=(i*5000) to=(j*5000-1) all accept
    end loop
  end proc

This would then be invoked as in (assuming the procedure was kept in a file superplot.icl):

  ICL > load superplot.icl
  ICL > superplot mygalaxies.dat -3 3 -3 3 10

Which would plot 50000 positions stored in the file mygalaxies.dat.