ALLOCATE (APPC)
Allocate a session to a remote APPC logical unit for use by an APPC mapped conversation.
Description
ALLOCATE makes one of the sessions associated with the named system available to the application program, and optionally selects a set of session-processing options.
CICS® returns, in EIBRSRCE in the EIB, the 4-byte CONVID (conversation identifier) that the application program uses in all subsequent commands that relate to the conversation.
If a session to the requested APPC LU is not available, the application is suspended until a session does become available. In such a case, the suspension of the application can be prevented by specifying either the NOQUEUE or the NOSUSPEND option. NOSUSPEND is still supported as an equivalent for NOQUEUE, but NOQUEUE is the preferred keyword.
- A contention winner
- Already bound
- Not already allocated
- Contention winner that is bound and not already allocated (CICS allocates it). This is a session that is immediately available.
- Contention winner that is unbound (CICS binds it and allocates it).
- Contention loser that is bound and not already allocated (CICS bids for it).
- Contention loser that is unbound (CICS binds it and bids for it).
- HANDLE for SYSBUSY condition issued
- The command is not queued and control is returned immediately to the label specified in the HANDLE command, whether or not you have specified NOQUEUE.
- No HANDLE issued for SYSBUSY condition
- If you have specified NOQUEUE (or NOSUSPEND), the request is not queued and control is returned immediately to your application program. The SYSBUSY code (X'D3') is set in the EIBRCODE field of the EXEC interface block. You should test this field immediately after issuing the ALLOCATE command.
If you have omitted the NOQUEUE option, and you have not issued a HANDLE command for the SYSBUSY option, then if no session is immediately available, CICS queues the request (and your application waits) until a session is available. The request is allocated a session either when a winner session has become available, or when CICS has successfully bid for a loser session. Omit the NOQUEUE option when you want all winner or loser sessions to be considered for allocation to the request. You can use the QUEUELIMIT and MAXQTIME attributes of the CONNECTION resource definitions to limit the length of the queue of requests, and the time that requests spend on the queue. Managing allocate queues has more information about allocate queues. The DTIMOUT value specified on the transaction definition can be used to limit the wait time for individual requests.
Options
- NOQUEUE
- overrides
the default action when a SYSBUSY condition arises. This indicates
that a session is not immediately available. The default action is
to suspend application execution until a session is available. NOQUEUE
inhibits this waiting; control returns immediately to the application
program instruction following the command.
Note, however, that if a HANDLE CONDITION for SYSBUSY is active when the command is executed, this also overrides the default action, and control is passed to the user label supplied in the HANDLE CONDITION. This takes precedence over the NOQUEUE option but is, of course, negated by either NOHANDLE or RESP.
If an APPC ALLOCATE request is issued against a single session connection from the contention loser end, the NOQUEUE option always causes SYSBUSY to be returned rather than allowing the request to bid for the session. If the NOQUEUE option is absent, the request is able to bid for the session.
If an APPC ALLOCATE request is issued against a parallel session connection, and the NOQUEUE option is specified, only sessions that are immediately available (that is, a contention winner that is bound and not already allocated) can be allocated to the request. If no such session is available, then SYSBUSY is returned. If the NOQUEUE option is absent, the request is able to bid for a loser session, or bind unbound winner sessions.
- PARTNER(name)
- specifies the name (8 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. You can use this option as an alternative to specifying SYSID and PROFILE explicitly.
- PROFILE(name)
- specifies the name (1-8 characters) of a set of session-processing options that are to be used during the execution of mapped commands for the session specified in the SYSID option. If you specify SYSID and omit PROFILE, a default profile (DFHCICSA) is selected.
- STATE(cvda)
- gets the state of the current conversation. The cvda value returned by CICS is ALLOCATED.
- SYSID(systemname)
- specifies the name (1-4 characters) by which the remote APPC LU is known to this CICS. This option requests that one of the sessions to the named system is to be allocated.
Conditions
- 62 CBIDERR
- occurs
if the requested PROFILE cannot be found.
Default action: terminate the task abnormally.
- 16 INVREQ
- occurs
if the ALLOCATE command is not valid for the device to which it is
directed.
Default action: terminate the task abnormally.
- 99 NETNAMEIDERR
- occurs
if the name specified in the NETNAME parameter of the RDO definition
for the PARTNER specified on the allocate command is invalid.
Default action: terminate the task abnormally.
- 97 PARTNERIDERR
- occurs
if the name specified in the PARTNER option is not recognized by CICS.
Default action: terminate the task abnormally.
- 59 SYSBUSY
- occurs
for one of the following reasons:
- The request for a session cannot be serviced immediately. This is only possible if the NOQUEUE option is set, or a HANDLE CONDITION for SYSBUSY is active.
- The ALLOCATE command is issued when persistent session recovery is still in process and the sessions needed to satisfy the command are not yet recovered.
Default action: ignore the condition.
- 53 SYSIDERR
- occurs
if CICS is unable to provide
the application program with a suitable session, for one of the following
reasons:
- The name specified in the SYSID option is not recognized by CICS.
- The mode name derived from the PROFILE option is not one of the mode names defined for the APPC system entry.
- All the sessions in the group specified by SYSID and mode name are out of service, or all sessions are out of service.
- The AID (automatic initiate descriptor) representing your ALLOCATE has been canceled.
- All the sessions are busy and the (queued) allocates have been purged or rejected.
Default action: terminate the task abnormally.