When an abnormal condition occurs

The following CICS® components are involved when an abnormal condition is detected from a logical unit:

For logical units, all information concerning the processing state of the terminal is contained in the TCTTE and the request parameter list (RPL). Consequently, when a terminal error must be handled for a logical unit, the TCTTE itself is placed onto the system error queue.

DFHZNAC assumes that system sense codes are available upon receipt of an exception response from the logical unit. Thus, analysis is performed to determine the reason for the response. Decisions, such as which action flags to set and which requests are needed, are made based upon the system sense codes received. If sense information is not available, default action flags are set, and DFHZEMW is scheduled to send a negative response, if a response is outstanding, with an error message to the terminal.

The action flags set by DFHZNAC on receipt of specific inbound system sense codes are listed in Appendix B. Default actions of the node abnormal condition program.

Before executing the specified routines, DFHZNAC links to DFHZNEP. You can use DFHZNEP to perform additional error processing beyond that performed by DFHZNAC; or to alter the default actions previously set by DFHZNAC. You need to code a node error program only if you want to do either of these things.

The action flags, set by DFHZNAC to assist the node error program, are in field TWAOPTL of the communication area.

If you want to modify DFHZNAC’s actions following an abnormal situation, DFHZNEP can interrogate field TWAOPTL and modify the bit settings. If you agree with DFHZNAC’s proposed actions, field TWAOPTL is left unaltered.

In most cases, DFHZNEP can modify DFHZNAC’s proposed actions. The only time that DFHZNAC overrides DFHZNEP’s modification of field TWAOPTL is when a logical unit is to be disconnected from CICS; that is, when DFHZNAC determines that the abnormal situation requires that CICS issue the ACF/VTAM CLSDST macro for a logical unit. In such a case, DFHZNAC disconnects the terminal and abnormally terminates the task, even if DFHZNEP tries to block such actions.

Resetting of the task termination flag by the node error program is also ignored if a negative response has been sent to a logical unit, or if DFHZEMW is to write an error message to the logical unit.

When the node error program has performed its functions, it returns control to DFHZNAC by an EXEC CICS RETURN command.

When control is returned from DFHZNEP, DFHZNAC performs the actions specified in field TWAOPTL (except when disconnecting logical units, as noted above), issuing messages and setting error codes, as necessary.

The communication area

After DFHZNEP receives control from DFHZNAC, it obtains the address of the communication area by means of an EXEC CICS ADDRESS COMMAREA command. Figure 24 illustrates the general structure of the communication area.

Figure 24. General structure of the communication area
 The picture shows the communication area as consisting of all the fields described in the following list. (It begins with a Header and ends with the XRF parameters.)

The significance of each section of the communication area is described below:

Header
A 4-byte header common to all user-replaceable programs.
Error_being_processed
Identifiers of the error code and the terminal associated with the error.
User option bytes
Flags that indicate the default actions set by DFHZNAC, and that may be reset within DFHZNEP.
VTAM information
Sense and RPL codes.
Additional info. for NEP
Other useful information for the NEP.
Additional system parameters
Locations of indirect parameters, such as the TCTTE, and other system information.
XRF parameters
Recovery notification data.

A detailed listing of the communication area is given in Figure 25.

Figure 25. The DFHZNAC/DFHZNEP communication area
 
**********************************************************************
**                       Header                                     **
**               These fields are READ ONLY                         **
**********************************************************************
NEPCAHDR DS    0XL4                Standard Header
NEPCAFNC DS    XL1                 Function Code      Always '1'
NEPCACMP DS    XL2                 Component Code     Always 'ZC'
         DS    XL1                 Reserved
**********************************************************************
**                   Error_being_processed                          **
**    Identity of terminal and the error code associated with it    **
**               These fields are READ ONLY                         **
**********************************************************************
TWAEC    DS    XL1                 Error Code
         DS    CL3                 Reserved
TWANID   DS    CL4                 Terminal identity
TWANETN  DS    CL8                 Netname
**********************************************************************
**                   User option bytes                              **
**               Initially set to the default actions.              **
**               DFHZNEP can change the defaults.                   **
**********************************************************************
TWAOPTL  DS    0XL3                User option bytes
TWAOPT1  DS    XL1                 User option byte 1
TWAOPT2  DS    XL1                 User option byte 2
TWAOPT3  DS    XL1                 User option byte 3
         DS    XL1                 Reserved
 
**********************************************************************
**      VTAM information  -   Any VTAM sense and RPL codes          **
**               These fields are READ ONLY                         **
**********************************************************************
TWAVTAM  DS    0XL12               VTAM information
TWARPLCD DS    H                   VTAM RPL feedback codes
         DS    H                   Reserved
