CREATE TERMINAL

Define a TERMINAL in the local CICS® region.

CREATE TERMINAL

CREATE TERMINAL attribute values

Conditions: ILLOGIC, INVREQ, LENGERR, NOTAUTH

Note to COBOL programmers: In the syntax above, you must use ATTRIBUTES(data-area) instead of ATTRIBUTES(data-value).

Description

The CREATE TERMINAL command installs a TERMINAL definition with the attribute specified on the command. It does not use a resource definition stored in the CSD. You can use them either to define individual terminals or a pool of terminals.

The POOL attribute determines which mode you are using. Without it, each command defines a single, independent terminal. If there is already a terminal with the name you specify in the local CICS region, the new definition replaces the old one; if not, the new definition is added.

To define a pool, you issue one CREATE TERMINAL ATTRIBUTES command for each terminal in the pool, specifying the same POOL value in the ATTRIBUTES string. After all of the terminals are defined, you issue CREATE TERMINAL COMPLETE; CICS collects but does not install the TERMINAL definitions until the COMPLETE command. At this point, if there was a pool of the same name in the local CICS region, CICS deletes all of its terminals and installs the new definitions; if not, it adds the new definitions. Consequently, pool terminals must be defined all at once; you cannot add terminals to an existing pool or include a terminal with the same name as an existing non-pool terminal.

During the time the pool is being built, you must not:

Change or omit the pool name
Define other resources of any type, including terminals outside the current pool
Issue a SYNCPOINT (or any command that implies one)
Terminate your task (normally)

However, if you encounter an error or problem during the course of building a pool, you can terminate the process at any point by issuing a CREATE TERMINAL DISCARD command. If you do this, CICS discards the partial pool definition, including all of its terminals.

A syncpoint is implicit in CREATE TERMINAL processing, as in other CREATE commands, except when an exception condition is detected early in the processing. Uncommitted changes to recoverable resources are committed when definitions are processed successfully, and rolled back if not or if you specify DISCARD. For non-pool terminals, the syncpoint occurs on each CREATE command. When you are building a pool, however, it occurs only on the command that ends the pool definition, whether you specify COMPLETE or DISCARD. See Creating resource definitions for other general rules governing CREATE commands.

Options

ATTRIBUTES(data-value)

specifies the attributes of the TERMINAL being added. The list of attributes must be coded as a single character string using the syntax shown in TERMINAL attributes. See The ATTRIBUTES option for general rules for specifying attributes, and TERMINAL definition attributes for details about specific attributes.

ATTRLEN(data-value)

specifies the length in bytes of the character string supplied in the ATTRIBUTES option, as a halfword binary value. The length may not exceed 32767 bytes.

COMPLETE

specifies that the terminal pool definition under construction is complete. It can be used only after the last terminal of a pool has been defined.

DISCARD

specifies that the terminal pool definition under construction is not to be completed, and all of the TERMINAL definitions issued since the pool was started are to be discarded and not added.

LOGMESSAGE(cvda)

Specifies whether CICS logs the attributes used for the resource that is created. CVDA values are as follows:

LOG: The resource attributes are logged to the CSDL transient data queue.
NOLOG: The resource attributes are not logged.

TERMINAL(data-value)

specifies the 4-character name of the TERMINAL definition to be added.

Conditions

ILLOGIC

RESP2 values:

2: The command cannot be executed because an earlier CONNECTION or TERMINAL pool definition has not yet been completed.

INVREQ

RESP2 values:

n: There is a syntax error in the ATTRIBUTES string, or an error occurred during either the discard or resource definition phase of the processing. See RESP2 values for EXEC CICS CREATE and EXEC CICS CSD commands for information on RESP2 values.
7: The LOGMESSAGE cvda value is not valid.
200: The command was executed in a program defined with an EXECUTIONSET value of DPLSUBSET or a program invoked from a remote system by a distributed program link without the SYNCONRETURN option.

LENGERR

RESP2 values:

1: The length specified in ATTRLEN is negative.

NOTAUTH

RESP2 values:

100: The user associated with the issuing task is not authorized to use this command.
102: The user associated with the task issuing the CREATE TERMINAL command is not an authorized surrogate of the user specified in USERID.