Input record exit

ACIF provides an exit that enables you to add, delete, or modify records in the input file. You can also use the exit to insert indexing information.

For example, imagine that you have unformatted ASCII data, such as a phone bill which contains two consecutive asterisks (**) to distinguish each page break. You can use the exit to add carriage control characters to the data so that ACIF can recognize where page breaks should occur. The program invoked at this exit is defined in the INPEXIT parameter.

This exit is called after each record is read from the input file. The exit can request that the record be discarded, processed, or processed and control returned to the exit for the next input record. The largest record that can be processed is 32756 bytes. This exit is not called when ACIF is processing resources from directories (libraries on z/OS® ).

In a MO:DCA-P document, indexing information can be passed in the form of a Tag Logical Element (TLE) structured field. The exit program can create these structured fields while ACIF is processing the print file. You can insert No Operation (NOP) structured fields into the input file in place of TLEs and use ACIF's indexing parameters (FIELD, INDEX, and TRIGGER) to index the NOPs. This is an alternative to modifying the application in cases where the indexing information is not consistently present in the application output.

Important: TLEs are not supported in line-mode or mixed-mode data.
The following example contains a sample C language header that describes the control block that is passed to the exit program. 
typedef struct _INPEXIT_PARMS /* Parameters for the input record exit        */
{
   char           *work;      /* Address of 16-byte static work area         */
   PFATTR         *pfattr;    /* Address of print file attribute information */
   char           *record;    /* Address of the input record                 */
   void           *reserved1; /* Reserved for future use                     */
   unsigned short recordln;   /* Length of the input record                  */
   unsigned short reserved2;  /* Reserved for future use                     */
   char           request;    /* Add, delete, or process the record          */
   char           eof;        /* EOF indicator                               */
} INPEXIT_PARMS;
The address of the control block containing the following parameters is passed to the input record exit:
work (Bytes 1–4)
A pointer to a static, 16-byte memory block. The exit program can use this parameter to save information across calls (for example, pointers to work areas). The 16-byte work area is aligned on a full word boundary and is initialized to binary zeros prior to the first call. The user-written exit program must provide the code required to manage this work area.
pfattr (Bytes 5–8)
A pointer to the print file attribute data structure. See the attributes of the input file for more information on the format of this data structure and the information it contains.
record (Bytes 9–12)
A pointer to the first byte of the input record including the carriage control character. The record resides in a buffer that resides in storage allocated by ACIF, but the exit program is allowed to modify the input record.
reserved1 (Bytes 13–16)
These bytes are reserved for future use.
recordln (Bytes 17–18)
Specifies the number of bytes (length) of the input record. If the input record is modified, this parameter must also be updated to reflect the actual length of the record.
reserved2 (Bytes 19–20)
These bytes are reserved for future use.
request (Byte 21)
Specifies how the record is to be processed by ACIF. On entry to the exit program, this parameter is X'00'. When the exit program returns control to ACIF, this parameter must have the value X'00', X'01', or X'02', where:
X'00'
Specifies that the record be processed by ACIF.
X'01'
Specifies that the record not be processed by ACIF.
X'02'
Specifies that the record be processed by ACIF and control returned to the exit program to allow it to insert the next record. The exit program can set this value to save the current record, insert a record, and then supply the saved record at the next call. After the exit inserts the last record, the exit program must reset the request byte to X'00'. Refer to the asciinpe.c input record exit for details.

A value of X'00' on entry to the exit program specifies that the record be processed. If you want to ignore the record, change the request byte value to X'01'. If you want the record to be processed, and you want to insert an additional record, change the request byte value to X'02'. Any value greater than X'02' is interpreted as X'00', and the exit processes the record.

Note: Only one record can reside in the buffer at any time.
eof (Byte 22)
An End-Of-File (eof) indicator. This indicator is a one-byte character code that specifies whether an eof condition has been encountered. When eof is signaled (eof value=‘Y’), the last record has already been presented to the input exit, and the input file has been closed. The record pointer is no longer valid. Records might not be inserted when eof is signaled. The valid values for this parameter:
Y
Specifies that eof has been encountered.
N
Specifies that eof has not been encountered.

This end-of-file indicator allows the exit program to perform some additional processing at the end of the print file. The exit program cannot change this parameter.

The following example contains a sample DSECT that describes the control block for the z/OS exit program. 
PARMLIST DSECT          Parameters for the input record exit
WORK@    DS    A        Address of 16-byte static work area
PFATTR@  DS    A        Address of print-file-attribute information
RECORD@  DS    A        Address of the input record
         DS    A        Reserved for future use
RECORDLN DS    H        Length of the input record
         DS    H        Reserved for future use
REQUEST  DS    X        Add, delete, or process the record
EOF      DS    C        EOF indicator
The address of the control block containing the following parameters is passed to the input record exit. For z/OS , the address is passed to a standard parameter list pointed to by Register 1.
WORK@ (Bytes 1–4)
A pointer to a static, 16-byte memory block. The exit program can use this parameter to save information across calls (for example, pointers to work areas). The 16-byte work area is aligned on a full word boundary and is initialized to binary zeros prior to the first call. The user-written exit program must provide the code required to manage this work area.
PFATTR@ (Bytes 5–8)
A pointer to the print file attribute data structure. See attributes of the input file for more information about the format of this data structure and the information that it contains.
RECORD@ (Bytes 9–12)
A pointer to the first byte of the input record including the carriage control character. The record resides in a buffer that resides in storage allocated by ACIF, but the exit program is allowed to modify the input record. The record resides in a 32 KB (where KB equals 1024 bytes) buffer.
RESERVED1 (Bytes 13–16)
These bytes are reserved for future use.
RECORDLN (Bytes 17–18)
Specifies the number of bytes (length) of the input record. If the input record is modified, this parameter must also be updated to reflect the actual length of the record.
RESERVED2 (Bytes 19–20)
These bytes are reserved for future use.
REQUEST (Byte 21)
Specifies how the record is to be processed by ACIF. On entry to the exit program, this parameter is X'00'. When the exit program returns control to ACIF, this parameter must have the value X'00', X'01', or X'02', where:
X'00'
Specifies that the record be processed by ACIF.
X'01'
Specifies that the record not be processed by ACIF.
X'02'
Specifies that the record be processed by ACIF and control returned to the exit program to let it insert the next record. The exit program can set this value to save the current record, insert a record, and then supply the saved record at the next call. After the exit inserts the last record, the exit program must reset the REQUEST byte to X'00'.

A value of X'00' on entry to the exit program specifies that the record is to be processed. If you want to ignore the record, change the REQUEST byte value to X'01'. If you want the record to be processed, and you want to insert an additional record, change the REQUEST byte value to X'02'. Any value greater than X'02' is interpreted as X'00', and the exit processes the record.

Remember: Only one record can reside in the buffer at any time.
EOF (Byte 22)
An end-of-file (EOF) indicator. This indicator is a one-byte character code that specifies whether an EOF condition has been encountered. When EOF is signaled (EOF=Y), the last record has already been presented to the input exit, and the input file has been closed. The pointer RECORD@ is no longer valid. Records cannot be inserted when EOF is signaled. The only valid values for this parameter:
Y
Specifies that EOF has been encountered.
N
Specifies that EOF has not been encountered.

This end-of-file indicator lets the exit program perform some additional processing at the end of the print file. The exit program cannot change this parameter.