TWASENSS DS    0F                  Sense codes to be sent
TWASS1   DS    XL1                 System sense byte No 1
TWASS2   DS    XL1                 System sense byte No 2
TWAUS1   DS    XL1                 User sense byte No 1
TWAUS2   DS    XL1                 User sense byte No 2
*
TWASENSR DS    0F                  Sense codes received
TWASR1   DS    X                   System sense byte No 1
TWASR2   DS    X                   System sense byte No 2
TWAUR1   DS    X                   User sense byte No 1
TWAUR2   DS    X                   User sense byte No 2
*
**********************************************************************
**             Additional information for the NEP                   **
**Except for TWANPFW, TWANLD, and TWANLDL these fields are READ ONLY**
**********************************************************************
TWAADINF DS    0XL22
         DS    F                   Reserved
TWACTLB  DS    X                   General use control byte
*        EQU   X'80'               Reserved
*        EQU   X'40'               Reserved
TWACSC   EQU   X'20'               Clear sense code indicator
TWAPSC   EQU   X'10'               Print VTAM sense codes
TWATIOA  EQU   X'08'               Print portion of I/O area
*        EQU   X'04'               Reserved
TWAVTRTC EQU   X'02'               VTAM return code available
TWANEPR  DS    XL1                 NEP return code byte
TWANPFW  EQU   X'80'               Retry write with FORCE=YES
TWAREASN DS    XL1                 VTAM reason code
TWASTAT  DS    XL1                 VTAM status code
TWATRSN  DS    XL1                 CICS terminal control
*                                  terminal error code
TWAXRSN  DS    H                   Exception response seq number recd
TWAR     EQU   *
TWAPFLG  DS    XL1                 CLSDST pass flag
TWAPIP   EQU   X'80'               CLSDST pass in progress
TWANEPC  DS    XL1                 NEP class flag
TWAEISAB DS    XL1                 Stand-alone begin bracket indicator
TWAESAB  EQU   X'04'               Stand-alone begin bracket
         DS    XL3                 Reserved
TWANLD   DS    A                   Address of data to be logged
TWANLDL  DS    H                   Length of data to be logged
**********************************************************************
**               Additional system parameters                       **
**Except for TWAPNETN, TWAPNTID, TWAUPRRC these fields are READ ONLY**
**********************************************************************
TWASYSPM DS    0XL68
TWATCTA  DS    AL4                 Address of TCTTE being processed
TWARPL   DS    AL4                 Address of VTAM RPL
TWATIOAA DS    AL4                 Address of data portion of TIOA
TWATIOAL DS    H                   Length of data portion of TIOA
TWACOMML DS    H                   Length of commarea data for TCTTE
TWACOMMA DS    CL4                 Address of commarea data for TCTTE
TWATECIA DS    AL4                 Address of TCTTE user area
TWATECIL DS    H                   Length of TCTTE user area
TWAPPNTN DS    CL8                 Primary 3270 printer netname
TWAPPTID DS    CL4                 Primary 3270 printer termid
TWAPPELG DS    X                   Primary printer eligible indicator
TWAPPELY EQU   X'01'               Primary printer is eligible flag
TWASPNTN DS    CL8                 Secondary 3270 printer netname
TWASPTID DS    CL4                 Secondary 3270 printer termid
TWASPELG DS    X                   Secondary printer eligible indicator
TWASPELY EQU   X'01'               Secondary printer is eligible flag
TWAPNETN DS    CL8                 Selected 3270 printer netname
TWAPNTID DS    CL4                 Selected 3270 printer termid
TWAUPRRC DS    B                   Unavailable Printer return code
TWAUPRNP EQU   X'00'               No printer selected
TWAUPRPS EQU   X'01'               Printer selected
TWAUPRDD EQU   X'FF'               Data disposal complete
TWAUPRPE EQU   X'FE'               Error on Put request
TWAERRF1 DS    B                   Error flag byte 1
TWALXS   EQU   X'80'               Logon crossed simlogon
         DS    XL2                 Reserved
**********************************************************************
**                    XRF parameters                                **
**           XRF recovery notification data                         **
**           DFHZNEP can change these default actions               **
**********************************************************************
TWAXRNOT DS    X                   Recovery notification options
TWAXRNON EQU   X'80'               Recov notification = none
TWAXRMSG EQU   X'40'               Recov notification = message
TWAXRTRN EQU   X'20'               Recov notification = transact.
         DS    XL3                 Reserved
TWAXMSTN DS    CL8                 Recovery mapset name
TWAXMAPN DS    CL8                 Recovery map name
TWAXTRAN DS    CL4                 Recovery transaction ID
*

