Input record exit

ACIF provides an exit that you can use to add, delete, or modify records in the input file. You can also use the exit to insert indexing information. The program that is run by this exit is defined in the INPEXIT parameter.

This exit is called after each record is read from the input file and before any further processing is done on the input record. The exit can request that the record is discarded, processed, or processed and that control is 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 libraries.

The EXTENSION=PASSPF parameter controls whether a Begin Print File (BPF) and End Print File (EPF) structured field pair that the input record exit tries to insert is actually inserted. If PASSPF is not specified and the input record tries to insert a BPF/EPF pair, the attempt fails and the pair is discarded.

In a MO:DCA-P document, indexing information can be passed in the form of a Tag Logical Element (TLE) structured field (see Tag Logical Element (TLE) structured field for more information). 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 (FIELDn, INDEXn, and TRIGGERn) to index the NOPs. You can use this alternative instead of modifying the application in cases where the indexing information is not consistently present in the application output.

AIX or Windows sample input record exit C language header contains a sample C language header that describes the control block that is passed to the AIX or Windows exit program.

typedef struct _INPEXIT_PARMS /* Parameters for the input record exit   */
{
   char           *work;    /* Address of 16-byte static work area      */
   PFATTR         *pfattr;  /* Address print file attribute information */
   char           *record;  /* Address of the input record              */
   unsigned short in_CCSID; /* Input CCSID for translating              */
   unsigned short out_CCSID;/* Output CCSID for translating             */
   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 that contains the following parameters is passed to the input record exit. For AIX and Windows, the address is passed by the first parameter.

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 fullword boundary and is initialized to binary zeros before the first call. The user-written exit program must provide the code that is required to manage this work area.

pfattr(Bytes 5–8)

A pointer to the print file attribute data structure. For more information about the format of this data structure and the information it contains, see Attributes of the input print file.

record(Bytes 9–12)

A pointer to the first byte of the input record that includes the carriage control character. The record is in buffer storage that is allocated by ACIF, but the exit program is allowed to modify the input record.

in_CCSID(Bytes 13-14)

The value from the INPCCSID parameter.

out_CCSID(Bytes 15-16)

The value from the OUTCCSID parameter.

recordln(Bytes 17–18)

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.

When you are using the INPCCSID and OUTCCSID parameters, the actual length of the field might differ from the input record length if you are converting to or from UTF-16 data.

Note: ACIF issues message 0425-419 with Return Code 999 (RC=999) and stops processing if the input exit returns a zero length record.

reserved2(Bytes 19–20)

These bytes are reserved for future use.

request(Byte 21)

An indication of 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 is to be processed by ACIF.

X'01'

Specifies that the record is not to be processed by ACIF.

X'02'

Specifies that the record is to be processed by ACIF and that control is returned to the exit program so it can 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 extra 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 be in the buffer at any time.

eof(Byte 22)

An end-of-file (EOF) indicator. This indicator is a 1-byte character code that specifies whether an EOF condition is encountered. When eof is signaled (eof=y), the last record is already presented to the input exit, and the input file is closed. The pointer record is no longer valid. Records cannot be inserted when eof is signaled. These values are the only valid values for this parameter:

y

Specifies that eof is encountered.

n

Specifies that eof is not encountered.

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