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.

See also:

For a discussion of how Oracle OLAP handles declarative errors in programs and models, see "Declarative Errors".

Syntax

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

Parameters

OFF: Deactivates the trap label. Because 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.

Note:
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 statement. Thus, an error occurring after execution has branched to the label does not cause execution to branch to the same label again.
ON errorlabel: Activates the trap label (errorlabel). When TRAP is active, any error in the program causes 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:
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.
When an actual trap label that corresponds to errorlabel does not exist elsewhere in the same program, execution stops with an error
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.

Examples

Example 10-156 Trapping a Program Error

The following program fragment uses a TRAP statement to direct control to a label where options and dimension status are set back to the values they had before the program was executed and an error is signaled.

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

Example 10-157 Producing a Program Error Message Immediately

To produce the error message immediately, use a TRAP statement 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 statement that includes the PRGERR keyword.

SIGNAL PRGERR

When you use the PRGERR keyword in the SIGNAL statement, no error message is produced, and the name PRGERR is not stored in ERRORNAME. The SIGNAL statement signals an error condition that is passed up to the program from which the current program was run. When 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 10-158 Producing a Program 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 statement that includes 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 statement.

SIGNAL ERRORNAME ERRORTEXT

The preceding SIGNAL statement contains includes ERRORNAME and ERRORTEXT within it. The ERRORNAME option contains the name of the original error, and the ERRORTEXT option contains the error message for the original error. When the calling program contains a trap label, then execution branches to that label.Consequently, the SIGNAL statement passes the original error name and error text to the calling program.

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 the following.

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