The next sections describe fields in the parameter list that can be reset within DFHZNEP. See also Coding for the 3270 ‘unavailable printer’ condition, which describes the use of the flags in the "unavailable printer return code" field, and Using the node error program with XRF or persistent sessions, which describes how the flags in the XRF part of the parameter list can be manipulated.

The user option bytes (TWAOPTL)

TWAOPTL contains the user option bytes TWAOPT1, TWAOPT2, and TWAOPT3, each of which contains action flags. On entry to DFHZNEP, these flags represent the default actions previously set by DFHZNAC. They can be reset by DFHZNEP.

TWAOPT1
User option byte 1. TWAOPT1 contains flags which are principally debugging aids. The first five flags cause DFHZNAC to write the desired information to the CSNE log if the appropriate bit is set. Setting the sixth flag (TWAODNTA) on causes CICS to take a system dump when there is no task attached to the terminal at the time of error detection, if the flag TWAOAT in TWAOPT2 is also set on. Setting the TWAONQN flag causes the network qualified name to be printed after any message that contains the action flag. Similarly setting the TWAOTNA flag causes the TNADDR information to be printed.

The flags are:

TWAOAF (X'80')
Print action flags.
TWAORPL (X'40')
Print VTAM RPL.
TWAOTCTE (X'20')
Print TCTTE.
TWAOTIOA (X'10')
Print TIOA.
TWAOBIND (X'08')
Print BIND area.
TWAODNTA (X'04')
System dump if no task attached.
TWAONQN (X'02')
Print NQNAME.
TWAOTNA (X'01')
Print TNADDR (TCP/IP client address, port and, optionally, host name).
Notes:
  1. Note that DFHZC2411 is not related to a specific node--that is, the TCTTE has not yet been created, and the message is printed against a dummy TCTTE. The node error program is not called in this case, therefore the default setting cannot be overridden. This means that the NQNAME and the TNADDR information is always printed for DFHZC2411 messges.
  2. When DFHZC2410 is issued against the dummy TCTTE, the NQNAME and TNADDR are not printed.
TWAOPT2
User option byte 2. TWAOPT2 contains flags which are task-related.

The NEP can abend the task by setting TWAOAT, or cancel it by setting TWAOCT. The difference is that abend task does not take effect until the task requests or completes a terminal control operation: cancel task takes effect as soon as system and data integrity can be maintained. Setting TWAOAT to abend the task is normally sufficient, except where the task performs lengthy processing (such as a database browse) between terminal requests. If both TWAOAT and TWAOCT are set, TWAOCT (cancel task) takes priority.

If the task is to be abnormally terminated, sends and receives are purged. If TWAOGMM is set, the next transid is cleared and any communication area associated with the terminal is released--except in the case of permanent transids (specified on the TERMINAL definition as TRANSACTION(name)), when the communication area is not released. If the TYPETERM of the terminal indicates that the "good morning" message is supported (LOGONMSG(YES)), if TWAONINT is off, and if the terminal is not in a BMS paging session, then the "good morning" message transaction is initiated (the transaction specified by the system initialization parameter GMTRAN).

The flags are:

TWAOAS (X'80')
Abandon any SEND for this terminal
TWAOAR (X'40')
Abandon any RECEIVE for this terminal
TWAOAT (X'20')
Abend any task attached to TCTTE
TWAOCT (X'10')
Cancel any task attached to TCTTE
TWAOGMM (X'08')
"good morning" message to be sent
TWAOPBP (X'04')
Purge any BMS pages for this session
TWAOASM (X'02')
SIMLOGON required.

Notes:
  1. If a definite response SEND has been performed, CICS has to issue a RECEIVE in order to obtain the response. If the response is negative, DFHZNAC is entered and sets flags TWAOAS (abandon the SEND) and TWAOAR (abandon the RECEIVE). TWAOAR must be left on to ensure that the RECEIVE for the response is abandoned.
  2. If the request is to be retried, and the break connection action flag is off (that is, if TWAOCN in TWAOPT3 is off), then one or more of TWAOAS, TWAOAR, and TWAONEGR must be off as well as TWAOAT.
  3. The abend code returned as a result of setting TWAOCT is unpredictable.
  4. TWAOGMM forces TWAOAT only if set on by the node error program.
  5. TWAOPBP forces TWAOAT to be set on.
  6. For non-pipeline terminals, TWAOAT acts as a cancel request (TWAOCT) if the task has not yet been dispatched for the first time.
TWAOPT3
User option byte 3. TWAOPT3 contains flags which are node-related.

The flags are:

TWAOINT (X'80')
Internally generated logons (INTLOGs) allowed
TWAONINT (X'40')
No internally-generated logons allowed 5
TWAONCN (X'10')
Normal CLSDST (no reset allowed)
TWAOSCN (X'08')
Normal CLSDST (reset allowed)
TWAONEGR (X'04')
Send negative response
TWAOOS (X'02')
Keep node out of service
TWAOCN (X'01')
CLSDST node. 5

