error handling

use HPAUTOCONT variable judiciously
- better -- continue command if hpcierr <> 0 then ...

RETURN vs. ESCAPE
- return goes back ONE level
- escape goes back to the CI level in a session, to an active CONTINUE, or can abort a job

Notes:

HPAUTOCONT = true is sometimes useful, but can be a dangerous practice. It allows every command to behave as if it is proceeded by a :CONTINUE command. This may be desired for some of the commands in a job or script, but not necessarily all of the commands. I find it safer and more reliable to leave HPAUTOCONT set to false (default) and to use an explicit :continue in front of each command that I want to test for success or failure. This allows me to control the behavior of the script, e.g., I can do some cleanup if an error occurs, and at the same time, it permits the script to abort if an unexpected failure arises.

I think that scripts are more maintainable and easier to read if the error checking portion reports the trouble and then simply exits. This is preferred to using constructs such as: if <error> then report problem… # Don’t handle errors this way if possible! else execute more code…

if <error> then report error # Do handle errors this way if possible! return endif

RETURN causes execution to resume in the calling environment. RETURN is useful as a method of exiting an alternate entry in a script or UDC. RETURN does not set CI error related variables and cannot directly cause the calling environment to abort. Returning from a script (command file) closes the file; however that is the only cleanup done automatically by the system. Scratch files, file equations, variable, etc., in general, should be cleaned up prior to exiting a script or UDC.

ESCAPE causes execution to resume at the main CI level for sessions, and at the calling environment if a :continue proceeded the invoking command. If the calling environment is a job and the invoking command was not “protected” by a :continue then ESCAPE will abort the job. Additionally, ESCAPE can set CIERROR and HPCIERR to an error number, but the default is to not alter these variables. ESCAPE mimics to some degree the TRY/ RECOVER / ESCAPE construct provided by Pascal, which is used by a large portion of the MPE operating system. ESCAPE is useful when a script or UDC needs to duplicate the CI’s error handling. This duplication can be further improved by exploiting the HPFSERR and HPCIERRCOL predefined variables, which provide the associated file system error (if any), and the column position of the offending command line parameter, where the CI would locate the caret (‘^”) in an error message.

The HPCIERRMSG string variable contains the error/warning message associated to the current value of the CIERROR variable. Note that parameter substitution is not performed in the error message, and thus, some messages will contain “!” as parameter place holders.

The ERRCLEAR command is useful in the initialization part of scripts to set all error related predefined CI variables to zero. It is more than twice as fast compared to setting all four variables individually. It is more than 25% faster than setting only HPCIERR and CIERROR to zero separately. It is slightly slower (7%) than setting only CIERROR to zero.

HPCIERR is signed -- CI warnings are negative, CI errors are positive. CIERROR contains the absolute value of HPCIERR -- thus there are no CI warnings with the same absolute value as a CI error. The CI keeps HPCIERR and CIERROR in sync, but users can change their values independent of each other.

use HPAUTOCONT variable judiciously