‘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.

SHIPPABLE attribute
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 the CICS Intercommunication Guide.
Automatic transaction initiation (ATI)
ATI occurs when an internally generated request leads to the initiation of a transaction. For example, when: 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 the CICS Intercommunication Guide.

‘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’.

The exits

To deal with the ‘terminal not known’ condition, CICS provides global user exits in the interval control and terminal allocation programs:

XICTENF
In the interval control program
XALTENF
In the terminal allocation program.

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.

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.

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.

Exit XALTENF

When invoked
By the terminal allocation program when the terminal that an ATI request from transient data or interval control requires is unknown in this system. The exit program is expected to give a return code indicating whether the terminal exists on another connected CICS system and, if so, on which one.
Exit-specific parameters
UEPALEVT
Address of 2 bytes containing the type of request. The equated values of the types are:
UEPALESD
START command with data
UEPALES
START command without data
UEPALETD
Transient data trigger level reached.
UEPALTR
Address of 1 byte containing an indication of whether the task issuing the START command was started by transaction routing. The equated values are:
UEPALTY
A START command was being processed and the task issuing the command was transaction routed to.
UEPALTN
A START command was not being processed or a START command was being processed but the task issuing the command was not transaction routed to.
UEPALFS
Address of 1 byte containing an indication of whether the START command was function shipped. The equated values are:
UEPALFY
A START command was being processed and the START was function shipped.
UEPALFN
A START command was not being processed or a START was being processed but it was not function shipped.
UEPALTRN
Address of 4 bytes containing the name of the transaction to be run.
UEPALRTR
Address of 4 bytes containing the name of the terminal on which the transaction should run. (If a transient data trigger level was reached and the transient data queue definition specified a system, then this would contain a system identifier.)
UEPALCTR
Address of 4 bytes containing, for START commands, the name of the current terminal if the command was transaction routed, or the name of the session if the command was function shipped.

For other START commands and for transient data trigger events, the field pointed to contains blanks.

UEPALNTI
Address of 8 bytes containing, for function-shipped START commands, the netname of the last system from which the request came.

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.

UEPALSYI
Address of 4 bytes containing, if UEPALNTI contains a netname, the corresponding sysid.

If UEPALNTI does not contain a netname, the field pointed to is blank.

UEPALNTO
Address of 8 bytes containing the contents of UEPALNTI.

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.

UEPALSYO
Address of 4 bytes containing the contents of UEPALSYI.

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.

UEPALNNI
Address of a 4-byte input field containing the netname of the terminal on which the transaction is to run, if this is known to CICS. If CICS does not know the netname, the addressed field contains blanks.
UEPALNNO
Address of a 4-byte input/output field containing, on invocation, the contents of UEPALNNI. Your exit program can use this field to supply the netname of the terminal on which the transaction is to run. It is important that your exit program supply a terminal netname if the TOR to which it directs the ATI request is a member of a VTAM generic resource.
Return codes
UERCTEUN
Terminal unknown, reject request.
UERCNETN
Terminal known, netname returned in UEPALNTO.
UERCSYSI
Terminal known, sysid returned in UEPALSYO.
XPI calls
You can use:

No other XPI calls should be used.

Exit XICTENF

When invoked
By the interval control program when the terminal that an EXEC CICS START command requires is unknown in this system. The exit program is expected to give a return code indicating whether the terminal exists on another connected CICS system and, if so, on which one.
Exit-specific parameters
UEPICEVT
Address of 2 bytes containing the type of request. The equated values of the types are:
UEPICESD
START command with data
UEPICES
START command without data.
UEPICTR
Address of 1 byte containing an indication of whether the task issuing the START command was started by transaction routing. The equated values are:
UEPICTY
A START command was being processed and the task issuing the command was transaction routed to.
UEPICTN
A START command was not being processed or a START command was being processed but the task issuing the command was not transaction routed to.
UEPICFS
Address of 1 byte containing an indication of whether the START command was function shipped. The equated values are:
UEPICFY
A START command was being processed and the START was function shipped.
UEPICFN
A START command was not being processed or a START was being processed but it was not function shipped.
UEPICTRN
Address of 4 bytes containing the name of the transaction to be run.
UEPICRTR
Address of 4 bytes containing the name of the terminal on which the transaction should run.
UEPICCTR
Address of 4 bytes containing, for START commands, the name of the current terminal if the command was transaction routed, or the name of the session if the command was function shipped.

For other START commands, the field pointed to contains blanks.

UEPICNTI
Address of 8 bytes containing, for function-shipped START commands, the netname of the last system from which the request came.

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.

UEPICSYI
Address of 4 bytes containing, if UEPICNTI contains a netname, the corresponding SYSID.

If UEPICNTI does not contain a netname, the field pointed to is blank.

UEPICNTO
Address of 8 bytes containing the contents of UEPICNTI.

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.

UEPICSYO
Address of 4 bytes containing the contents of UEPICSYI.

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.

UEPICNNI
Address of a 4-byte input field containing the netname of the terminal on which the transaction is to run, if this is known to CICS. If CICS does not know the netname, the addressed field contains blanks.
UEPICNNO
Address of a 4-byte input/output field containing, on invocation, the contents of UEPICNNI. Your exit program can use this field to supply the netname of the terminal on which the transaction is to run. It is important that your exit program supply a terminal netname if the TOR to which it directs the ATI request is a member of a VTAM generic resource.
Return codes
UERCTEUN
Terminal unknown, reject request.
UERCNETN
Terminal known, netname returned in UEPICNTO.
UERCSYSI
Terminal known, sysid returned in UEPICSYO.
UERCPURG
Task purged during XPI call.
XPI calls
The following must not be used:

The sample program for the XALTENF and XICTENF exits, DFHXTENF

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.

Figure 2. Sample program for XALTENF and XICTENF exits
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
Important

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.

Related concepts
Overview -- what is a global user exit?
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Writing global user exit programs
Making an XPI call
Related reference
List of global user exit points
The XPI functions
[[ Contents Previous Page | Next Page Index ]]