VMS-to-Unix Phrase Book
[an error occurred while processing this directive]

3.2  Using STDERR and Exit Codes

Problem

You want your scripts to work like standard Unix utilities when issuing error messages and returning an exit status.

Solution

Use the echo command with redirection to STDERR, and the exit command with an integer exit code.

Discussion

Both VMS and Unix share the ideas of standard I/O channels that are automatically connected to a script or program at launch time, as well as using integer return values to indicate if the program completed the task successfully, or if there were problems.

VMS UNIX Description
SYS$INPUT STDIN Input data source.
SYS$OUTPUT STDOUT Output data sink.
SYS$ERROR STDERR Error message sink.
SYS$COMMAND -- Command input source.

In DCL scripts, the DCL write command can be used to write data to any data channel open for output by explicitly naming that channel:

    write sys$error "Uh oh..."
In Unix, the echo command is the method normally used by shell scripts for writing output to STDOUT. To use echo to issue error messages, you need to redirect it's STDOUT to STDERR. Using bourne style shells (sh, ksh, bash), the easiest way to do this is:
    echo "Uh oh..." >&2

Both VMS and Unix use the concept of exit codes for indicating the ultimate success or failure of an exiting process. With VMS, there is an elaborate system used for indicating the severity of errors, the registering of unique exit codes to specific applications and software vendors, and an automatic association of exit codes with message strings, allowing for easy internationalization of such messages without having to change or relink programs. In contrast, Unix is much more like MS-DOS in this respect. The numbering scheme (if any) used for exit codes are unique to that particular program. The basic convention is that an exit code of 0 means success, and any other positive value means an error or other advisory condition occurred. Some utilities, such as grep may use a set of different error codes to indicate conditions such as:

0 Successful completion; a match was found.
1 Successful completion; no match was found.
>1 Error completion; a syntax error was found or a file was inaccessible, even if matches were found in other files.

To allow your own scripts to be used by other scripts, your script should explicitly return an exit status using a convention similar to the one above. For example:

    if ( sort file1 file2 file3 >/tmp/all-files )
    then ... process the files ...
    else echo "$0: error creating output file" >&2
         exit 2
    fi;
You'll also want to document which codes are returned under which conditions. If you do not explictily call exit, or call it with no status value, your script will exit with the status of the last command run. Thus it is best to always set the exit code yourself whenever you can.

See Also

3.5 - Detecting Program Errors;
Chapter 10 of [an error occurred while processing this directive];
Chapter 46 of [an error occurred while processing this directive].

[an error occurred while processing this directive]
[an error occurred while processing this directive]