IMS Print Exit

IMS Print Exit functionality enables data otherwise destined for a printer to be redirected to the DFSPRINT exit routine.

Invocation

The print exit is invoked at run time.

Coding Requirements

To enable a print exit requires that you code an exit program named DFSPRINT, and also that you code an interface to DFSPRINT from your IMS COBOL program.

DFSPRINT

To enable the print exit functionality, you must code and build a module named DFSPRINT, and place the resulting executable in the directory specified by the ES_IMS_EXITPATH environment variable. Micro Focus provides a very basic DFSPRINT.cbl file to help you get started. DFSPRINT.cbl resides in your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\exits directory by default.

Important: The DFSPRINT print exit routine must be thread-safe.

Interface

Include the following interface in the Linkage-Section of your DFSPRINT program. The contents of this interface are sent to the DFSPRINT module:

01 print-exit-interface.
   03 data-destination     pic x(8).
   03 data-pending         pic x comp-x.
      88 more-to-come-88   value 1 false 0.
   03 page-count           pic x(4) comp-5.
   03 page-array-ptr       pointer.
01 page-array.
   03 page-data occurs 50 times depending on page-count.
      05 page-data-ptr     pointer.
      05 page-data-length  pic x(4) comp-5.

Field	Contents
data-destination	The name of the destination printer
more-to-come-88	If true, indicates that more data is to come for this print job
page-count	The number of pages in the array pointed to by page-array-ptr
page-array-ptr	Pointer to the page-array structure containing the print data
page-data-ptr	Pointer to the TN3270 data for a single page
page-data-length	The length of the data pointed to by page-data-ptr

Run-time Requirements

To enable print exit functionality, you must have the following in place:

DFSPRINT executable

The DFSPRINT executable must be in the directory specified by the ES_IMS_EXITPATH environment variable.

Enterprise Server environment variables

You must set the following environment variables in the enterprise server region that runs your IMS application:

ES_IMS_EXITPATH

Set this to point to the directory that contains your DFSPRINT executable.

ES_IMS_OTMA_DEST

Set the ES_IMS_OTMA_DEST environment variable to identify each printer destination that is specified in the application for which you want to redirect the print data to the exit routine. Each specified destination consists of the destination name, the NONOTMA keyword, and the LU type (LU1 or LU3) separated by commas. Each destination definition is separated by a semi-colon.

IMS_OTMA_DEST=printerName,NONOTMA,LUtype[;...]

Entries in the ES_IMS_OTMA_DEST environment variable are separated by semi-colons. Each entry consists of the printer destination name, the NONOTMA keyword, and the LU type (LU1 or LU3) separated by commas. For example:

ES_IMS_OTMA_DEST=IMSPRLU1,NONOTMA,LU1;IMSPRLU3,NONOTMA,LU3

Where the first printer destination specifies an LU1 printer named IMSPRLU1; and the second destination specifies an LU3 printer named IMSPRLU3.

Run-time Behavior

The following describes the run-time behavior expected when a print exit routine is present:

IMS calls the routine before initiating any printing. Print data is sent to the exit routine as a TN3270 data stream.
When DFSPRINT handles the print data, it assigns a return code of 0 (zero) to the return-code field and exits.
When IMS receives a return code of 0 from the exit routine, IMS bypasses normal print processing.
When IMS receives a non-zero return code from the exit routine, IMS handles the printing as normal.