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.
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.
The significance of each section of the communication area is described below:
A detailed listing of the communication area is given in Figure 25.
**********************************************************************
** 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.
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.
The flags are:
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:
The flags are:
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.
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.
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.
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.
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.
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.
These fields can be reset by the NEP. See Using the node error program with XRF or persistent sessions.