GDS ALLOCATE

Description

GDS ALLOCATE acquires a session to a remote system.

The return code is given in RETCODE (see Table 1). For a list of return code values, see the Return codes for APPC basic conversations . EXEC CICS® conditions are never raised on GDS commands.

Options

In general, the arguments can be replaced by absolute or relocatable assembler-language expressions.

CONVID(data-area)

specifies the 4-character application data area that is to contain the token returned by an ALLOCATE command to identify the allocated conversation. This token is required in subsequent GDS commands issued on the conversation.

MODENAME(name)

specifies the name of the mode group from which the session is to be acquired. If you specify SYSID and omit MODENAME, CICS selects a modename from those defined for the system.

NOQUEUE

specifies that the request to allocate a session is not to be queued when a suitable APPC session cannot be acquired immediately. A session is acquired immediately only if it is a bound contention winner that is not already allocated to another conversation.

The return code in RETCODE indicates whether or not a session has been acquired.

If the NOQUEUE option is not used, a delay may occur before control is passed back to the application program. A delay can occur for any of the following reasons:

• All sessions for the specified SYSID and MODENAME are in use.
• The CICS allocation algorithm has selected a session that is not currently bound (in which case, CICS has to bind).
• The CICS allocation algorithm has selected a contention loser (in which case, CICS has to bid).

If there is a delay, the program waits until the session has been acquired.

PARTNER(name)

specifies the name (eight characters) of a set of definitions that include the names of a remote LU (NETNAME) and a communication profile to be used on the allocated session. For APPC basic conversations, the only relevant attribute set by the profile is MODENAME.

If you use this option as an alternative to SYSID and MODENAME, CICS uses the NETNAME and MODENAME from the PARTNER definition.

RETCODE(data-area)

specifies the 6-byte application data area into which return code information (shown in Table 1) is to be moved.

STATE(cvda)

gets the state of the current conversation. The cvda values returned by CICS are:

• ALLOCATED
• CONFFREE
• CONFRECEIVE
• CONFSEND
• FREE
• PENDFREE
• PENDRECEIVE
• RECEIVE
• ROLLBACK
• SEND
• SYNCFREE
• SYNCRECEIVE
• SYNCSEND

SYSID(systemname)

specifies the remote system to which an APPC session is to be allocated. The name, which is 1–4 characters, identifies an entry (defined as an APPC connection) in the CICS terminal control table.