User interface
GIPSY programs do not interact with the user directly, but do this through the
GIPSY user interface, Hermes.
If for instance a program needs some input from
the user, it will send a request to Hermes which will then prompt
the user for the required parameters. The same goes for informational
messages intended for the user. If a program wants to inform the user
that the integrated flux density of a source is x Janskys, it will not
do this with an ordinary WRITE statement, but via a library routine
which sends a request to Hermes.
Below is an overview of the most important user interface facilities.
Documentation of all user interface routines can be found in a
separate document.
There is also an example program which
demonstrates the use these routines.
Starting and stopping
The first thing a task must do when it is running is to
tell Hermes that it is alive and ready for communication. This is done
with subroutine INIT. A call to
INIT must always be the first executable statement in a task.
Likewise we need to inform Hermes that the task has finished its
job. This is done with a call to
FINIS (always just before the
STOP or END statement).
User input
Input from the user is requested with the USERxxx routines.
There are eight of those routines, each for different types of inputs.
- USERINT
- requests INTEGER input
- USERLOG
- requests LOGICAL input
- USERREAL
- requests REAL input
- USERDBLE
- requests DOUBLE PRECISION input
- USERCHAR
- requests CHARACTER input
- USERCHARL
- same as USERCHAR,
but all characters are converted to lower case
- USERCHARU
- same as USERCHAR,
but all characters are converted to upper case
- USERTEXT
- requests verbatim CHARACTER input
All these routines are integer functions which return the
number of items entered by the user.
Arguments to these routines are:
- The array or variable that receives the requested input
- The maximum expected number of items
- The default level
- The keyword associated with the input
- The prompt message
Default levels have the following effect:
0 --- no default is possible
1 --- user is prompted, but default is taken when user types RETURN
2 --- user is not prompted and default is taken unless
the input was pre-specified
4 --- (added to any of the above values) the user is required to enter the exact number of items
The behaviour of GIPSY resulting from a call to these routines is
described in the user documentation.
User input keywords
When one of the user input routines is called, the user may be prompted
depending on the value of the default level and whether the
requested keyword is already known to Hermes. So repeated calls for the same
keyword do not automatically prompt the user, but normally return the value
that is already present.
Cancelling a keyword
If it is necessary to prompt the user again for some keyword, e.g. when the
task executes a loop and for every pass through the loop a new value is
required, the routine CANCEL should be
called.
Rejecting a keyword
Before the input given by the user is passed to the task, Hermes checks if
it conforms to the task's request. If not, Hermes rejects the input and
prompts the user again.
If the input does conform to the request, but for an other reason is
unacceptable to the task, the task can call the routine
REJECT and then request the input again.
One of the arguments to REJECT is a message intended to explain
why the input is unacceptable. This message will be displayed in tHermes'
User Command Area.
Text output
Tasks can send output to the terminal screen and/or the log file using the
subroutine ANYOUT. Arguments to this
routine are:
- an integer device code indicating whether output should go to the
screen, the log file or both, and whether it should be suppressed in
`experienced mode' or displayed only in `test mode'.
- a character constant or variable containing one line of output.
Status output
Information about the status of a atsk, i.e. what the task is doing at the
moment, can be sent to Hermes' Task Status Area
using the subroutine STATUS.
This routine has one argument: a character constant or variable containing
the status message.
Error reporting
A task can report any errors it encounters by calling the subroutine
ERROR. Arguments to this routine are:
- an integer error level
indicating the severity of the error. Values range from 1: `warning', to
4: `fatal error'.
- a character constant or variable containing the error message.
More features...
A separate document lists all
user interface routines. Routines not described above support following
features:
- execute another task
- modify input parameters and substitute keywords
- obtain the name of the task
- edit a text file
- decode a string into numbers
- register a function to be called when the task exits or is aborted
