Writing your own node error program

You can write your own NEP in any of the CICS-supported languages. However, CICS-supplied NEP code is provided in assembler language only. The communication area parameter list is supplied in assembler-language and C versions. The names of the supplied source files, copy books, and macros, and the libraries in which they can be found, are listed in Table 26.

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

If you code in assembler language, you can use the sample NEP as a framework on which to construct your own node error program.

Restrictions on the use of EXEC CICS commands

There are certain restrictions on the commands that a NEP can issue. The use of any commands which require a principal facility causes unpredictable results, and should be avoided. In particular, you should not use commands which invoke the following functions:

You should also note that you cannot use the NEP to suppress DFHZNAC messages.

Entry and addressability

On entry, your NEP should issue the commands:

EXEC CICS ADDRESS COMMAREA
EXEC CICS ADDRESS EIB

These commands provide addressability to the communication area passed by DFHZNAC, and to the EXEC interface block, respectively.

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

DFHNEPCA TYPE=DSECT

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

#include <dfhnepca>

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:

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 VTAM® 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:

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 25) and, based on its contents, performs one of the following actions:

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

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 reinvoked 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. Refer to Restrictions on the use of EXEC CICS commands.

Coding for specific VTAM sense codes

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

Figure 27. Sample code, showing how your node error program could test for specific VTAM 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'

Writing multiple NEPs

You can write several node error programs, as described in Multiple NEPs. 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.

DFHZNEPI macros

The following macros are required to generate the node error program interface module (DFHZNEPI):

The DFHZNEPI interface module must be generated when you require the node abnormal condition program to pass control to the appropriate user-written node error program for resolution of the error.

DFHZNEPI TYPE=INITIAL--specifying the default routine

The DFHZNEPI TYPE=INITIAL macro specifies the name of the default transaction-class routine to be used for the DFNZNEPI module.

DFHZNEPI  TYPE=INITIAL
          [,DEFAULT=name]
DEFAULT=name
specifies the name of the default transaction-class routine to be used. A link is made to this default routine if you specify for the transaction (using the CEDA DEFINE PROFILE, CEDA DEFINE SESSIONS, or CEDA DEFINE TYPETERM command) a NEPCLASS value of 0 (the default) or higher than 255, or if you do not specify a transaction-class routine using the DFHZNEPI TYPE=ENTRY macro for the class specified on the NEPCLASS operand.

If either of the preceding conditions is true, but you do not code the DEFAULT operand, then no routine is invoked.

The DFHZNEPI TYPE=INITIAL macro must always be specified, and must be placed before any other forms of the DFHZNEPI macro. Only one TYPE=INITIAL macro can be specified.

DFHZNEPI TYPE=ENTRY--specifying a transaction-class routine

You use the DFHZNEPI TYPE=ENTRY macro to associate a transaction class (NEPCLASS) with a transaction-class error handling routine. The format of this macro is:

DFHZNEPI  TYPE=ENTRY
          ,NEPCLAS=integer
          ,NEPNAME=name
NEPCLAS=integer
specifies the transaction-class, and must be in the range 1 through 255. No value should be specified that has been specified in a previous DFHZNEPI TYPE=ENTRY instruction.
NEPNAME=name
specifies a name for the transaction-class routine to be associated with the specified transaction-class. An error condition results if the name is specified either as DFHZNEP, or is longer than 8 characters.
Note:
You can use the sample node error program (with a name other than DFHZNEP) as a transaction-class routine for the interface module, DFHZNEPI.

DFHZNEPI TYPE=FINAL--terminating DFHZNEPI entries

DFHZNEPI  TYPE=FINAL
TYPE=FINAL
completes the definition of module DFHZNEPI and must be specified last. The assembly should be terminated by an END statement with no entry name specified, or by the statement: END DFHZNENA.

Handling shutdown hung terminals in the node error program

Error Code:       X'6F'
Symbolic Name:   TCZSDAS
Message Number:  DFHZC2351

For error code X'6F', DFHZNAC passes the setting of TCSACTN and the DFHZC2351 reason code to DFHZNEP, and DFHZNEP can modify the force-close action for the current terminal.

How DFHZNAC passes the setting of TCSACTN to DFHZNEP

For error code X'6F', DFHZNAC passes the setting of the TCSACTN system initialization parameter to DFHZNEP by setting TWAOSCN. TWAOSCN off (B'0') indicates TCSACTN=NONE, and TWAOSCN on (B'1') indicates TCSACTN=UNBIND.

How DFHZNAC passes the DFHZC2351 reason code to DFHZNEP

For error code X'6F', the DFHZC2351 reason code is passed to DFHZNEP in the NEP communications area (NEPCA) field TWATRSN. TWATRSN is a 1-byte code field. Note that, currently, TWATRSN overlays TWAREASN (also a 1-byte field). The codes, and their meaning, are:

  01  Request in progress    06  Waiting for RTR
  02  Task still active      07  BID in progress
  03  Waiting for SHUTC      08  Other TC work pending
  04  Waiting for BIS        99  (X'63')  Undetermined
  05  Waiting for UNBIND
 

See Terminal Control message DFHZC2351 for further details.

How DFHZNEP can modify the force-close action for the current terminal

For error code X'6F', DFHZNEP can modify the force-close action, for the current terminal, by setting TWAOSCN. If DFHZNEP sets TWAOSCN off (B'0'), DFHZNAC will not attempt to force-close the terminal (TCSACTN=NONE), however, if DFHZNEP sets TWAOSCN on (B'1'), DFHZNAC will attempt to force-close the terminal (TCSACTN=UNBIND). Internally, DFHZNAC achieves this by converting the TWAOSCN normal close to a TWAOCN forced close. DFHZNEP cannot modify either of the system initialization parameters TCSWAIT or TCSACTN.

Related concepts
Background to CICS-VTAM error handling
When an abnormal condition occurs
Related tasks
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
[[ Contents Previous Page | Next Page Index ]]