Workbook for SLD Offline Users - Writing Code: The Signal System

Use $CALL and $RETURN

On the simplest level, all you have to do to correctly use the Signal System in your Prepmort is to make sure that when you call Prepmort routines, you use the construction:

   $CALL ... ERROR RETURN

and when you end Prepmort routines, you use the construction:

   $RETURN

The ERROR RETURN in the $CALL construction means that if the routine you are calling fails, your own routine will immediately return. The error message from the routine that actually had the problem will end up being passed up the chain of all the routines that called one another until the error message gets back to IDA.

In rare cases, you may want to take some other action when a routine you $CALL fails. Instead of just returning, you can set up your $CALL statement to execute some other set of code.

For example:

   $CALL JZIOPN(SAVSET,'READ','OLD',DEVID) ERROR
   [
     IF P_DSPWIND%(INTERLEV) .GT. 1 [ $CALL DSPUIRM ERROR RETURN; ]
     $RETURN;
   ]

Instead of just returning when JZIOPN fails, this example tests on a flag and then has the option of calling another routine.

In most cases, an ERROR RETURN is enough.

Use $SIGNAL instead of WRITE or PRINT

In a complex software environment such as SLD, the programmer cannot always count on getting the user's attention with a simple WRITE or PRINT statement. For example, if the user is using the interactive Event Display, it may be more appropriate to put a message into the event display's event information box than to put a message into the console window. Or, if the user us running the code as part of the online data taking process, it may be more appropriate to put the message into the SLD Status Display.

By issuing all messages through the Signal System rather than through WRITE or PRINT statements, the user can rely on the Signal System to post the messages in the right place for the current user.

If the user is just running a simple offline job, the message will appear in the console.
If the user is running a job that includes the interactive event display, the message will appear both in the console and in the event display information box.
If the user is running an online job, the message will appear both in the console and on the SLD Status Display.

Not only is the message available for the user, but the message is available to other Prepmort routines that called the routine. These other Prepmort routines can take different action depending on what message the called routine gave.

The Signal System even knows how to suppress certain kinds of error messages if they appear very often. It will typically show you the message the first few times it occurs in your job, and will then suppress the message for the rest of the job, issuing occasional reminders that the message has occurred many times and has been suppressed.

As you become more familiar with SLD software, you will become more aware of the importance of the Signal System. For now, you should learn the basics of how to use $SIGNAL.

The process involves three steps,

Composing a Signal Message
Adding the Signal Message to the Error Database
Signalling the Message

Composing a Signal Message

Signal messages are composed in special files that have the file extension ERR. A single ERR file typically contains all of the signal messages for a related group of Prepmort routines. The ERR is short for "Error Handler," but it is important to remember that this system actually supports many more kinds of messages than just error messages. Many of the messages handled by Signal are normal progress reports, not error messages.

As a first example of an ERR file, look at the one that handles all of thhe signal messages for the MFIT Minuit fitting package. They are in the file PRODMFIT:FITCMD.ERR.

The header is self-explanatory. It is almost like a Prepmort header.

The phrase /ABBREV=FIT defines an abbreviation used in Prepmort files to refer to this message file. Most ERR files have a three letter abbreviation, though this is not required.

Each line that starts with the percent sign represents one signal message.

The first column contains the message identifier. This, combined with the ERR file name or abbreviation, gives a unique identifier for the signal message.
For example, when Prepmort code wants to invoke the seventh message from this file, it uses the statement:
```
     $SIGNAL FIT$AMBIG;
```
When Prepmort code wants to invoke the last message from this file, it uses the statement:
```
     $SIGNAL FIT$NOFTPLT2;
```
The second column contains the severity code. This controls how serious IDA considers this condition.
It can be either:
- S for Success, nothing at all is written out
- I for Informational, just writes out some information
- W for Warning, still just writes out some information
- E for Error, writes an error message and causes the chain of called routines to all return to IDA
- F for Fatal Error, writes an error message and causes the IDA job to end
The options I and F are the ones you will use most often. There is no clear distinction when W is better than I. generally, both have the same affect, but I is used when the information is something to be expected while W is used when the information means that something is a little bit wrong but not so serious that it will cause a problem.
The third column contains the signal message itself, the message that IDA will type out.

It is easier to understand all of this by looking at some examples of ERR files, at the Prepmort files that use them, and at the results that appear in IDA.

