GU call

The Get Unique (GU) call retrieves the first segment of a message.

Format

Read syntax diagramSkip visual syntax diagramGUi/o_pcbaibi/o_area
Call Name DB/DC DBCTL DCCTL DB Batch TM Batch
GU 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.
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.
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 output parameter. The I/O area must be large enough to hold the largest segment passed between the program and IMS TM.

Usage

An MPP or message-driven BMP uses two calls to retrieve input message from the host: GN and GU. A GU call retrieves the first segment of a message. The Get Next (GN) call retrieves subsequent segments.

When you issue a successful GU or GN, IMS TM returns the message segment to the I/O area that you specify in the call. Message segments are not all the same length. Because the segment length varies, your I/O area must be long enough to hold the longest segment that your program can receive. The first two bytes of the segment contain the length of the segment.

Your application program must issue a GU call to the message queue before issuing other DL/I calls. When IMS TM schedules an MPP, the Transaction Manager transfers the first segment of the first message to the message processing region. When the MPP issues the GU for the first message, IMS TM already has the message waiting. If the application program does not issue a GU message call as the first call of the program, IMS TM has to transfer the message again, and the efficiency provided by message priming is lost.

If an MPP responds to more than one transaction code, the MPP has to examine the text of the input message to determine what processing the message requires.

After a successful GU call, IMS TM places the following information in the I/O PCB mask:

  • The name of the logical terminal that sent the message.
  • The status code for this call. (See the topic "I/O PCB mask" in IMS Version 15.5 Application Programming)
  • The input prefix, giving the date, time, and sequence number of the message at the time it was first queued. IMS returns both an 8-byte local date containing a 2-digit year and a 12-byte time stamp (local or UTC time) containing a 4-digit year.
  • The MOD name (if you are using MFS).
  • The user ID of the person at the terminal, or if user IDs are not used in the system, the logical terminal name. If the message is from a BMP, IMS TM places the PSB name of the BMP in this field.
  • Group name, used by DB2® to provide security for SQL calls.

Related reading: For more information on the format of the I/O PCB mask, see the topic "Specifying the I/O PCB Mask" in IMS Version 15.5 Application Programming.

Restrictions

The AIB must specify the I/O PCB for this call.

You cannot issue a GU call from a CPI-C driven application program.