Oracle9i OLAP Services Developer's Guide to the OLAP DML Release 1 (9.0.1) Part Number A86720-01 |
|
Designing Programs, 11 of 13
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.
When an error occurs anywhere in a program, the error is signaled. To signal the error, the following actions are performed.
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, the following actions are performed.
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.
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.
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.
To find out what the value of ERRORNAME will be for specific error conditions, you can check the dimension _MSGID in the express.db
analytic workspace. The error messages are contained in the variable _MSGTEXT, which is dimensioned by _MSGID. To see this list, execute the following command.
report w 60 _msgtext
Many of the error messages contained in _MSGTEXT are constructed so that appropriate values can be substituted in the message at the time it is produced (for example, the name of an OLAP DML object). These substitutions are indicated by a percent sign (%
) followed by one or more characters in the _MSGTEXT value. In most cases, you can understand the purpose and condition of the message without knowing exactly what will be substituted.
When you need to, you can use the SIGNAL command to send to the current outfile the ERRORNAME and ERRORTEXT of the last error that occurred. The SIGNAL command has the following format.
SIGNAL errorname [message]
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.
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 do not specify your own message in a SIGNAL command, then Express the error name and a default message are produced.
ERROR: (TOOMANY) Please contact the administrator of your Oracle Express Server application.
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
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 SIGNAL command is used in both methods.
For Method 1, 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
For Method 2, 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
For more information, see the following table.
IF you want documentation about . . . | THEN see . . . |
---|---|
testing and debugging programs, |
|
individual OLAP DML commands, |
the topic for the command in OLAP DML Reference |
|
Copyright © 1996-2001, Oracle Corporation. All Rights Reserved. |
|