As a first example, if you are running IDA with the MFIT package, and you issue the command MFIT S:
```
     Ida>  CMDPROC MFITCMD
     Ida>  MFIT S
```
the routine PRODMFIT:MFITCMD.PREPMNLB will execute the statement
```
     $RETURN FIT$AMBIG;
```
which will write out the message:
```
     %FITCMD-E-AMBIG Ambiguous fit command.  Supply more characters.
     IDA error executing MFIT (4)
```
The only difference between $RETURN and $SIGNAL is that $RETURN will return after writing out the signal message.
Some of the messages in FITCMD.ERR contain 'A' or 'I'. These are places where the Prepmort code will supply character or integer arguments to the Signal System when it invokes the signal message.
For example, if in you are running IDA with the MFIT package, and you try to fit to a dataset that does not exist:
```
     Ida>  CMDPROC MFITCMD
     Ida>  MFIT DATA CRUD
```
the routine PRODMFIT:MFITCMD.PREPMNLB will execute the statement
```
     $RETURN FIT$NODATA WORD;
```
where the variable WORD will be the data set name you typed in, CRUD. The signal system will then write out the message:
```
     %FITCMD-I-NODATA Could not locate the data set named CRUD.
```
In some cases, some additional lines of information follow the one line message. These lines provide can be used by the automated help system to give users more details about a given signal condition.
For example, in the file PRODDISPLAY:DSPDSP.ERR you will see all of the error messages used by the event display system. Look at that file now and study the lines around the %NOSVEW message.
The following IDA code would invoke this signal message, trying to read a set of saved view parameters that do not exist:
```
     Ida>  CMDPROC DSPCMD
     Ida>  DSP RVIEW FAKE
```
the routine PRODDISPLAY:DSPURVW.PREPMORT will execute the statement
```
     $RETURN DSP$NOSVEW SAVSET;
```
where the variable SAVSET will be the data set name you typed in, FAKE. The signal system will then write out the message:
```
     %DSPDSP-W-NOSVEW No view parameters named FAKE JAZZDATA have been saved.
```
To see the additional help information relating to this signal message:
```
     Ida>  SIGNAL HELP DSP$NOSVEW
```
IDA will respond with:
```
     DSPDSP

       NOSVEW

          There is no saved set of view parameters with the filename you specified.
          The view parameters have been left as they were before the DSP RVIEW.

     Topic?
```
IDA will leave you in the help mode (you will have the Topic prompt). To leave help mode, hit return.

Adding Your Signal Message to the Error Database

Once you have modified an existing ERR file or written your own, you make IDA add those signal messages to its signal database by issueing a command from the DCL prompt.

The command is:

    > SLDERROR/NEW filename.filetype

For example, copy the file from PRODMFIT:FITCMD.ERR to your current directly and then try to rebuild the error database (this will not actually make anything new since you have not changed the FITCMD.ERR file):

    > SLDERROR/NEW FITCMD.ERR

You should get the reponse:

     %SYSTEM-F-NOLOGNAM, no logical name match
     %SIGNAL-W-TESTSECT Logical name TESTMFIT not defined, default directory used
     %SIGNAL-I-NEWDBASE New data base created

The first two messages are just letting you know that the Signal system has noticed that the file your are rebuilding is part of the DUCS section MFIT and that DUCS is going to assume you want it to do a DUCS TEST MFIT * for you.

If you now do a DIR, you will find that the Signal system has created three new files:

FITCMD.ERRORS is a compiled form of your ERR file
SIGNAL.DATABASE is a new version of the SLD signal database that includes your signal file
SIGNAL.HLB is a new version of the SLD help system that includes help messages from your signal file

Signalling the Message

Once you have written the ERR file and rebuilt the signal database, you just use the $SIGNAL statement to signal the message from your Prepmort. If you want to leave your routine immediately after signalling the message, you can instead use the $RETURN statement.

You already saw examples of these statements above:


   $SIGNAL FIT$AMBIG;
   $SIGNAL FIT$NOFTPLT2;
   $RETURN FIT$AMBIG;
   $RETURN FIT$NODATA WORD;
   $RETURN DSP$NOSVEW SAVSET;

The only other thing you need is to have a "&COPY FROM ..." statement for every ERR file that you signal errors from.

For example, if you want to signal errors from the FITCMD.ERR file, you need the statement:

   "&COPY FROM FITCMD.ERRORS"

This statement should appear at the beginning of your declarations section. The statement can not have any spaces before it. It is another example of the rule that statements that begin with the two characters "& can not have spaces before them.

You can see now that the statement that comes at the end of most Prepmort routines, $RETURN;, is just a special case of the more general form of the statement:

   $RETURN err_file_name$message_id;

When no err_file_name$message_id is specified, Prepmort simply returns with no message signalled.

References

See the manual titled "SLD Error Signaling and Status System" for more details on the Signal System. It is not as clearly written as some of the other SLD manuals, but it can be useful when you find yourself needing to do very advanced work with the Signal System. It is can be obtained from the SLD Offline Software Documentation Center, SLAC Central Lab Annex Room B105.

Back to Writing Code

Joseph Perl
27 February 1995