Processing of LIBEXIT

The LIBEXIT exit module is used in place of the SYSLIB, or library-name, data set. Calls are made to the module by the compiler to obtain copybooks whenever COPY or BASIS statements are encountered.

Table 1. LIBEXIT processing
Action by compiler Action by exit module
Loads the exit module (mod2) during initialization  
Calls the exit module with an OPEN operation code (op code) Prepares the specified library-name for processing. Passes the status of the OPEN request to the compiler.
Calls the exit module with a FIND op code if the library-name was successfully opened Establishes positioning at the requested text-name (or basis-name) in the specified library-name; this place becomes the active copybook. Passes an appropriate return code to the compiler when positioning is complete.
Calls the exit module with a GET op code Passes the compiler either the length and address of the record to be copied from the active copybook or the end-of-data indicator
Calls the exit module with a CLOSE op code when the end-of-data is presented Releases any resources that are related to its input

Processing of LIBEXIT with nested COPY statements

Any record from the active copybook can contain a COPY statement.

You cannot make recursive calls to text-name. That is, a copybook can be named only once in a set of nested COPY statements until the end-of-data for that copybook is reached.

The following table shows how the processing of LIBEXIT changes when there are one or more valid COPY statements that are not nested.

Table 2. LIBEXIT processing with nonnested COPY statements
Action by compiler Action by exit module
Loads the exit module (mod2) during initialization  
Calls the exit module with an OPEN operation code (op code) Prepares the specified library-name for processing. Passes the status of the OPEN request to the compiler.
Calls the exit module with a FIND op code if the library-name was successfully opened Establishes positioning at the requested text-name (or basis-name) in the specified library-name; this place becomes the active copybook. Passes an appropriate return code to the compiler when positioning is complete.
Calls the exit module with a FIND op code if the library-name was successfully opened Reestablishes positioning at the previous active copybook. Passes an appropriate return code to the compiler when positioning is complete.
Calls the exit module with a GET op code. Verifies that the same record was passed. Passes the compiler the same record as was passed previously from this copybook. After verification, passes either the length and address of the record to be copied from the active copybook or the end-of-data indicator.
Calls the exit module with a CLOSE op code when the end-of-data is presented Releases any resources that are related to its input

The following table shows how the processing of LIBEXIT changes when the compiler encounters a valid nested COPY statement.

Table 3. LIBEXIT processing with nested COPY statements
Action by compiler Action by exit module
If the requested library-name from the nested COPY statement was not previously opened, calls the exit module with an OPEN op code Pushes its control information about the active copybook onto a stack. Completes the requested action (OPEN). The newly requested text-name (or basis-name) becomes the active copybook.
Calls the exit module with a FIND op code for the requested new text-name Pushes its control information about the active copybook onto a stack. Completes the requested action (FIND). The newly requested text-name (or basis-name) becomes the active copybook.
Calls the exit module with a GET op code Passes the compiler either the length and address of the record to be copied from the active copybook or the end-of-data indicator. At end-of-data, pops its control information from the stack.

LIBEXIT parameters

The compiler uses 10 parameters, passed by reference, to communicate with the exit module. The return code, data length, and data parameters are set by the exit module for return to the compiler; the other items are passed from the compiler to the exit module.

Table 4. LIBEXIT parameters
Parameter number Parameter item Description of item
1 User-exit type Halfword that identifies which user exit is to perform the operation.

2=LIBEXIT

2 Operation code Halfword that indicates the type of operation:
  • 0=OPEN
  • 1=CLOSE
  • 2=GET
  • 4=FIND
3 Return code Fullword, set by the exit module, that indicates the success of the requested operation:
  • 0=Operation was successful
  • 4=End-of-data
  • 12=Operation failed
4 User-exit work area Six-fullword work area provided by the compiler for use by the user-exit module.

Second word: for use by LIBEXIT

5 Data length Fullword, set by the exit module, that specifies the length of the record being returned by the GET operation (must be 80)
6 Data or str2 Fullword, set by the exit module, that contains the address of the record in a user-owned buffer, for the GET operation.

str2 applies only to OPEN. The first halfword (on a halfword boundary) contains the length of the string, followed by the string.

7 System library-name Eight-character area that contains the library-name from the COPY statement. Processing and conversion rules for a program-name are applied. Padded with blanks if required. Applies to OPEN, CLOSE, and FIND.
8 System text-name Eight-character area that contains the text-name from the COPY statement (basis-name from BASIS statement). Processing and conversion rules for a program-name are applied. Padded with blanks if required. Applies only to FIND.
9 Library-name Thirty-character area that contains the full library-name from the COPY statement. Padded with blanks if required, and used as is (not folded to uppercase). Applies to OPEN, CLOSE, and FIND.
10 Text-name Thirty-character area that contains the full text-name from the COPY statement. Padded with blanks if required, and used as is (not folded to uppercase). Applies only to FIND.