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.
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.
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:
If you need to start a remote transaction, start a local transaction which starts a remote one in turn.
You should also note that you cannot use the NEP to suppress DFHZNAC messages.
On entry, your NEP should issue the commands:
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:
If you write your program in C, you include the communication area definitions by coding:
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:
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.
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.
Figure 27 shows how your NEP error processors could test for the presence of 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'
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.
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.
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]
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.
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
DFHZNEPI TYPE=FINAL
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.
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.
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.
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.