The input data user-exit program
The InfoPrint Manager input data user-exit program can be used to:
- Monitor the incoming print data stream to InfoPrint Manager
- Discard an input record before it is processed
- Replace an existing input record with one or more records (which might include the original record or a modified version of the original record)
- Continue processing with the input record unchanged
If you are using the exit to insert extra input records, the original input record that is passed to the exit can be processed before or after the extra input records. This means that the extra input records can be inserted before or after the current structured field depending on where the current structured field is placed in the list of structured fields to insert.
Because of the constraints outlined above, you should first consider using the transform subsystem to process data, because the transform subsystem does not have these limitations. For example, a transform object would have access to all of the input data (no restrictions) and could add, delete, and modify both resources and pages. In addition, the transform subsystem processing is done before printing begins, so it would have no impact on printer performance or behavior.
The input data user-exit is not capable of identifying individual document boundaries in a data stream. For example, your job might have 5 separate documents that each contain 10 pages of data. This is viewed by the exit as 50 pages of data, not 5 units of 10. The transform subsystem does not have this limitation.
The PSF Input Record Exit is responsible for managing any memory it allocates. It
can reuse the memory across calls through the use of a work area pointer provided
ainuexit.h. PSF does not free any memory that might be pointed to by fields in either the
INDATA_EXITDATA structure or the
PSFINSERTRECS structure. The exit can point to memory that it has defined or allocated. The exit
can reuse allocated memory or free memory when it is appropriate. PSF might run out
of memory if the PSF Input Record Exit mismanages memory.
The source code (in the C programming language) for the sample input data user-exit program listed on page What sample user-exit programs are available? is in the /usr/lpp/psf/exits/ainuxind.c file. This sample program consists of a return code and performs no function.
The data structures for the input data user-exit program are included with the source code in the /usr/lpp/psf/exits/ainuexit.h file.
The declaration of this exit is:
void INDATA (INDATA_EXITDATA *exitdata)
The INDATA_EXITDATA input/output parameter contains all of the input and output data needed to communicate between InfoPrint Manager and the user-exit program.
These fields are also found in the input data user-exit:
- This variable was formerly called
reserved1. It is designed for use as a migration aid for future variants of this exit. It contains a version identifier for this structure:
- X'00'= previous version (before August, 2005)
- X'01'= August, 2005 version adding support for deletion and insertion of input records
- Indicates which copy is associated with this call to the exit. Initially set to 1, it increments by one each time the exit is called.
- Contains the length of the input data record
- Points to the input data record to be processed.
- Always set to 0 (AFP; MO:DCA data only).
Note: If the exit is being called to indicate end of job processing:
- DataSize is set to 0,
- DataPointer is set to NULL
- DataType is set to 0 — no record is passed in at that time
The PSFINSERTRECS structure contains information about a structured field that is to be inserted at the request of the input data exit. The PSFINSERTRECS structure contains these fields:
- Version identifies to PSF the version of the PSFINSERTRECS structure that is being supplied. The exit must supply a value of 0x01 or the record
next_ppointer) is ignored.
- Contains the pointer to the next record to insert.
- Contains the pointer to the MO:DCA (AFP) structured field to be inserted.
See more data definitions and comments in the
ainuexit.h source file located in /usr/lpp/psf/exits/.
After you create your input data user-exit program, you must use the make command to compile the code (see Compiling and installing the user-exit program).