Request info pointer

The request info pointer points to a list of fullword fields that describe the exit request. The assembler sets this pointer, which is always a valid address.

Parameter list version

A fullword identifying the version of the parameter list. For High Level Assembler Release 6 this field contains a value of 3.

Exit type

A fullword identifying the type of exit being called. You use this field when the exit handles more than one exit type. The exit type is identified by the following values:

1
SOURCE Input
2
LIBRARY Input
3
LISTING Output
4
PUNCH Output
5
OBJECT Output
6
ADATA Output
7
TERM Output

The assembler always sets this field.

Request type

A fullword identifying the type of processing request. The request type is identified by these values:

1
OPEN--exit receives control before any input or output processing.
2
CLOSE--exit receives control before the assembler does any close processing.
3
READ--exit receives control to provide a record to the assembler.
4
WRITE--exit receives control to write a record provided by the assembler.
5
PROCESS (for exit types other than LIBRARY)--exit receives control to inspect or manipulate the record provided by the assembler.
5
PROCESS MACRO (LIBRARY exit type)--exit receives control to inspect or manipulate the macro definition record provided by the assembler.
6
PROCESS COPY (LIBRARY exit type)--exit receives control to inspect or manipulate the copy member record provided by the assembler.
7
FIND MACRO (LIBRARY exit type)--exit receives control to locate the specified library macro.
8
FIND COPY MEMBER (LIBRARY exit type)--exit receives control to locate the specified copy member.
9
END OF MEMBER (LIBRARY exit type)--exit receives control after the reading of a macro or copy member is completed.
10
REINIT--exit receives control during the assembler's reinitialisation processing between assemblies in a batch. This call only occurs if the exit requested the REINIT by setting reason code 16 in response to the OPEN request.

The assembler always sets this field.

Options

A fullword that provides additional information to the exit.

For the SOURCE and LIBRARY exits

These values are provided:

0
No additional information available.
1
New information is available in the Exit-Specific Information block. The assembler updates this block whenever the primary input data set changes.

For example, the SOURCE input might be a concatenation of data sets. When the first data set is opened, and when each subsequent concatenated data set is opened, this value is set to 1 to inform the exit that a data set switch has occurred. It is also set for LIBRARY processing to inform the exit which data set in the concatenation is being used to provide the specific member.

2
For the LIBRARY exit, when the request type is FIND MACRO or FIND COPY, this indicates that the copy code or a macro should resume at the saved record position.
3
For the LIBRARY exit, when the request type is FIND MACRO or FIND COPY, this indicates that copy code or a macro definition is currently being processed. The user exit should save the position within the current member to allow it to be resumed when the new member has been processed.

See Nesting COPY instructions and macro definitions.

For the LISTING exit

These decimal values are provided:

00
No additional information available
10
High Level Assembler Options Summary heading line
11
High Level Assembler Options Summary detail line
15
High Level Assembler Options Summary diagnostic message
17
High Level Assembler Product Information heading line
18
High Level Assembler Product Information detail line
20
External Symbol Dictionary heading line
21
External Symbol Dictionary detail line
30
Source and Object heading line
31
Source and Object machine instruction
32
Source and Object DC/DS instruction
33
Source and Object comment
34
Source and Object statement in error
35
Source and Object diagnostic message
36
Source and Object other
40
Relocation Dictionary heading line
41
Relocation Dictionary detail line
50
Ordinary Symbol and Literal Cross Reference heading line
51
Ordinary Symbol and Literal Cross Reference detail line
52
Unreferenced Symbols Defined in CSECTs heading line
53
Unreferenced Symbols Defined in CSECTs detail line
60
Macro and Copy Code Source Summary heading line
61
Macro and Copy Code Source Summary detail line
62
Macro and Copy Code Cross Reference heading line
63
Macro and Copy Code Cross Reference detail line
70
DSECT Cross Reference heading line
71
DSECT Cross Reference detail line
80
USING Map heading line
81
USING Map detail line
85
General Purpose Register Cross Reference heading line
86
General Purpose Register Cross Reference detail line
90
Diagnostic Cross Reference and Assembler Summary heading line
91
Diagnostic Cross Reference and Assembler Summary detail line
For the PUNCH, OBJECT, and ADATA exits

This field contains 0.

The assembler sets this field.

EXITCTLn

Four fullword fields containing the exit-control values for this exit type. Exit-control values are set by the EXITCTL assembler instruction during the assembly.

