Writing your own node error program

You can write your own node error program (NEP) in any of the CICS®-supported languages. If you code in assembler language, you can use the sample NEP as a framework on which to construct your own node error program.

As described in Multiple NEPs, you can write several node error programs. When an error occurs, the node abnormal condition program passes control to an interface module, DFHZNEPI, which determines the transaction class and passes control to the appropriate node error program.

If only one node error program is used, the interface module (DFHZNEPI) is not required. If the node error program is named DFHZNEP, the node abnormal condition program branches directly to that. If more than one node error program is used, the interface module DFHZNEPI is required. In this case, the node error programs must be given names other than DFHZNEP. There must be an installed program definition for every node error program generated.

CICS-supplied sample NEP

CICS provides NEP code is provided in assembler language, and the communication area parameter list is supplied in assembler language and C® versions. The names of the supplied source files, copybooks, and macros, and the libraries in which they can be found, are listed in Table 1.

Where you see nn, the nn indicates the CICS version and library is the library name. For example, CICSTS63.CICS.SDFHLOAD.

Table 1. Supplied source files, copy books, and macros
Name	Type	Description	Library
DFHZNEP0	Program	Default node error program (assembler language)	CICSTS`nn`.CICS..SDFHSAMP
DFHZNEPX	Source	Default NEP (embedded by DFHZNEP0 via COPY statement)	CICSTS`nn`.CICS..SDFHSAMP
DFHSNEP	Macro	Sample NEP program generator (assembler language)	CICSTS`nn`.CICS..SDFHMAC
DFHZNEPI	Macro	NEP interface generator (for multiple NEPs)	CICSTS`nn`.CICS..SDFHMAC
DFHNEPCA	Macro	assembler language communication area	CICSTS`nn`.CICS..SDFHMAC
DFHNEPCA	Copybook	C-language communication area	CICSTS`nn`.CICS..SDFHC370

Restrictions on the use of EXEC CICS commands

The commands that a node error program (NEP) can issue are restricted. In particular, do not use commands that require a principal facility, because their results are unpredictable.

Do not use commands that start the following functions:

Terminal control. For example, issuing an EXEC CICS DELAY command can cause the CSNE task to suspend and never resume, which can cause shutdown of the region to hang. CEMT-type commands, however, such as EXEC CICS INQUIRE TERMINAL, are permitted.
BMS (except routing).
ISC communication (including function shipping), including START requests for remote transactions, although such requests are not recommended because CSNE (Node Abnormal Condition task) might become suspended while issuing an ALLOCATE command to the remote system.
To start a remote transaction, start a local transaction which in turn starts a remote transaction.
Updates to recoverable resources. If the resources are locked by another task, the CSNE unit of work can be suspended or shunted.

You cannot use the NEP to suppress DFHZNAC messages.

Coding the entry to provide addressability

On entry, your NEP should issue the following commands to provide addressability to the communication area passed by DFHZNAC and to the EXEC interface block, respectively.

EXEC CICS ADDRESS COMMAREA
EXEC CICS ADDRESS EIB

Assembler

If you write your node error program in assembler language, you generate the communication area DSECT by coding:

DFHNEPCA TYPE=DSECT

C

If you write your program in C, you include the communication area definitions by coding:

#include <dfhnepca>

Coding for session failures

Following some categories of error associated with logical unit or path failures, the session between CICS and the logical unit may be lost. The default action taken by DFHZNAC may be to put the TCTTE out of service.

A method of automatically reacquiring the session is for your node error program to alter the default DFHZNAC actions and to keep the TCTTE in service. Your node error program can then issue an EXEC CICS START TERMID(name) command against that TCTTE for a transaction written in a similar manner to the CICS “good morning” signon message (CSGM). When the transaction is initiated using automatic transaction initiation (ATI), CICS tries to reacquire the session. If the session fails again, DFHZNAC is re-invoked and the process is repeated.

The time specified on the EXEC CICS START command is determined by installation-dependent expected-mean-time-to values.

If used in this way, the initiated transaction can write an appropriate signon message when the session has been acquired. Note, however, that if LOGONMSG=YES is specified on the CEDA DEFINE TYPETERM command, the CICS “good morning” message is also initiated when the session is opened. See Restrictions on the use of EXEC CICS commands.

