‘Terminal not known’ condition exits XALTENF and XICTENF

The ‘terminal not known’ condition can occur when intercommunicating CICS® regions use both SHIPPABLE terminal definitions and automatic transaction initiation (ATI). The condition is especially likely to arise if autoinstall is used.

Terminals defined with the SHIPPABLE attribute in a terminal-owning region (TOR) do not need a definition in a connected application-owning region (AOR). If necessary to support transaction routing, CICS ships a copy of the definition from the TOR to the AOR. For further information, refer to Shipping terminal and connection definitions.

Automatic transaction initiation (ATI)

ATI occurs when an internally generated request leads to the initiation of a transaction (for example, when an application issues an EXEC CICS START command, or when the transient data trigger level is reached.

Two CICS modules handle ATI requests:

The interval control program processes a START command, checks that the terminal is known in the local system, and (when any START time interval elapses) calls the terminal allocation program.
The terminal allocation program is called by the interval control program or by the transient data triggering mechanism, and checks that the terminal is known in the local system. If the requested terminal is remote, the terminal allocation program ships an ATI request to the remote system, which initiates transaction routing back to the local system.

For guidance information about ATI, refer to Traditional routing of transactions started by ATI.

‘Terminal not known’ condition

The ‘terminal not known’ condition arises when an ATI request is made for a terminal not known in the region. An ATI request can occur in the AOR for a SHIPPABLE terminal before any transaction routing has taken place for the terminal, and so before the definition of the terminal can have been shipped from the TOR to the AOR.

If the ‘terminal not known’ condition occurs, both the interval control program and the terminal allocation program reject the transaction-initiation request as ‘TERMIDERR’.

Exits XALTENF and XICTENF

To deal with the ‘terminal not known’ condition, CICS provides global user exit XICTENF in the interval control program and exit XALTENF in the terminal allocation program.

CICS drives exit XICTENF when the ‘terminal not known’ condition occurs after the interval control program has been invoked by an EXEC CICS START command. CICS drives the XALTENF exit when the ‘terminal not known’ condition occurs after the terminal allocation program has been invoked by the transient data trigger level or the interval control program. Note that an EXEC CICS START command could result in both exits being invoked.

The exit program must indicate whether the terminal exists on another system and, if so, on which one. CICS passes data to the exit program to help establish this information. You can use the same exit program at both exit points. CICS supplies a sample exit program, DFHXTENF, that can be used at both exits and that can deal unchanged with some typical situations.

The exits are designed to deal with ‘terminal not known’ conditions that occur in CICS regions other than the TOR. For a TOR/AOR pair, enable the exit program in the AOR. The exits cannot deal with a ‘terminal not known’ condition in the TOR and the exit program should not normally be enabled there. However, if more than one TOR exists, you may need to enable the exit program in each TOR to deal with requests for terminals owned by other TORs. In this case, the exit program must recognize terminals that should be owned by this system and reject the requests (‘UERCTEUN’). Although the exit provides as much data as possible, the logic of your program depends entirely on your system design. A simple solution to the most complex case would be to make the name of each terminal reflect the netname or sysid of its owning region.

Data returned by exit

The exit program must set a return code in register 15 as follows:

UERCTEUN: Terminal does not exist
UERCNETN: Netname of TOR returned
UERCSYSI: Sysid of TOR returned.

UERCTEUN: Terminal does not exist
UERCNETN: Netname of TOR returned
UERCSYSI: Sysid of TOR returned.

For return codes UERCNETN and UERCSYSI, the exit program must place the netname or sysid of the terminal-owning region in fields UEPxxNTO or UEPxxSYO (where xx is AL or IC).

If the terminal-owning region is a member of a z/OS® Communications Server generic resource, the exit program should place the netname of the terminal in field UEPxxNNO. For information about using ATI with z/OS Communications Server generic resources, see Using ATI with generic resources.