TRAP

Within an OLAP DML program, the TRAP command causes program execution to branch to a label when an error occurs in a program or when the user interrupts the program. When execution branches to the trap label, that label is deactivated.

The label should be no longer than eight characters. It must start with a letter, dot, or underscore, and the remaining characters must be letters, numbers, dots, or underscores.

Syntax

TRAP {OFF|ON errorlabel [NOPRINT|PRINT]}

Arguments

OFF

Deactivates the trap label. Since only one trap label can be active at a time, you do not supply errorlabel when setting TRAP OFF. When you try to include a label with OFF, an error occurs.

ON errorlabel

Activates the trap label (errorlabel). When TRAP is active, any error in the program will cause execution to branch to errorlabel.

errorlabel

The name of a label elsewhere in the program constructed following the "Guidelines for Constructing a Label". Execution of the program branches to the line directly following the specified label.

Note that errorlabel, as specified in ON, must not be followed by a colon. However, the actual label elsewhere in the program must end with a colon.

NOPRINT

PRINT

Indicates whether to suppress output of the error message. NOPRINT suppresses the message. PRINT (default) means that the error message is sent to the current outfile before execution branches to the trap label. With the OFF keyword, NOPRINT and PRINT are meaningless and produce an error.

Notes

To activate a trap label, include a TRAP command at the beginning of your program and specify a trap label in it. Then include this label later in your program.

When an actual trap label that corresponds to errorlabel does not exist elsewhere in the same program, execution stops with an error.

When an error occurs in a program that contains a trap label, execution branches to the label and the trap is deactivated. You do not have to execute an explicit TRAP OFF  command. Thus, an error occurring after execution has branched to the label will not cause execution to branch to the same label again.

In the statements that follow the trap label, you can check the name of the error that has occurred by using the ERRORNAME option, which contains the name of the first error occurring in the program. You can also check the error message for that error by using the ERRORTEXT option (see the entries for ERRORNAME and ERRORTEXT).

To find out what the value of ERRORNAME will be for specific error conditions, you can check the dimension _MSGID, which is supplied as a part of Oracle OLAP. The error messages are contained in the variable _MSGTEXT, which is dimensioned by _MSGID. To see this list, execute the following statement.

REPORT W 60 _MSGTEXT

To pass an error to a calling program, you can use one of two methods. The method you use depends on when you want the error message to be produced. With the first method, Oracle OLAP produces the message immediately and then the error condition is passed through the chain of programs. With the second method, Oracle OLAP passes the error through the chain of programs first and then produces the message. See "Passing an Error: Method One" and "Passing an Error: Method Two" for details.

With both methods, the appropriate error handling happens in each program in the chain, and at some point Oracle OLAP sends an error message to the current outfile.

Using this method, Oracle OLAP produces the message immediately and then the error condition is passed through the chain of programs.

Use a TRAP command with the (default) PRINT option. When an error occurs, Oracle OLAP produces an error message, and execution branches to the trap label. After the trap label, perform whatever cleanup you want, and then execute the following statement.

SIGNAL PRGERR

This creates an error condition that is passed up to the program from which the current program was run. However, PRGERR does not produce an error message. PRGERR sets the ERRORNAME option to a blank value.

When the calling program contains a trap label, execution branches to the label. When each of the programs in a sequence of nested programs uses TRAP and SIGNAL in this way, you can pass the error condition up through the entire sequence of programs.

Using this method, Oracle OLAP passes the error through the chain of programs first and then produces the message.

Use a TRAP command with the NOPRINT option. When an error occurs, execution branches to the trap label, but the error message is suppressed. After the trap label, perform whatever cleanup you want, then execute the following statement.

SIGNAL ERRORNAME ERRORTEXT

The options ERRORNAME and ERRORTEXT contain the name and message of the original error, so this SIGNAL command reproduces the original error. The error is then passed up to the program from which the current program was run.

When the calling program also contains a trap label, execution branches to its label. When each of the programs in a sequence of nested programs uses TRAP...NOPRINT and SIGNAL ERRORNAME ERRORTEXT in this way, you can pass the error condition up through the entire sequence of programs. Oracle OLAP produces the error message at the end of the chain.

When you reach a level where you want to handle the error and continue the application, omit the SIGNAL command. You can display your own message with the SHOW command.

Examples

PUSH month DECIMALS LSIZE PAGESIZE
TRAP ON haderror NOPRINT
LIMIT month TO LAST 1
   ...
POP month DECIMALS LSIZE PAGESIZE
RETURN
 
haderror:
POP month DECIMALS LSIZE PAGESIZE
SIGNAL ERRORNAME ERRORTEXT

SIGNAL PRGERR

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

SIGNAL ERRORNAME ERRORTEXT

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