PURG call

The Purge (PURG) call allows your application program to send one or more output message segments (specified with the ISRT call) to the specified destination before the application program retrieves the next input message or issues a commit point.

For Spool API functions, the PURG call can also be used to release a print data set for immediate printing.

Format

Read syntax diagramSkip visual syntax diagramPURGi/o_pcbalternate_pcbaibi/o_areamod_name
Call Name DB/DC DBCTL DCCTL DB Batch TM Batch
PURG X   X    

Parameters

i/o pcb
Specifies the I/O PCB, the first PCB address in the list that is passed to the program. This parameter is an input and output parameter.
alternate pcb
Specifies the PCB to use for the call. These parameters are input and output parameters.
aib
Specifies the application interface block (AIB) that is used for the call. This parameter is an input and output parameter.
The following fields must be initialized in the AIB:
AIBID
Eye catcher. This 8-byte field must contain DFSAIBbb.
AIBLEN
AIB lengths. This field must contain the actual length of the AIB that the application program obtained.
AIBRSNM1
Resource name. This 8-byte, left-justified field must contain the PCB name IOPCBbbb (if the TP PCB is used), or the name of an alternate PCB (if an alternate PCB is used).
AIBOALEN
I/O area length. This field must contain the length of the I/O area that is specified in the call list.
i/o area
Specifies the I/O area to use for this call. This parameter is an input parameter. The I/O area must be large enough to hold the largest segment passed between the program and IMS TM.
mod name
Specifies the MOD you want used for this output message. This parameter is an input parameter. The 8-byte MOD name must be left justified and padded with blanks as necessary. PURG can specify the MOD name for the first message segment for an output message. If the terminal receiving the output does not use MFS, this parameter is ignored. If you specify a valid MOD name, IMS TM uses that MOD to format the screen for the output message you are sending.

Usage

Use the PURG call to send output messages to several different terminals. A PURG call tells IMS TM that the message built against the specified I/O PCB, or alternate PCB (with the ISRT call) is complete. IMS TM collects the message segments that have been inserted into one PCB as one message and sends the message to the destination specified by the destination name of the alternate PCB listed in the PURG call.

If you specify an I/O area in the PURG call parameters, PURG acts as an ISRT call to insert the first segment of the next message. When you identify the I/O area, you can also specify a MOD name to change the screen format.

In the OTMA environment

An IMS application program that issues a PURG call causes IMS to call the Open Transaction Manager Access (OTMA) Prerouting and Destination Resolution exit routines to determine the destination. For information on these exit routines, see IMS Version 15.3 Exit Routines.

In the shared queues environment

A STATUSQF can be received on a PURG call in a shared queues environment if the MSGQ structure is full. If the MSGQ structure is full, one of the following can happen:

  • If the PURG is for a multi-segment message, STATUSQF will be received.
  • If the PURG for a multi-segment message still completes correctly (enough space) but not enough space is found to be available at PURG or CHKP time, the application will abend with ABENDU0370.
Spool API functions

You can use the PURG call with an express alternate PCB to release a print data set for immediate printing. When you issue the PURG call with an I/O area, IMS treats the call as two functions: the purge request, and the insertion of data provided by the I/O area.

If you issue the PURG call:

  • Against an express alternate PCB, the data set is closed, unallocated, and released for printing. The destination is reset.
  • With an I/O area against a non-express alternate PCB, the purge function is ignored and the data in the insert portion of the call is put into the print data set. This means that the call behaves like an ISRT call.
  • With no I/O area against an express alternate PCB, the data set is closed, unallocated, and released for printing. IMS returns a status code of blanks.
  • With no I/O area against a non-express alternate PCB, no action is taken.

Restrictions

CPI-C driven application programs can only issue the PURG call to alternate PCBs.

MOD name can be specified only once per message, in the first ISRT or PURG call that begins the message. For conversational transactions, if the first ISRT is the SPA, the MOD name can either be provided on the SPA ISRT or on the first ISRT of a message segment.

This call is not supported in an IFP.

For synchronized APPC/OTMA conversations or OTMA commit-then-send (CM0) transactions with TMAMIPRG indicator set in the OTMA prefix, PURG calls on the TP PCB are ignored. The next ISRT call is processed for the next segment of the current message.