ACQUIRE TERMINAL

Description

The ACQUIRE TERMINAL command enables you to tell CICS® to acquire a session with a particular terminal.

The terminal you specify must be a z/OS® Communications Server terminal, and it cannot be an APPC, LU6.1, or IRC session. It must already be defined to CICS, either in an installed TERMINAL definition or by the autoinstall process, and it must be local to the system on which the ACQUIRE TERMINAL is issued, not remote.

This means that, if the terminal was autoinstalled, you must issue the ACQUIRE command before CICS deletes the terminal definition.

CICS normally deletes an autoinstalled terminal definition if the session ends and is not reestablished within the interval specified in the AIRDELAY value in the system initialization table. The terminal does not have to be reacquired within this interval, however; after you issue the command, CICS suspends its timeout and does not delete the definition while waiting for the session to be reestablished.

CICS processes an ACQUIRE command by sending a SIMLOGON request to z/OS Communications Server (the queueing options on the command are for z/OS Communications Server use and correspond to those on a SIMLOGON request). The task that issued the command is dispatchable as soon as this occurs. It is not notified of the eventual result of the z/OS Communications Server request, nor when the terminal is acquired, and the terminal does not become associated with the task.

The request is sent straight to z/OS Communications Server unless the terminal is already in session with the requesting CICS system. If it is, and NOQUEUE or QNOTENAB are present, CICS rejects the request as invalid (because a SIMLOGON would fail under these circumstances). Otherwise, CICS stores the request until the terminal's current session ends and then sends it to z/OS Communications Server. For this reason, requests may be queued by z/OS Communications Server in a different order from the order in which they were originally issued.

After it has been issued, an ACQUIRE TERMINAL request cannot be canceled, and you cannot ordinarily determine whether an ACQUIRE TERMINAL has been issued for a particular terminal.

Options

NOQUEUE

specifies that z/OS Communications Server should not queue the request. Consequently, the ACQUIRE succeeds only if the terminal is immediately available.

QALL

specifies that z/OS Communications Server should queue the request if the terminal is not enabled for sessions or is at its session limit (that is, in session with another z/OS Communications Server application).

QNOTENAB

specifies that z/OS Communications Server should queue the request only if the terminal is not enabled for sessions.

QSESSLIM

specifies that z/OS Communications Server should queue the request only if the terminal is at its session limit (that is, in session with another z/OS Communications Server application).

RELREQ

is meaningful only if the QALL or QSESSLIM option is set. The RELREQ option specifies that, if the requested terminal is already in session with another z/OS Communications Server application, that application is notified of your request via its RELREQ exit routine. If RELREQ is not specified, the other application is not notified.

If the other application is a CICS system, the RELREQ value of the terminal definition in that system determines whether the request to release the terminal is honored. RELREQ is specified on the TYPETERM definition associated with the terminal.

TERMINAL(data-value)

is the 4-character identifier of the terminal with which CICS is to acquire a session.

USERDATA(data-value)

specifies the data area containing the logon user data, if any. z/OS Communications Server simulates a logon when CICS asks to acquire a terminal. This data corresponds to user data that sometimes accompanies a real logon. z/OS Communications Server passes it to the application (in this case, the requesting CICS system) when the terminal has been acquired successfully. See the description of the The EXTRACT LOGONMSG command command for programming information.

USERDATALEN(data-value)

specifies the length, as a halfword binary value, of the user data. Because of a z/OS Communications Server limitation, the maximum length of the user data is restricted to 255 bytes.

Conditions

INVREQ

RESP2 values:

2

The terminal is a remote terminal.

3

The terminal is LU6.1, APPC, IRC or a non-z/OS Communications Server device.

4

The terminal is not in service; that is, it is not available for use.

5

z/OS Communications Server is not open.

7

CICS is already in the process of acquiring this session.

8

NOQUEUE and QNOTENAB options are invalid for a logged-on device.

LENGERR

RESP2 values:

6

Out-of-range value supplied in the USERDATALEN option.

NOTAUTH

RESP2 values:

100

The user associated with the issuing task is not authorized to use this command.

TERMIDERR

RESP2 values:

1

The terminal cannot be found.