For the SOURCE and LIBRARY exits

The new EXITCTL values are available to the exit when the input record after the EXITCTL instruction is passed to the exit.

For the LISTING, ADATA, and TERM exits

The new EXITCTL values are available to the exit with the output record containing the EXITCTL instruction.

For the OBJECT and PUNCH exits

The new EXITCTL values are available to the exit when the next object module record is passed to the exit. This may happen several source statements after the EXITCTL instruction statement. A possible consequence is that one or more EXITCTL statements can be processed without the exit receiving the EXITCTL parameter values, if they occur between object records.

Return code

A fullword, set by the exit, that indicates success or failure of the exit call, and the action taken by the assembler on return from the exit. Table 11 summarizes the return codes.

Return code 20 is described at Error handling.

Table 11. User-exit return codes
Exit Request RC=0 4 8 16 207
SOURCE OPEN Assembler to open the primary input data set 1 Exit provides records 2   Disable 6 Operation failed
  CLOSE Operation successful       Operation failed
  READ Exit has provided record     End-of-file indicator Operation failed
  PROCESS Accept record Discard record   Disable 6 Operation failed
  REINIT Operation successful     Disable 6 Operation failed
LIBRARY OPEN Assembler to open its library 1 Exit has opened its library 3 Exit has opened its library, assembler to open its library Disable 6 Operation failed
  CLOSE Operation successful       Operation failed
  READ Exit has provided record     EOD on input source Operation failed
  PROCESS (macro or copy member) Accept record Discard record   Disable 5, 6 Operation failed
  FIND (macro or copy member) Operation successful Member not found; search assembler library if available     Operation failed
  END OF
MEMBER
Operation successful     Disable 5, 6 Operation failed
  REINIT Operation successful     Disable 6 Operation failed
LISTING
PUNCH
OBJECT(z/OS and CMS)
TERM
ADATA
OPEN Assembler opens the output data set 1 Exit has opened its output data set 4   Disable 6 Operation failed
  CLOSE Operation successful       Operation failed
  WRITE Exit has written record       Operation failed
  PROCESS Accept record Discard record   Disable 6 Operation failed
  REINIT Operation successful     Disable 6 Operation failed
Notes:
  1. The assembler only uses the PROCESS and CLOSE operation codes on subsequent calls.
  2. The assembler only uses the READ and CLOSE operation codes on subsequent calls.
  3. The assembler only uses the READ, FIND, and CLOSE operation codes on subsequent calls.
  4. The assembler only uses the WRITE and CLOSE operation codes on subsequent calls.
  5. This return is valid from all PROCESS and END OF MEMBER requests, with these exceptions:
    1. PROCESS MACRO requests when the LIBRARY exit set the return code of 8 for the OPEN request.
    2. PROCESS COPY requests when the LIBRARY exit set the return code of 8 for the OPEN request.
    3. END OF MEMBER requests when the LIBRARY exit set the return code of 4 or 8 for the OPEN request.
  6. If an exit sets the disable return code, then the assembler does not call that exit again, so any resource clean-up should be done before returning control to the assembler.
  7. See Error handling.

Reason code

A fullword, set by the exit, to qualify the return code. Table 12 shows reason codes for each exit type, and which request they are checked after.

Table 12. User exit reason codes
Exit Request RSN=0 4 8 16
SOURCE OPEN No additional information Input source information available REINIT call required
READ No additional information Input source information available Redrive requested 2
LIBRARY OPEN No additional information End of member call required REINIT call required
FIND (macro or copy member) No additional information Input source information available Redrive requested 2
READ No additional information Input source information available Redrive requested 2
LISTING
TERM
OPEN No additional information When return code is 0, reason code 4 indicates the exit has provided a line length in the buffer length field. When return code is 4, reason code 4 indicates the exit has provided the data set information. REINIT call required
SOURCE
LIBRARY
LISTING
PUNCH
OBJECT(z/OS and CMS)
TERM
ADATA
PROCESS No additional information Return to exit with empty buffer Redrive requested 2
LISTING
PUNCH
OBJECT(z/OS and CMS)
TERM
ADATA
WRITE No additional information Redrive requested 2
PUNCH
OBJECT(z/OS and CMS)
OPEN No additional information Exit has provided the output data set information REINIT call required
ADATA OPEN No additional information Exit has provided the output data set information Exit intends to discard type X'0002' and X'0090' records REINIT call required
Notes:
  1. Multiple reason codes can be specified by OR-ing them together.
  2. When redrive is requested, the assembler issues any required error message and then recalls the exit with the same parameter list as before.