TWAONINT forces TWAOCN.

TWAONEGR forces TWAOAR and TWAOAT.

TWAOOS forces TWAOCN.

TWAOCN forces TWAOAR, TWAOAS, and TWAOAT.

TWAOOS indicates that no further processing is to be done for this node. The node is logically out of service.

For an LU6.1 intersystem communication session, TWAOOS or TWAONINT causes the system entry to be put out of service if, as a result of the specified action, there are no allocatable sessions left. (A session can also be put out of service because of either an unknown modename being passed to VTAM during an attempt to bind an APPC session, or an invalid logmode name for a VTAM 3270-type terminal. However, the CICS default action resulting from this condition cannot be overridden in the NEP.)

If TWAOCN is set, the task is abnormally terminated and communication with the node is lost. Note that the NEP cannot reset this flag.

TWAOSCN provides the same function as TWAONCN, but the NEP can reset it if the session is not to be closed.

If DFHZNAC is scheduled because of the receipt of an exception response, the sense information in the TCTTE is available to DFHZNAC and DFHZNEP to determine any necessary actions.

If DFHZNAC is scheduled because of loss of the connection between CICS and a logical unit, DFHZNAC abnormally terminates any transaction in progress at the time of the failure. DFHZNEP and transaction-class error routine analysis and processing are permitted, but you should not attempt to retry the message.

However, if the application program handles the ‘TERMERR’ condition, the transaction is not abended. Control is returned to the program. In this circumstance, no further use can be made of the failed session.

Additional information for the NEP (TWAADINF)

Fields TWANPFW, TWANLD, and TWANLDL can be reset by the NEP. For information about the use of TWANPFW, see the supplied sample node error program, and Optional error processor for interactive logical units.

TWANLD and TWANLDL -- using the DFHZNAC logging facility

You can use the logging facility available in DFHZNAC to aid in retrieving information. You specify the address of the data that you want to examine in field TWANLD of the communication area, and the length of the data in field TWANLDL. The data is logged to the CSNE transient data queue for future inspection.

Note:
No data in excess of 220 bytes is logged.

You can also send user-written messages to the CSNE log using the transient data facility. To write your messages, you must code the EXEC CICS WRITEQ TD instruction directly into the node error program.

TWAPIP -- and application routing failure

The EXEC CICS ISSUE PASS command passes control from CICS to another named VTAM application. For programming information about the EXEC CICS ISSUE PASS command, see the CICS Application Programming Reference manual. The ISSUE PASS command in turn invokes the VTAM macro CLSDST with OPTCD=PASS, and, in addition, if NOTIFY has been specified on the CLSDSTP system initialization parameter, with PARMS=(THRDPTY=NOTIFY). CICS is then notified of the outcome of any CLSDST request.

This notification results in an informative message being issued, and causes DFHZNAC to invoke your NEP, whether the CLSDST request has failed or succeeded. The NEP can discover that a CLSDST OPTCD=PASS request is in progress by examining field TWAPFLG for the pass-in-progress indicator, TWAPIP. The success or failure of the CLSDST OPTCD=PASS request can be determined by examining the error code at TWAEC.

If the pass operation fails, DFHZNAC sets up a default set of recovery actions that can be modified by your NEP. A possible recovery, when, for example, the target application program is not active, would be to reestablish the session with the initial application using a SIMLOGON request and for CICS to send its "good morning" message to the terminal. The default action is to leave the session disconnected and to make it NOCREATE.

If CLSDSTP=NONOTIFY has been specified, and autoinstall is being used, CICS takes no action, even if the ISSUE PASS fails.

If persistent sessions support is active, autoinstall terminals are deleted after the AIRDELAY, so any expected NEP processing as a result of CLSDSTP=NOTIFY being coded does not take place.

The additional system parameters (TWASYSPM)

If a data element referenced in this section of the parameter list (for example, the TIOA) does not exist when the NEP is driven, its address and length fields are set to zero.

Fields TWAPNETN, TWAPNTID, and TWAUPRRC can be reset by the NEP. The use of these fields is discussed in Data storage key for task-related user exit programs.

XRF parameters (TWAXRNOT)

These fields can be reset by the NEP. See Using the node error program with XRF or persistent sessions.

Related concepts
Background to CICS-VTAM error handling
Related tasks
Writing your own node error program
Using the node error program with XRF or persistent sessions
Using the node error program with VTAM generic resources
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
Related reference
The sample node error program
User-replaceable programs and the storage protection facility

5.
Do not set this flag when processing error code X'49' (TCZCLSIN).

[[ Contents Previous Page | Next Page Index ]]