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.
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 the CICS Intercommunication Guide.
If the ‘terminal not known’ condition occurs, both the interval control program and the terminal allocation program reject the transaction-initiation request as ‘TERMIDERR’.
To deal with the ‘terminal not known’ condition, CICS provides global user exits in the interval control and terminal allocation programs:
CICS drives the XICTENF exit 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 (see Figure 2), 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.
The exit program must set a return code in register 15 as follows:
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 VTAM® generic resource, the exit program should place the netname of the terminal in field UEPxxNNO. For information about using ATI with VTAM generic resources, see the CICS Intercommunication Guide.
For other START commands and for transient data trigger events, the field pointed to contains blanks.
For START commands issued in this system by transaction routing to a task, the netname of the last system from which the task was routed.
For other START command situations and for transient data trigger level events, the field pointed to contains blanks.
If UEPALNTI does not contain a netname, the field pointed to is blank.
If it sets a return code of ‘UERCNETN’, your exit program must place in this field the netname of the system to which the ATI request should be sent.
If it sets a return code of ‘UERCSYSI’, your exit program must place in this field the sysid of the system to which the ATI request should be sent.
No other XPI calls should be used.
For other START commands, the field pointed to contains blanks.
For START commands issued in this system by transaction routing to a task, the netname of the last system from which the task was routed.
For other START command situations, the field pointed to contains blanks.
If UEPICNTI does not contain a netname, the field pointed to is blank.
If it sets a return code of ‘UERCNETN’, your exit program must place in this field the netname of the system to which the ATI request should be sent.
If it sets a return code of ‘UERCSYSI’, your exit program must place in this field the sysid of the system to which the ATI request should be sent.
One program can be used for both exits, or a separate program can be written for each. Figure 2 shows the executable code from the supplied sample program DFHXTENF, which can be used for both exits. DFHXTENF rejects transient data requests, because the action in this case is very much installation-dependent.
DFHXTENF CSECT
DFHVM XTENF
ENTRY DFHXTENA
DFHXTENA DS 0H
STM R14,R12,12(R13) save registers
BALR R11,0 set up base register
USING *,R11
*
USING DFHUEPAR,R1 DFHUEH parameter list
*
* Could check the terminal ID at this point. In this
* program we assume it is valid. We also choose to accept
* START requests and reject Transient Data trigger level
* events.
*
L R2,UEPICEVT access type of request
CLC 0(2,R2),START START command?
BE STARTCMD yes
*
CLC 0(2,R2),STARTDAT START command with data?
BNE NOTSTART no, must be Transient Data
*
STARTCMD DS 0H
*
* Accept the default netname if we are Function Shipping.
* Otherwise build a netname.
*
L R2,UEPICFS access FS information
CLI 0(R2),UEPICFY Function Shipping?
BNE BLDNETNM no, build a netname
*
LH R15,NETNAME accept the default netname
B EXIT
*BLDNETNM DS 0H
*
* Build a netname by taking the first character of the
* terminal ID and appending it to the characters 'CICS'.
*
L R2,UEPICNTO access the output netname field
L R3,UEPICRTR access ID of requested terminal
MVC 0(8,R2),=C'CICS '
MVC 4(1,R2),0(R3) first character of terminal ID
LH R15,NETNAME netname returned
B EXIT
*
NOTSTART DS 0H
LH R15,UNKNOWN reject Transient Data trigger *
level events
*
EXIT DS 0H
L R14,12(R13) restore registers except 15
LM R0,R12,20(R13) which contains the return code
BR R14
*
***********************************************************************
* Local constants
***********************************************************************
START DC AL2(UEPICES)
STARTDAT DC AL2(UEPICESD)
NETNAME DC AL2(UERCNETN)
UNKNOWN DC AL2(UERCTEUN)
*
DFHEND DFHXTENF
The example in Figure 2 is intended purely as a demonstration of some of the possibilities available, and would be impractical in a production environment.