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 length of the AIB the application actually obtained.

AIBSFUNC

Subfunction code. This field must contain one of these 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 program.

WAITAOI

When coded with an AOI token in the AIBRSNM1 field, WAITAOI indicates IMS is to wait for an AOI message when none is currently available for the application program. 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 on the right 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 that is padded on the right with blanks.

AIBOALEN

I/O area length. This field must contain the length of the I/O area 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 that is passed from IMS to the AO application program. If the I/O area is not large enough to contain all the data, IMS returns partial data.

Usage

GMSG is used in an AO application program to retrieve a message associated with an AOI token. The AO application program must pass an 8-byte AOI token to IMS in order to retrieve the first segment of the message. IMS uses the AOI token to associate messages from an AO exit routine of type AOIE, with the GMSG call from an AO application program. IMS returns to the application program only those messages associated with the AOI token. By using different AOI tokens, the AOIE type exit routine can direct messages to different AO application programs. 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 nonretrieved segments of a multisegment message when a new GMSG call that specifies an AOI token is issued.

Your AO application program can specify a wait on the GMSG call. If no messages are currently available for the associated AOI token, your AO application program waits until a message is available. The decision to wait is specified by the AO application program, 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 application program some GMSG calls can specify waits, while others do not. The following table shows, by IMS environment, the types of AO application programs that can issue GMSG. GMSG is also supported from a CPI-C driven program.

Restrictions

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