Acquire a session to a remote LUTYPE6.1 logical unit.
ALLOCATE (LUTYPE6.1)
>>-ALLOCATE--+-SESSION(name)-----+--+---------------+----------->
'-SYSID(systemname)-' '-PROFILE(name)-'
>--+---------+-------------------------------------------------><
'-NOQUEUE '
Conditions: CBIDERR, EOC, INVREQ, SESSBUSY, SESSIONERR, SYSBUSY,
SYSIDERR
Description
ALLOCATE acquires an alternate facility
and optionally selects a set of session-processing options. If SYSID is specified, CICS® makes
available to the application program one of the sessions associated with the
named system. The name of this session can be obtained from EIBRSRCE in the
EIB. If SESSION is specified, CICS makes the named session available.
If
the session requested is not available, the application is suspended until
the 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.
Options
- NOQUEUE
- overrides
the default action when a SESSBUSY or SYSBUSY condition arises. These conditions
indicate that the session requested is not immediately available. The default
action is to suspend application execution until the 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 SESSBUSY or 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.
- PROFILE(name)
- specifies
the name (1–8 characters) of a set of session-processing options that are
to be used during execution of terminal control commands for the session specified
in the SYSID or SESSION options. If the PROFILE option is omitted, a default
profile (DFHCICSA) is selected.
- SESSION(name)
- specifies
the symbolic identifier (1–4 characters) of a session TCTTE. This option specifies
the alternate facility to be used.
- SYSID(systemname)
- specifies
the name (1–4 characters) of a system TCTSE. This option specifies 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.
- 06 EOC
- occurs
when a request/response unit (RU) is received with the end-of-chain indicator
set. Field EIBEOC also contains this indicator.
Default action: ignore
the condition.
- 16 INVREQ
- occurs
when the specified session is already allocated to this task, or the session
is an APPC session.
Default action: terminate the task abnormally.
- 60 SESSBUSY
- occurs
if the request for the specified session cannot be serviced immediately. This
is only possible if the NOQUEUE option is set, or a HANDLE CONDITION for SESSBUSY
is active.
Default action: ignore the condition.
- 58 SESSIONERR
- occurs
if the name specified in the SESSION option is not that of an LUTYPE6.1 session
TCTTE, or if the session cannot be allocated because it is out of service.
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.
- 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.