Coding for specific SNA sense codes

Figure 1 shows how your NEP error processors could test for the presence of specific SNA sense codes.

Figure 1. Sample code, showing how your node error program could test for specific SNA sense codes

TEST1   EQU   *
        CLC   TWASENSR(2),SNS1              SENSE CODE EQUAL TO NNNN
        BNE   TEST2                         NO, THEN NEXT TEST
        NI    TWAOPT1,TWAOAF                PRINT ACTION MESSAGES ONLY
        OI    TWAOPT2,TWAOAS+TWAOAR+TWAOAT  ABANDON SEND,RECEIVE AND TASK
        NI    TWAOPT2,255-TWAOASM           SET SIMLOGON OFF
        OI    TWAOPT3,TWAOINT               SET INTLOG NOW ALLOWED
        NI    TWAOPT3,255-TWAONINT          OR RESET NOINTLOG
        B     END
        .
        .
        .
SNS1    DC    X'NNNN'

Coding for the 3270 unavailable printer condition

The unavailable printer condition arises when a print request is made using the 3270 print request facility, and there are no printers on the control unit, or when the printers are in one of the following conditions:

Out of service
Not in TRANSCEIVE or RECEIVE status for automatic transaction initiation
With a task currently attached
Busy on a previous operation
Requiring intervention.

The procedure is applicable to 3270 logical units or to the 3270 compatibility mode logical unit when using the PRINTER and ALTPRINTER operands of the CEDA DEFINE TERMINAL command.

The terminal control program recognizes this condition, and issues a READ BUFFER request to collect the data into a terminal I/O area. The TIOA is of the same format as it is when an application program has issued a terminal control read buffer request.

The terminal control program z/OS® Communications Server section (DFHZCP) then queues the TCTTE to the node abnormal condition program with error code X'42' (TCZCUNPRT). The node abnormal condition program (DFHZNAC) writes to the CSNE transient data queue:

DFHZC2497 UNAVAILABLE PRINTER (device types 3270P and LUTYPE3)
DFHZC3493 INVALID DEVICE TYPE FOR A PRINT REQUEST (all other printer device types).

Before linking to the node error program, DFHZNAC inserts the primary and secondary printer netnames and terminal IDs into the communication area, indicating also whether either printer is eligible for a print request. DFHZNAC links to the node error program with no default actions set.

On return from the node error program, DFHZNAC checks the additional system parameter TWAUPRRC in the communication area (see Figure 2) and, based on its contents, performs one of the following actions:

If your NEP sets TWAUPRRC to X'FF' (-1), DFHZNAC assumes that the node error program has disposed of the data to be printed and therefore takes no further action.
If your NEP sets TWAUPRRC to zero, DFHZNAC assumes that no printer is available and takes no further action.
If your NEP sets TWAUPRRC to neither zero nor -1, DFHZNAC assumes that one of either field TWAPNETN or field TWAPNTID is set. (If both are set, TWAPNTID(termid) takes precedence.) An interval control PUT is performed to the provided terminal. The transaction to be initiated is CSPP (print program), and the time interval is zero.
- If an error occurs on the interval control PUT, DFHZNAC writes the ‘DFHZC2496 IC FAILURE' message to the destination CSNE. DFHZNAC then links to the node error program again with the TWAUPRRC field set to -2. This is done to give the node error program a last chance to dispose of the data. On the second return from the node error program to DFHZNAC, the latter reexamines TWAUPRRC. If TWAUPRRC is -1, then the node error program has disposed of the data.
- If no error occurs on the interval control PUT, DFHZNAC checks for the following printer conditions:
  - ‘Out of service'
  - ‘Intervention required'
  - Any condition other than RECEIVE or TRANSCEIVE status
  If one of these conditions is true, DFHZNAC issues the ‘DFH2495 PRINTER OUTSERV/IR/INELIGIBLE-REQ QUEUED' message to the destination CSNE.

Finally, DFHZNAC terminates any print requests on the originating terminal and performs normal action flag processing on that terminal.