REXX error-handling instructions in procedures with logic

You can use REXX error-handling techniques, such as the REXX SIGNAL instruction, in a procedure with logic. In addition, you can use QMF commands and variables with the REXX EXIT instruction to help clarify nonzero return codes.

Branching to error-handling subroutines

The REXX signal on error instruction tells REXX to leave the current line and branch to a label marked error when a nonzero return code is encountered. This instruction requires two parts:

Signal on error
After every command, REXX puts the return code of the command in a variable called rc.

If a command has a nonzero return code, REXX branches to the error label.

In TSO, signal on error returns errors from the QMF REXX procedure (ADDRESS QRW) command environment, but not the REXX callable interface.
Error label
The signal on error instruction requires that you provide a label that the procedure can branch to if it encounters a nonzero return code. The label precedes your error-handling code. The return code is in the variable rc. You can use this variable to branch to another subroutine or you can use it in your EXIT instruction, as shown in the following figure.
Figure 1. QMF exits with a nonzero return code.
```
/*  error handling code for a procedure with logic */
error:
  exit rc
```

Using messages with the REXX EXIT instruction

You can use the REXX EXIT instruction to exit a procedure with logic. QMF always issues a message when it finishes running a procedure with logic. If you use the EXIT instruction, the message you see depends on these factors:

Whether the last QMF command encountered an error
Whether the return code was zero

The following table shows which message you see based on the conditions.

Table 1. Messages returned from QMF commands in procedures
Return code from last QMF command	Procedure return code	Message (or examples of messages) at completion of procedure
0	0	`OK, your procedure was run`
0	Nonzero	`The return code from your procedure was 8`
Nonzero	0	The error message provided by QMF
Nonzero	Nonzero	The error message provided by QMF

A QMF error message takes precedence over the return code message from the program if you have an incorrect QMF command and a nonzero return code.

If you want to show the error message from the last command and exit with a nonzero return code, use the MESSAGE command as in the following figure.

Figure 2. Specify MESSAGE to see the error message from the last command.

"MESSAGE (TEXT='"dsq_message_text"'"
exit rc

The variable dsq_message_text is a REXX variable that is provided by QMF. You can use the MESSAGE command and the dsq_message_text variable to store and display a message after further processing has occurred, as shown in the following figure.

Figure 3. The MESSAGE command displays the original error message.

 /* Monthly report */
   Signal on error
   "DISPLAY TABLE JUNE_INFO"
   "PRINT REPORT"
   Exit(0);
 Error:
   Original_msg = dsq_message_text    /* Saves error message. */
   "RUN PROC GENERAL_RECOVERY"        /* This proc generates  */
                                      /* new dsq_message_text. */
   "MESSAGE (TEXT='" Original_msg "'" /* Display original error msg. */
   Exit(8);