Return information and error flags (return codes)

Return information

The transfer of information to the calling program is an integral part of the function of a number of macros. This information is sometimes stored in register R1 or transferred to a program area whose address is specified in the macro. The mode of transfer of such information is indicated in the description of the relevant macro.

Error flags (return codes)

After a macro has been executed, the calling program is informed of the successful or unsuccessful result of the macro. This is effected by transferring a return code.
Depending on the relevant macro interface, the return code may be transferred either in register R15 or in the standard header. Some macros allow a combination of these two cases.

1.Transferring the return code in the standard header

(Part of standard header)
+---------------+
|   |   |   |   |
|c|c|b|b|a|a|a|a|
+---------------+

aaaa = main code

bb cc

= subcode1 = subcode2

The main code is transferred in the two rightmost bytes. It identifies the result of the function execution. Subcode 1 is used for error classification. Subcode 2 subdivides the error into error classes or contains additional diagnostic information. All parts of the return code are specified in hexadecimal notation. For information on the structure and contents of the standard header, see "Standard header".

1. Transferring the return code in register R15

R15:

+---------------+
|   |   |   |   |
|b|b| | | | |a|a|
+---------------+

aa = primary return code
bb = secondary return code

The primary return code is transferred in the rightmost byte of register R15. It indicates whether or not the function was executed successfully.
If no error occurred during execution, the rightmost byte contains the code X'00'. If an error occurred during the execution of a macro, the Executive places an error flag in the form of a different hexadecimal code in this byte (the three leftmost bytes each contain X'00' provided that nothing else has been specified explicitly).
In some cases, the information provided by the primary return code is supplemented by a secondary return code in the leftmost byte of register R15. This code provides more detailed information on the cause of the error. The secondary return code, too, is specified in hexadecimal notation. It is the user's responsibility to analyze this code and to take proper action.
The return code values and their meaning are given under “Return information and error flags” in each macro description.

If the code values of the primary return code are given with an increment of X'04' and a guaranteed maximum value is defined, the return code can be processed using a branch table (consisting of 4-byte branch instructions).
The return codes of many macros do not have such a fixed structure. Such return codes must be processed with explicit queries (compare instructions).

An example follows for each of these two types of processing.

Return code of the OPCOM macro

X'aa'	Meaning
X'00'	ITC participation has been started.
X'04'	Error in operand specification. ITC participation has not been started.
X'08'	ITC name is already assigned. ITC participation is not started.
X'0C'	No system memory available for starting ITC or the system-internal size for receive queues is exceeded. ITC participation is not started.
X'10'	ITC participation has already been declared.

Example of return code processing with a branch table

  RCTAB    START
           PRINT NOGEN
           BALR  3,0
           USING *,3
  *        :
           OPCOM ITCNAME       * Declare ITC participation
1                 *,MACRO: OPCOM, VERSION: VER041
           B     RS00(15)
  CONTINUE EQU   *
  *        :
  END      TERM
  RS00     B     CONTINUE      * R15=00: No error handling
           B     OPERR         * R15=04
           B     NAMEERR       * R15=08
           B     MEMERR        * R15=0C
  EXIST    NOP   EXIST         * R15=10:
  *                              EXISTING ITC PARTICIPATION handling
           B     END
  OPERR    NOP   OPERR         *         OPERAND ERROR handling
           B     END
  NAMEERR  NOP   NAMEERR       *         DUPLICATE NAME handling
           B     END
  MEMERR   NOP   MEMERR        *         MEMORY ERROR handling
           B     END
           END

Example of return code processing with explicit query

  RCEXPL   START
           PRINT NOGEN
           BALR  3,0
           USING *,3
  *         :
           OPCOM ITCNAME       * Declare ITC participation
1                 *,MACRO: OPCOM, VERSION: VER041
           LTR   15,15
           BZ    CONTINUE      * R15 = X'00'
           C     15,=F'4'
           BE    OPERR         * R15 = X'04'
           C     15,=F'8'
           BE    NAMEERR       * R15 = X'08'
           C     15,=F'12'
           BE    MEMERR        * R15 = X'0C'
           C     15,=F'16'
           BE    EXIST         * R15 = X'10'
  *        :                   ***
  *        :                   * Handling of other return codes
  *        :                   ***
  CONTINUE EQU   *
  *        :
  END      TERM
  *
  OPERR    NOP   OPERR         * OPERAND ERROR handling
           B     END
  NAMEERR  NOP   NAMEERR       * DUPLICATE NAME handling
           B     END
  MEMERR   NOP   MEMERR        * MEMORY ERROR handling
           B     END
  EXIST    NOP   EXIST         * EXISTING ITC PARTICIPATION handling
           B     END
  *        :
           END