---

SIGNAL

The SIGNAL command produces an error message from within a program and halts normal execution of the program. Oracle OLAP sends the error message to the current outfile. When the program contains an active trap label, execution branches to the label. Without a trap label, execution of the program terminates and, when the program was called by another program, execution control returns to the calling program.

Syntax

SIGNAL {errname [message]|STOP}

Arguments

errname

A TEXT expression that indicates the name of the error message to be produced. When you execute the SIGNAL command, Oracle OLAP stores the errname in the ERRORNAME option. Normally, the name of the error does not appear in the error message. However, when you omit message, the error name (errname) will appear along with a stock message as described in the message argument.

message

A TEXT expression that specifies the error message to be produced. When you omit this argument, SIGNAL produces the following message.

ERROR: (errname) Please contact the administrator of your
   Oracle Oracle OLAP application.

When you execute the SIGNAL command, Oracle OLAP stores message in the ERRORTEXT option.

STOP

Immediately stops execution of all currently running programs. No error message is produced. The error condition is not trapped by an active TRAP label.

Notes

Error Message Format

When you supply a long line as your error message, you must add your own line breaks to format the text. Type the newline escape sequence (\n) where you want each line to end. You can type up to a limit of 6 lines or 4000 characters, whichever you reach first. An error occurs when you try to supply a single line longer than 4000 characters.

Transfer of Control

SIGNAL creates an error condition that halts execution of a program. Control is passed back up any chain of nested programs until it reaches a trap label in one of the programs. See the TRAP command.

TRAP Labels

When you execute a SIGNAL command when TRAP is ON, execution branches to the trap label. Any statements following the trap label in the program are then executed.

PRGERR Argument

You can use the special name PRGERR to communicate to a calling program that an error has occurred. The statement SIGNAL PRGERR sets ERRORNAME to a blank value and passes an error condition to the calling program without causing another error message to be displayed. For a complete explanation of how to use SIGNAL to pass an error up a chain of nested programs, see the TRAP command.

Examples

Example 21-32 Signaling an Error

Suppose you have written a program that requires one argument. When no argument is supplied, there is no purpose in running the program. Therefore, the first thing the program does is check if an argument has been passed. When it has not, the program terminates after sending an error message to the current outfile.

The following program lines check for the argument and signal an error when it is not found.

IF ARGS EQ ''
THEN SIGNAL msg1 'You must supply an argument.'

SIGNAL sends the following message to the current outfile.

ERROR: You must supply an argument.

Example 21-33 Signaling an Error When an Argument Value is Invalid

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'