Standard header

All macros which are new and, as a rule, all existing macros which which have been extended by the 31-bit interface make use of the standard header in order to identify their interface.

The standard header is an 8-byte field at the beginning of the data area containing the (standardized) interface name plus 4 bytes reserved for a return code. The standard header is generated and initialized, i.e. supplied with the valid values for UNIT, FUNCTION and VERSION, by the corresponding macro. When using an E-form macro with reference to the data area, the caller may have to initialize the standard header. Where required, details are given in the macro description.

Structure of the standard header:

Byte	Field contents and meaning
0 - 1	Name of the unit containing the requested function
2	Name of the function within the unit
3	Name of the version of the function
4	SUBCODE2 of the return code
5	SUBCODE1 of the return code
6 - 7	MAINCODE of the return code

Table 3: Standard header

The following list gives the standard return code values which apply to all macros:

SUB- CODE2	SUB- CODE1	MAIN- CODE	Meaning
X'00'	X'00'	X'0000'	The function has been performed without errors. There is no information in addition to the MAINCODE.
X'01'	X'00'	X'0000'	The function has been performed without errors. No further action was required.
X'00'	X'01'	X'FFFF'	The requested function is not supported (incorrect entry for UNIT or FUNCTION in the standard header). Unrecoverable error.
X'00'	X'02'	X'FFFF'	The requested function is not available. Unrecoverable error.
X'00'	X'03'	X'FFFF'	The specified version of the interface is not supported (incorrect entry for VERSION in the standard header). Unrecoverable error.
X'00'	X'04'	X'FFFF'	Data area is not aligned on a word boundary.
X'00'	X'41'	X'FFFF'	The subsystem is not present and must be explicitly generated.
X'00'	X'42'	X'FFFF'	The calling task is not connected to this interface; the connection must be explicitly established.
X'00'	X'81'	X'FFFF'	The subsystem is currently not available.
X'00'	X'82'	X'FFFF'	The subsystem is in the DELETE or HOLD state.

Table 4: Standard return codes

MAINCODE indicates the result of function execution. SUBCODE1 qualifies MAINCODE. SUBCODE2 further qualifies the error by means of error classes or contains additional diagnostic information.
With all new macros, the return code should be supplied exclusively in the standard header. Some macro interfaces allow the return code to be passed in register R15, either as an alternative or in addition to being supplied in the standard header. The return code field should be initially set to X'FFFFFFFF' in order to permit checking whether a return code has been transferred to the standard header or not.

Example: generation of standard header

           WROUT    START
           PRINT NOGEN
           BALR  3,0
           USING *,3
  WROUT    AMODE ANY
  WROUT    RMODE ANY
           GPARMOD 31
1                 *,MACRO: GPARMOD, VERSION: VER121
           PRINT GEN
           WROUT OUTPUT,STOP
1          ##SPASS S0002S,S0002D                                     A312
2          CNOP  0,4
2          BAS   1,S0002S           ADDRESS AND SKIP PARAMS
1 S0002D     DS 0F                                                   A340
1          FHDR  UNIT=36,FUNCT=17,VERS=2
2          DS    0A
2          DS    0XL8                GENERAL OPERAND LIST HEADER
2          DC    AL2(36)             FUNCTION UNIT NUMBER
2          DC    AL1(17)             FUNCTION NUMBER
2          DC    AL1(2)              FUNCTION INTERFACE VERSION NUMBER
2          DC    X'FFFFFFFF'          Returncode is virgin
1 *
1          DC    AL4(STOP)                ERROR ADDRESS
1          DC    AL4(OUTPUT)              MESSAGE AREA ADDRESS
  *        :