Developing Programs, 10 of 12

Handling Errors

A well-designed program handles errors gracefully and reports each error in an informative way. The OLAP DML provides commands such as TRAP to help you detect and report errors in your programs.

How An Error Is Signaled

When an error occurs anywhere in a program, the error is signaled. To signal the error, the following actions are performed.

The name of the error is stored in the ERRORNAME option, and the text of the error message is stored in the ERRORTEXT option.
If ECHOPROMPT is YES, then the error message is sent to the current outfile or to the debugging file, when there is one.
If error trapping is off, then the execution of the program is halted. If error trapping is on, then the error is trapped.

How An Error Is Trapped

To make sure the program works correctly, you should anticipate errors and set up a system for handling them. You can use the TRAP command to turn on an error-trapping mechanism in a program. If error trapping is on when an error is signaled, then the execution of the program is not halted. Instead, error trapping does the following:

Turns off the error-trapping mechanism to prevent endless looping in case additional errors occur during the error-handling process
Branches to the label that is specified in the TRAP command
Executes the commands following the label

Handling Errors While Saving the Session Environment

To correctly handle errors that might occur while you are saving the session environment, place your PUSHLEVEL command before the TRAP command and your PUSH commands after the TRAP command.

PUSHLEVEL 'firstlevel'
TRAP ON error
PUSH . . .

In the abnormal exit section of your program, place the error label (followed by a colon) and the commands that restore the session environment and handle errors. The abnormal exit section might look like this.

error:
POPLEVEL 'firstlevel'
OUTFILE EOF

These commands restore saved dimension status and option values and reroute output to the default outfile.

Suppressing Error Messages

If you do not want to produce the error message that is normally provided for a given error, then you can use the NOPRINT keyword with the TRAP command.

TRAP ON error NOPRINT

When you use the NOPRINT keyword with TRAP, control branches to the error label, and an error message is not issued when an error occurs. The commands following the error label are then executed.

When you suppress the error message, you might want to produce your own message in the abnormal exit section. The SHOW command produces the text you specify but does not signal an error.

TRAP ON error NOPRINT
       .
       .
       .
error:
       .
       .
       .
SHOW 'The report will not be produced.'

The program continues with the next command after producing the message.

Identifying the Error That Occurred

All errors have names. Whenever an error is signaled, the error name is stored in the ERRORNAME option. If you want to perform one set of activities when one type of error occurs, and a different set of activities if another type of error occurs, then you can test the value of the ERRORNAME option. The ERRORTEXT option contains a description of the error.

Creating Your Own Error Messages

All errors that occur when commands or command sequences do not conform to its requirements are signaled automatically. In your program, you can establish additional requirements for your own application. When a requirement is not met, you can execute the SIGNAL command to signal an error.

You can give the error any name. When the SIGNAL command is executed, the error name you specify is stored in the ERRORNAME option, just as an error name is stored. If you specify your own error message in the SIGNAL command, then your message is produced just as an error message is produced. When you are using a TRAP command to trap errors, a SIGNAL command branches to the TRAP label after the error message is produced.

Example 7-14 Signaling an Error

Suppose your program produces a report that can present from one to nine months of data. You can signal an error when the program is called with an argument value greater than nine. In this example, nummonths is the name of the argument that must be no greater than nine.

select:
TRAP ON error
PUSH month
LIMIT month TO nummonths
IF STATLEN(month) GT 9
   THEN SIGNAL toomany -
     'You can specify no more than 9 months.'
REPORT DOWN district W 6 units
finish:
POP month
RETURN
error:
POP month
IF ERRORNAME EQ 'TOOMANY'
   THEN SHOW 'No report produced'

If you want to produce a warning message without branching to an error label, then you can use the SHOW command.

select:
LIMIT month TO nummonths
IF STATLEN(month) GT 9
   THEN DO
     SHOW 'You can select no more than 9 months.'
     GOTO finish
     DOEND
REPORT DOWN district W 6 units
finish:
POP month
RETURN

Handling Errors in Nested Programs

When you write a program that runs another program, the second program is nested within the first program. The second program might, in turn, run another nested program.

The error-handling section in each program should restore the environment. It can also handle any special error conditions that are particular to that program. For example, if your program signals its own error, then you can include commands that test for that error.

Any other errors that occur in a nested program should be passed up through the chain of programs and handled in each program. To pass errors through a chain of nested programs, you can use one of two methods, depending on when you want the error message to be produced:

The error message is produced immediately, and the error condition is then passed through the chain of programs.
The error is passed through the chain of programs first, and the error message is produced at the end of the chain.

The SIGNAL command is used in both methods.

Example 7-15 Producing the Error Message Immediately

To produce the error message immediately, use a TRAP command in each nested program, but do not use the NOPRINT keyword. When an error occurs, an error message is produced immediately, and execution branches to the trap label.

At the trap label, perform whatever error-handling commands you want and restore the environment. Then execute a SIGNAL command with the PRGERR keyword.

SIGNAL PRGERR

When you use the PRGERR keyword with the SIGNAL command, no error message is produced, and the name PRGERR is not stored in ERRORNAME. The SIGNAL command signals an error condition that is passed up to the program from which the current program was run. If the calling program contains a trap label, then execution branches to that label.

When each program in a chain of nested programs uses the TRAP and SIGNAL commands in this way, you can pass the error condition up through the entire chain. Each program has commands like these.

TRAP ON error
   .
   .       "Body of program and normal exit commands
   .
RETURN 
error:
   .
   .       "Error-handling and exit commands
   .
SIGNAL PRGERR

Example 7-16 Producing the Error Message at the End of the Chain

To produce the error message at the end of a chain of nested programs, use a TRAP command with the NOPRINT keyword. When an error occurs in a nested program, execution branches to the trap label, but the error message is suppressed.

At the trap label, perform whatever error-handling commands you want and restore the environment. Then execute the following SIGNAL command.

SIGNAL ERRORNAME ERRORTEXT

The ERRORNAME option contains the name of the original error, and the ERRORTEXT option contains the error message for the original error. The SIGNAL command shown above passes the original error name and error text to the calling program. If the calling program contains a trap label, then execution branches to that label.

When each program in a chain of nested programs uses the TRAP and SIGNAL commands in this way, the original error message is produced at the end of the chain. Each program has commands like these.

TRAP ON error NOPRINT
   .
   .       "Body of program and normal exit commands
   .
RETURN
error:
   .
   .       "Error-handling and exit commands
   .
SIGNAL ERRORNAME ERRORTEXT