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


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:
and when you end Prepmort routines, you use the construction:

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:

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.

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

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.

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.

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):
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:

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:


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:


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.


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