Allocate a session to a remote APPC logical unit for
use by an APPC mapped conversation.
ALLOCATE (APPC)
>>-ALLOCATE--+-SYSID(systemname)--+---------------+-+----------->
| '-PROFILE(name)-' |
'-PARTNER(name)------------------------'
>--+---------+--+-------------+--------------------------------><
'-NOQUEUE-' '-STATE(cvda)-'
Conditions: CBIDERR, INVREQ, NETNAMEIDERR, PARTNERIDERR,
SYSBUSY, SYSIDERR
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 session is immediately available
for allocation only if it is all of the following:
- A contention winner
- Already bound
- Not already allocated
CICS attempts to satisfy a request for a session by choosing
among sessions in the following order of preference:
- 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).
The action taken by CICS if no session
is immediately available depends on whether you specify NOQUEUE (or
the equivalent NOSUSPEND option), and also on whether your application
has executed a HANDLE command for the SYSBUSY condition. In these
situations, CICS does not bid for sessions or bind additional sessions.
It looks for a session that is immediately available (that is, a contention
winner that is bound and not already allocated), and if one is not
available, the SYSBUSY condition is returned. The possible combinations
are shown below:
- 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.
The HANDLE for SYSBUSY condition therefore has the
same effect as the NOQUEUE option, except for where control is returned
in the application. If the HANDLE command is used, control is returned
to the label, and if it is not used, control is returned to the instruction
following 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.