SET TERMINAL
Change some terminal attributes and cancel outstanding AIDs.
Conditions: INVREQ, NORMAL, NOTAUTH, TERMIDERR
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
Description
The SET TERMINAL command changes some of the values of a named terminal definition. It cannot be used for APPC sessions.
Only PURGETYPE, PURGE, or FORCEPURGE can be used for IRC sessions.
If a terminal TCTTE is available in a remote system, in either model or surrogate form, a change can be made to TRACING or NEXTTRANSID in the remote definition. This change is not shipped back to the TOR. This allows the user to make a change that applies only to the remote TCTTE.
The SET TERMINAL command can also be used to change the UCTRANST option of a surrogate terminal. This change is shipped back to the TOR and intermediate systems. Any attempt to change any other attribute for a model or surrogate terminal results in INVREQ with RESP2=24.
The SET TERMINAL command is not audited.
Options
- ACQSTATUS(cvda) (z/OS® Communications Server only)
- This option is retained only for compatibility purposes. You should use the TERMSTATUS option in new applications.
- ALTPRINTER(data-value)
- Specifies the
name of a 3270 printer for use as an alternative to the printer defined on the PRINTER option. The
name can be up to four characters long. Note: You cannot specify ALTPRINTER for a terminal that does not have a primary printer defined (on the PRINTER parameter).
See TERMINAL resources for information about the PRINTER and ALTPRINTER parameters for defining primary and alternate printers for terminals.
Note: For z/OS Communications Server terminals, in a transaction routing environment, this command does not take effect until the next flow across the link from the TOR to the AOR for the named terminal. - ALTPRTCOPYST(cvda)
- Specifies
the alternate printer copy status. This indicates whether CICS® is to use the hardware COPY feature to satisfy a print request on the printer named on
the ALTPRINTER parameter. CVDA values are:
- ALTPRTCOPY
- CICS is to use the hardware COPY feature to satisfy a print request on the alternate printer.
- NOALTPRTCOPY
- CICS is not to use the hardware COPY feature.
Note: You cannot specify ALTPRTCOPY for a terminal that does not have an alternate printer defined.See TERMINAL resources for information about the ALTPRINTCOPY parameter, which specifies the use of the hardware copy feature for the alternate printer on the terminal definition.
- ATISTATUS(cvda)
- Specifies
whether the terminal can be used by transactions that are automatically
initiated from within CICS or,
if the terminal is an ISC session, by transactions that are using
this session as an alternate facility to communicate with another
system. CVDA values are:
- ATI
- The terminal can be used by automatically initiated transactions.
- NOATI
- The terminal cannot be used by automatically initiated transactions.
A terminal cannot have both NOATI and NOTTI in its status.
- CREATESESS(cvda) (z/OS Communications Server only)
- Specifies
whether the terminal can be acquired automatically by ATI transactions.
CVDA values are:
- CREATE
- The terminal can be acquired automatically.
- NOCREATE
- The terminal cannot be acquired automatically.
- DISCREQST(cvda)
- Specifies
whether CICS is to honor a
disconnect request from the terminal. CVDA values are:
- DISCREQ
- CICS honors a disconnect
request for a z/OS Communications
Server device, and issues a z/OS Communications
Server CLSDST macro instruction to terminate the z/OS Communications Server session with that
logical unit.
It also means that CESF LOGOFF (or GOODNIGHT) from the terminal causes disconnection.
- NODISCREQ
- CICS does not honor a disconnect request for a z/OS Communications Server device.
- EXITTRACING(cvda)
- Specifies
whether the activity associated with the terminal exit program is
to be traced. CVDA values are:
- EXITTRACE
- Exit program activity is to be traced.
- NOEXITTRACE
- Exit program activity is not to be traced.
- MAPNAME(data-area)
- Specifies the 7-character name of the map that is to be saved (stored) by CICS as the name of the last map sent to this device. If this terminal is a surrogate, the map name specified is returned in the DETACH sequence to the terminal-owning region when the currently executing transaction terminates, unless the map name is superseded by a subsequent SEND MAP command. You can use the MAPNAME option to restore a map name that was returned to the application program in a previous INQUIRE TERMINAL command. If the terminal is not supported by BMS (for example, this terminal is a session), an INVREQ condition is raised with a RESP2 value of 60.
- MAPSETNAME(data-area)
- Specifies the 8-character name of the mapset that is to be saved by CICS as the name of the last mapset used in a SEND MAP command processed for this terminal. If this terminal is a surrogate, the mapset name specified is returned in the DETACH sequence to the terminal-owning region when the currently executing transaction terminates, unless the mapset name is superseded by a subsequent SEND MAP command. The MAPSETNAME option can be used to restore a mapset name that was returned to the application program in a previous INQUIRE TERMINAL command. If the terminal is not supported by BMS (for example, this terminal is a session), an INVREQ condition is raised with a RESP2 value of 60.
- NEXTTRANSID(data-value)
- Specifies
the next transaction identifier for the specified terminal. The identifier
can be up to 4 characters long. If you specify the NEXTTRANSID parameter
as blanks (X'40404040'), CICS sets
the next transaction identifier to nulls, meaning there is no NEXTTRANSID
defined for the terminal.
Changes are permitted to a remote TCTTE, but the change is not shipped back to the TOR.
Note: NEXTTRANSID cannot be set if a transaction has been defined for this terminal. - OBFORMATST(cvda)
- Specifies whether
the device supports outboard formatting. See TYPETERM resources for details
of the types of device that support outboard formatting. CVDA values are:
- NOOBFORMAT
- The device does not support outboard formatting.
- OBFORMAT
- The device supports outboard formatting.
Note: OBFORMATST cannot be specified for a console or 3790. - OPERID(data-value)
- Specifies an operator identification code that is to be associated with the terminal. The identification code can be up to 3 characters long. The operator identification code will continue to be associated with the terminal until it is changed by another SET TERMINAL OPERID command, or until the user signed on at the terminal changes (i.e. until a user signs on or signs off at the terminal).
- PAGESTATUS(cvda)
- Specifies
how pages are to be written. CVDA values are:
- AUTOPAGEABLE
- Pages, after the first in a series, are to be written to the terminal automatically.
- PAGEABLE
- Pages, after the first in a series, are to be written to the terminal on request from the operator.
- PRINTER(data-value)
- Specifies the
name of the primary printer CICS is to use in response to a
print request (either an ISSUE PRINT command, or a PRINT request from an operator pressing a program
access (PA) key). The name can be up to 4 characters long. See Terminals for printing for
information about specifying 3270-type printers. Note: For z/OS Communications Server terminals, in a transaction routing environment, this command does not take effect until the next flow across the link from the TOR to the AOR for the named terminal.
- PRTCOPYST(cvda)
- Specifies
whether CICS is to use the hardware COPY feature to satisfy a
print request on the printer named on the PRINTER parameter. CVDA values are:
- NOPRTCOPY
- CICS is not to use the hardware COPY feature.
- PRTCOPY
- CICS is to use the hardware COPY feature to satisfy a print request on the primary printer.
Note: You cannot specify PRTCOPY for a terminal that does not have a printer defined.See TERMINAL resources for information about the PRINTCOPY parameter, which specifies the use of the hardware copy feature for the primary printer on the terminal definition.
- PURGETYPE(cvda)
- Specifies
whether transactions running with the named terminal can be purged.
CVDA values are:
- CANCEL
- AIDs queuing for the specified terminal are to be canceled. AIDs
representing scheduled and allocated requests waiting in the local CICS system for the specified terminal
are canceled. However, CRSR AIDs and TD AIDs with an associated
triggered task already started are not canceled.
When a canceled scheduled request is found to have a precursor in a remote CICS system, this remote AID is canceled asynchronously. Message DFHTF0100 is written to CSMT to indicate how many AIDs have been deleted for the terminal and how many remain.
- FORCEPURGE
- Transactions are to be purged immediately. This can lead to unpredictable results and should be used only in exceptional circumstances.
- Kill
- The task is to be terminated. System and data integrity is not guaranteed. The KILL option extends the PURGE and FORCEPURGE options. It should be used only after an attempt has been made to PURGE or FORCEPURGE a task. The KILL option does not guarantee integrity of any kind but in some situations it allows the user to free up a stalled region enabling the region to continue processing. In some cases, for example, if a task is killed during backout processing, CICS terminates abnormally.
- PURGE
- The transactions can be terminated only if system and data integrity can be maintained. A transaction is not to be purged if its definition specifies SPURGE=NO.
FORCEPURGE replaces PURGE FORCE, which is retained only for compatibility purposes. You should use FORCEPURGE in new applications.
PURGETYPE cannot be specified for non-z/OS Communications Server terminals.
- RELREQST(cvda)
- Specifies
the status for releasing the logical unit. CVDA values are:
- NORELREQ
- CICS is not to release the logical unit upon request by another z/OS Communications Server application program.
- RELREQ
- CICS is to release the logical unit, if the logical unit is not currently busy running a transaction.
- SERVSTATUS(cvda)
- Specifies
whether the terminal is to be in- or out-of-service. CVDA values are:
- INSERVICE
- CICS is to set the terminal in-service and available for use.
- OUTSERVICE
- CICS is to set the terminal
out-of-service, and not available for transactions. Unless you specify
PURGE or FORCEPURGE, any current transaction is allowed to terminate
normally, but no further transactions are allowed to use the terminal.
If the execution diagnostic facility (EDF) is in use at the specified terminal, EDF stops immediately, because it is a sequence of separate transactions, while the transaction that is being tested under EDF is allowed to complete.
If you set a z/OS Communications Server terminal to OUTSERVICE, it is also RELEASED and the operator is signed off, either immediately or when the current transaction has terminated. You cannot therefore set the terminal associated with the executing transaction to OUTSERVICE, unless it is a printer.
- TCAMCONTROL(data-value) (TCAM/DCB remote terminals only)
- Obsolete. TCAM terminals are not supported.
- TERMINAL(data-value)
- Specifies
the 4-character terminal name. Note: As a result of the operation of the XICTENF and XALTENF global user exits, it is possible for SCHEDULE requests to be queued for a terminal that is not yet defined to the local CICS system. You can use the SET TERMINAL(data-value) CANCEL command to remove these requests.
- TERMPRIORITY(data-value)
- Specifies, as a fullword binary value, the priority required for the terminal, relative to other terminals, in the range 0–255.
- TERMSTATUS(cvda) (z/OS Communications Server only)
- Specifies
the session status for the logical unit represented by this terminal.
CVDA values are:
- ACQUIRED
- CICS is to acquire a session with the logical unit represented by this terminal.
- COLDACQ
- CICS is to acquire a session with the logical unit represented by this terminal where no resynchronization is required.
- RELEASED
- CICS is to terminate the session. This happens immediately if you also specify the PURGE option, otherwise the session is terminated when the current active transaction finishes.
- TRACING(cvda)
- Specifies
the required tracing activity associated with the terminal. CVDA values
are:
- SPECTRACE
- Special tracing is to be used.
- STANTRACE
- Standard tracing is to be used.
Changes are permitted to a remote TCTTE, but the change is not shipped back to the TOR.
- TTISTATUS(cvda)
- Specifies
whether this terminal can be used by the transactions that are initiated
from this terminal. CVDA values are:
- NOTTI
- This terminal cannot be used by transactions initiated from it.
- TTI
- This terminal can be used by transactions initiated from it.
A terminal cannot be defined with both NOATI and NOTTI.
- UCTRANST(cvda)
- Specifies
whether the uppercase translate option is to be set for transactions
associated with this terminal. Note that there is also an UCTRAN option
on the profile definition. See Table 1 for
information on how the UCTRAN options on the terminal and transaction
profiles interact.
If a terminal TCTTE is available in a remote system, in either model or surrogate form, a change can be made to TRACING or NEXTTRANSID in the remote definition. This change is not shipped back to the TOR. This allows the user to make a change which applies only to the remote TCTTE. The SET TERMINAL command can also be used to change the UCTRANST option of a surrogate terminal. This change is shipped back to the TOR and intermediate systems. Attempting to change any other attribute for a model or surrogate terminal results in INVREQ with RESP2=24.
This command may be used to set the uppercase translation option for a remote terminal, if the named terminal is the principal facility of the task issuing the command. If the remote terminal is not the principal facility, the INVREQ condition is raised with a RESP2 value of 24. The uppercase translation option is also changed in the terminal-owning region and any intermediate region in a daisy-chaining setup. CVDA values are:- NOUCTRAN
- CICS is not to perform uppercase translation on input from this terminal (unless specified otherwise on the profile for individual transactions).
- TRANIDONLY
- CICS is to perform uppercase translation on the transaction id only on input from this terminal.
- UCTRAN
- CICS is to perform uppercase translation on input from this terminal.
Table 1. The effect of the UCTRAN parameters Profile Terminal (TYPETERM) UCTRAN (YES) UCTRAN (NO) UCTRAN (TRANID) UCTRAN (YES) Tranid: Yes Data: Yes Tranid: No Data: Yes Tranid: Yes Data: Yes UCTRAN (NO) Tranid: Yes Data: Yes Tranid: No Data: No Tranid: Yes Data: No Note: This table shows which portion of the terminal input is translated (transaction id and/or data) according to the setting of the UCTRAN on the PROFILE and TYPETERM resource definitions. - ZCPTRACING(cvda)
- Specifies
the required tracing activity associated with the z/OS Communications Server control component
of CICS. CVDA values are:
- NOZCPTRACE
- z/OS Communications Server ZCP tracing is not to be carried out.
- ZCPTRACE
- z/OS Communications Server ZCP tracing is to be carried out.
Conditions
- INVREQ
- RESP2 values:
- 1
- TERMSTATUS or ACQSTATUS was specified for an IRC session or non-z/OS Communications Server terminal.
- 2
- TERMSTATUS or ACQSTATUS has an invalid CVDA value.
- 4
- ATISTATUS has an invalid CVDA value.
- 5
- ATISTATUS change would result in NOATI and NOTTI.
- 6
- CREATESESS was specified for non-z/OS Communications Server terminal.
- 7
- CREATESESS has an invalid CVDA value.
- 9
- PAGESTATUS has an invalid CVDA value.
- 11
- Trying to put the issuing terminal OUTSERVICE.
- 13
- SERVSTATUS has an invalid CVDA value.
- 15
- TERMPRIORITY value not in range 0–255.
- 17
- NOTTI cannot be specified for the issuing terminal.
- 18
- TTISTATUS has an invalid CVDA value.
- 21
- PURGETYPE has an invalid CVDA value.
- 22
- TRACING has an invalid CVDA value.
- 24
- Invalid option requested for a remote terminal.
- 25
- ACQUIRED specified, but terminal is not in service.
- 26
- PURGE specified, but target task has SPURGE=NO on its associated transaction definition.
- 27
- EXITTRACING has an invalid CVDA value.
- 28
- ZCPTRACING has an invalid CVDA value.
- 29
- EXITTRACING or ZCPTRACING specified for a non-z/OS Communications Server terminal (or z/OS Communications Server not installed).
- 31
- This is a remote terminal with no associated surrogate.
- 33
- SET TERMINAL is not valid for an LU6.2 (APPC) session.
- 34
- A permanent transaction has been defined for this terminal (TRANSACTION operand in TERMINAL definition).
- 35
- Attempt made to change TCAM CONTROL on non-TCAM terminal.
- 36
- Invalid value supplied for TCAM CONTROL.
- 37
- Preset signon failed, terminal remains OUTSERVICE.
- 38
- OBFORMATST has an invalid CVDA value.
- 39
- RELREQST has an invalid CVDA value.
- 40
- DISCREQST has an invalid CVDA value.
- 41
- ALTPRTCOPYST has an invalid CVDA value.
- 42
- PRTCOPYST has an invalid CVDA value.
- 43
- UCTRANST has an invalid CVDA value.
- 44
- Options would result in the invalid combination of the alternate printer copy status being set without an alternate printer defined.
- 45
- Options would result in the invalid combination of the alternate printer being defined without a primary printer defined.
- 46
- OBFORMATST is specified for a console or 3790.
- 48
- Options would result in the invalid combination of the printer copy status being set without a primary printer defined.
- 50
- z/OS Communications Server not available for z/OS Communications Server terminal.
- 51
- PRINTER and ALTPRINTER option specified for a terminal that is not z/OS Communications Server 3270 or 3270 compatibility mode.
- 52
- PRTCOPYST or ALTPRTCOPST option specified for a terminal that is not z/OS Communications Server 3270 or 3270 compatibility mode.
- 54
- Option other than PURGETYPE specified for IRC session.
- 57
- Other SET parameters were included with the CANCEL option.
- 61
- No previous attempt has been made to forcepurge the task whose facility is a terminal.
- NORMAL
- RESP2 values:
- 53
- Purge deferred.
- 58
- AIDs are successfully canceled.
- 59
- No AIDs are canceled.
- 60
- MAPNAME or MAPSETNAME specified, but the terminal is not of a type supported by BMS.
- NOTAUTH
- RESP2 values:
- 100
- The user associated with the issuing task is not authorized to use this command.
- TERMIDERR
- RESP2 values:
- 23
- The named terminal cannot be found.