Buffer length

A fullword containing the length of the area pointed to by the buffer pointer.

For OPEN requests

This field contains the length of the optional character string you specified in the EXIT assembler option.

For WRITE and PROCESS requests

This field contains the length of the record pointed to by the buffer pointer.

For READ requests

This field contains the length of the area pointed to by the buffer pointer where the exit may return a record to the assembler.

All other requests

This field contains zero.

Setting the length

When either the SOURCE, LIBRARY, PUNCH, or OBJECT exit is invoked for a READ, WRITE, or PROCESS request, the assembler sets the buffer length to 80.

On z/OS and CMS, if you specify the GOFF assembler option, and the OBJECT exit is invoked, the buffer length might be fixed-length 80, or variable-length, depending on the JCL (z/OS) you supply. The maximum value for variable-length records is 8212.

For an OPEN request the LISTING exit can use this field to pass the listing line length to the assembler. The exit indicates that it has provided a print line length by setting the return code to 0 and the reason code to 4.

z/VM and z/OS

The line length must be in the range 121 to 255. If it is any other value, the assembler issues message ASMA402W and does not call the exit to process listing records.

End of z/VM and z/OS
z/VSE

If the assembler opens the listing data set and the LISTING exit provides a print line length, the line length must be 121 if SYSLST is assigned to disk, otherwise it can be any value from 121 to 133. If it is any other value, the assembler issues message ASMA402W and does not call the exit to process listing records.

End of z/VSE

For all other calls to the LISTING exit, the assembler sets this field to the length determined during the OPEN call.

The TERM exit can use this field to indicate to the assembler the length of the terminal record. This may be done when the exit is invoked with an OPEN request. The exit indicates that it has provided a terminal line length by setting the Return Code to 0 and the Reason Code to 4. The value must not be zero, or negative, and must not be greater than 255 on z/OS and CMS, or 125 on z/VSE. If the value is not correct, the assembler issues message ASMA404W and does not call the exit to process terminal records.

For all other calls to the TERM exit, the assembler sets this field to the length determined during the OPEN call.

Error buffer length

An unsigned fullword, set by the exit, that contains the length of the text pointed to by the error buffer pointer. The maximum length is 255 bytes. If the exit specifies a larger value, the assembler uses 255.

The assembler uses this length to determine whether to issue an error message. If the length is greater than zero, the text in the error buffer is inserted into one of the messages ASMA700I to ASMA704C. The assembler selects which message to issue by checking the value of the error severity field.

The contents of the error buffer are ignored on CLOSE calls to the exit, unless the exit requests immediate termination. If immediate termination is requested, the assembler generates an ASMA940U message with the text provided by the exit; all remaining open exits are CLOSEd, but may not provide any additional message text.

Error severity

A fullword, set by the exit, that contains the severity code the assembler uses to determine which diagnostic message to issue.

The severity code should be a value of 0, 4, 8, 12, or 16. If the severity code is not one of these values, it is rounded up to the nearest value or, if the severity code is greater than 16, it is reset to 16.

The values 0, 4, 8, 12, and 16 correspond to the five diagnostic messages, ASMA700I through ASMA704C, respectively. For example, severity code of 4 causes the assembler to issue message ASMA701W. Table 13 summarizes the return code values and the associated diagnostic message.

Table 13. Error severity and associated diagnostic message
Error Severity Code
Specified
Error Severity Code
Used
Associated
Message
0 0 ASMA700I
1-4 4 ASMA701W
5-8 8 ASMA702E
9-12 12 ASMA703S
> 12 16 ASMA704C

User-defined field

A fullword, set to zero by the assembler before it calls the exit with an OPEN request. The exit can use this field to store information (such as the address of acquired storage) between calls. This field is separately maintained for each exit type and is preserved across all calls until the exit is closed. The assembler does not modify or interpret this field.

Common user field

A fullword, set to zero by the assembler. Any exit can use this to store information (such as the address of acquired storage) between calls. This field is common for all exit types and so provides a mechanism for different exits to share information. The assembler does not modify or interpret this field.


[ Top of Page | Previous Page | Next Page | Contents | Index ]