GMSG call

Format

Parameters

aib

Specifies the application interface block (AIB) to be used for this call. This parameter is an input and output parameter.

You must initialize the following fields 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.

AIBSFUNC

Subfunction code. This field must contain one of the listed 8-byte subfunction codes:

8-blanks (null)

When coded with an AOI token in the AIBRSNM1 field, indicates IMS is to return when no AOI message is available for the application.

WAITAOI

When coded with an AOI token in the AIBRSNM1 field, indicates IMS is to wait for an AOI message when none is currently available for the application. This subfunction value is invalid if an AOI token is not coded in AIBRSNM1. In this case, error return and reason codes are returned in the AIB.

The value WAITAOI must be left justified and padded with a blank character.

AIBRSNM1

Resource name. This field must contain the AOI token or blanks. The AOI token identifies the message the AO application is to retrieve. The token is supplied for the first segment of a message. If the message is a multisegment message, set this field to blanks to retrieve the second through the last segment. AIBRSNM1 is an 8-byte alphanumeric left-justified field padded with blanks.

AIBOALEN

I/O area length. This field must contain the length of the I/O area that is specified in the call list. This field is not changed by IMS.

AIBOAUSE

Length of the data returned in the I/O area. This parameter is an output parameter.

When partial data is returned because the I/O area is not large enough, AIBOAUSE contains the length required to receive all of the data, and AIBOALEN contains the actual length of the data.

i/o area

Specifies the I/O area to use for this call. This parameter is an output parameter. The I/O area should be large enough to hold the largest segment passed from IMS to the AO application. If the I/O area is not large enough to contain all of the data, IMS returns partial data.

Usage

GMSG is used in an AO application to retrieve a message associated with an AOI token. The AO application must pass an 8-byte AOI token to IMS to retrieve the first segment of the message. IMS uses the AOI token to associate messages from the AO exit routine of type AOIE, with the GMSG call from an AO application. IMS returns to the application only those messages associated with the AOI token. By using different AOI tokens, the AOIE type exit routine can direct messages to different AO applications. Note that your installation defines the AOI token.

To retrieve the second through the last segments of a multisegment message, issue GMSG calls with no token specified (set the token to blanks). If you want to retrieve all segments of a message, you must issue GMSG calls until all segments are retrieved. IMS discards all non-retrieved segments of a multisegment message when a new GMSG call specifying an AOI token is issued.

Your AO application can specify a wait on the GMSG call. If no messages are currently available for the associated AOI token, your AO application waits until a message is available. The decision to wait is specified by the AO application, unlike a WFI transaction where the wait is specified in the transaction definition. The wait is done on a call basis; that is, within a single AO application some GMSG calls might specify waits while others do not.

The following table shows, by IMS environment, the types of application programs that can issue GMSG. GMSG is also supported from a CPI-C driven application program.

Restrictions

A CPI-C driven program must issue an APSB (allocate PSB) call before issuing GMSG.