The communication area
After DFHZNEP receives control from DFHZNAC, it obtains the address of the communication area by means of an ADDRESS COMMAREA API command.
General structure of the communication area
- 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.
- z/OS® Communications Server 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. The fields in TWAXRNOT can be reset by the NEP
Detailed listing of the 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
**************************************************************************
** z/OS Communications Sever information - Any sense and RPL codes **
** These fields are READ ONLY **
**************************************************************************
TWAVTAM DS 0XL12 z/OS Communications Sever information
TWARPLCD DS H z/OS Communications Sever 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 z/OS Communications Sever sense codes
TWATIOA EQU X'08' Print portion of I/O area
* EQU X'04' Reserved
TWAVTRTC EQU X'02' z/OS Communications Sever return code available
TWANEPR DS XL1 NEP return code byte
TWANPFW EQU X'80' Retry write with FORCE=YES
TWAREASN DS XL1 z/OS Communications Sever reason code
TWASTAT DS XL1 z/OS Communications Sever status code
TWATRSN DS XL1 CICS terminal control
* terminal error code
TWAXRSN DS 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 z/OS Communications Sever 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.
TWAOPTL - The user option bytes
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 intended 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 z/OS Communications Server 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). Note:
- 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.
- 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.
Note:- If a definite response SEND has been performed, CICS has to issue a RECEIVE 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 kept on to ensure that the RECEIVE for the response is abandoned.
- 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.
- The abend code returned as a result of setting TWAOCT is unpredictable.
- TWAOGMM forces TWAOAT only if set on by the node error program.
- TWAOPBP forces TWAOAT to be set on.
- 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. Do not set this flag when processing error codeX'49' (TCZCLSIN)
- 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. Do not set this flag when processing error codeX'49' (TCZCLSIN).
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 remaining. (A session can also be put out of service because of either an unknown modename being passed to z/OS Communications Server during an attempt to bind an APPC session, or an invalid logmode name for a z/OS Communications Server 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.
TWAADINF - Additional information for the NEP
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 help you retrieve information from fields TWANLD and TWANLDL. 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.
TWAPIP - Application routing failure
You can use the EXEC CICS ISSUE PASS command to pass control from CICS to another named z/OS Communications Server application. By using the ISSUE PASS command you can invoke the z/OS Communications Server macro CLSDST with OPTCD=PASS to notify CICS of the outcome of your CLSDST requests.
For programming information about the EXEC CICS ISSUE PASS command, see ISSUE PASS. The ISSUE PASS command in turn invokes the z/OS Communications Server 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.
TWASYSPM - Additional system parameters
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.