ISRT call

For Spool API functions, the ISRT call is also used to write data to the JES Spool.

Format

>>-ISRT--+-i/o_pcb-------+--i/o_area--+----------+-------------><
         +-alternate_pcb-+            '-mod_name-'   
         '-aib-----------'                           

Parameters

i/0 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 this 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 be used for the call. This parameter is an input parameter. The I/O area must be large enough to hold the largest segment passed between the application 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. 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

To issue the ISRT call successfully, your application program must first build the message you want to send in the application program's I/O area. The ISRT uses the destination name in the I/O PCB or alternate PCB, and the I/O area that you specify in the call, to locate the message to be sent. The ISRT call then sends the output message from your application program to another terminal. ISRT sends one message segment per issue, so your application program must issue one ISRT call for each segment of the message in the I/O area.

You can also specify a MOD name if you want to change the screen format. For example, if the application program detects an error and must notify the person at the terminal, you can specify a MOD name that formats the screen to receive the error message. ISRT and PURG are the only DL/I calls that allow you to specify a MOD name on the first segment of an output message.

When your application program issues one or more ISRT calls, IMS TM groups the message segments to be sent in the message queue. IMS TM sends the message segments to the destination when the application program does one of the following:

• Issues a GU call to retrieve the first segment of the next message
• Reaches a commit point
• Issues a PURG call on an express alternate PCB

Your application must also use the ISRT call to issue replies to other terminals in conversational programs and to pass a conversation between application programs.

A STATUSQF can be received on an ISRT 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 ISRT is for a multi-segment message, STATUSQF will be received.
• If the ISRT 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.
• If the ISRT is for a single segment message, STATUSQF can be received. If the program continues to insert further messages that cause all available device relative record number (DRRN) to be exhausted, IMS will fail with ABENDU0758. If the program issues a checkpoint before exhausting all available DRRN, queue buffers will be freed and the messages will be written on the log as “unresolved UOWEs.” Logs containing the original type01 and type03 log records are needed to later insert the messages in the structure if space becomes available and must not be reused. IMS will issue message DFS1994I to remind the user at every check point time.

You can use the ISRT call to write data to the JES Spool. These writes are done using BSAM and, if possible, each BSAM "write" is done directly from the application program's buffer area.

Restriction: BSAM does not support the I/O area for sysout data sets above the 16-MB line. If IMS finds an I/O area above the 16-MB line, it moves the application data to a work area below the line before it performs the BSAM write. If the I/O area is already below the line, the write is done directly from the I/O area. Do not take unusual steps to place the I/O area below the line unless performance indicates a need to do so.

When you issue the ISRT call for an alternate PCB set up for IAFP processing, prefix the I/O area with a BSAM block descriptor word for variable length records.

Restrictions

A CPI-C driven application program can only issue the ISRT call to an alternate PCB.

If you want to send message segments before retrieving the next message or issuing a commit point, you must use the PURG call.

MOD name can be specified only once per message, on the first ISRT or PURG call that begins the message.

BSAM does not support the I/O area for sysout data above the 16 MB line.