Coding the sample node error program

The sample node error program (NEP) is coded by using the macro DFHSNEP.

The basic form is as follows: 
DFHSNEP TYPE=INITIAL
 
Specific error handling code. For example:
 
DFHSNEP TYPE=DEF3270
 
DFHSNEP TYPE=FINAL
END     DFHNEPNA

By default, this generates a module called DFHZNEP, which works with a node error table called DFHNET. If you want to use another table, you could code NETNAME=MYTABLE after TYPE=INITIAL. Details of the DFHSNEP macro are given in DFHSNEP macros for generating the sample node error program.

To understand the sample code, generate a standard NEP, as with TYPE=DEF3270, shown in DFHSNEP TYPE=DEF3270 (Including error processors for 3270 LUs), and look at the resulting assembler-language listing. Here is a description of the code.

The INITIAL and FINAL macros generate the basic skeleton of the NEP. This comprises some initialization code and some common routines. All the code is built around the assumption that you have a node error table as previously described.

The initial code first tests the internal error code passed from DFHZNAC to see if it belongs to a group that the NEP needs to handle. (The groups are identified by the code you supply between the DFHSNEP INITIAL and FINAL macros. This is described in DFHSNEP macros for generating the sample node error program.) If the particular error code is not of interest to the NEP, control is returned at once to DFHZNAC, to take default actions.

Otherwise, the relevant node error table is located by a CICS LOAD request. (As previously explained, this table should be resident in virtual storage.) The NEP code will then locate the correct ESB within a selected NEB. The latter may be permanently dedicated to the LU in error (a named NEB), or may be one taken from the general pool.

The initial code then invokes the appropriate user logic for that error group. The initial code also sets up pointers to the communication area, the NEB, and the ESB. For details, see DFHSNEP macros for generating the sample node error program.

The common routines in the NEP provide common services for your own logic. They count and time stamp errors in the ESB, and test whether error thresholds have been exceeded. They are not documented outside the sample listings. You can generate a NEP without them if you prefer.

Your own code is inserted between the DFHSNEP TYPE=INITIAL and TYPE=FINAL macros.

Note: If the user code you insert between the DFHSNEP macros contains EXEC CICS commands, you must translate the commands, and enter the translated code between the DFHSNEP macros.
Each section of user logic, intended to handle a particular group of error types, is headed by a macro of the type: 
DFHSNEP TYPE=ERRPROC,CODE=(ab,cd,...),GROUP=n
where X'ab', X'cd',… are the DFHZNAC internal error codes you want to process, and n is the number of the error group, and therefore also of the corresponding ESB, within a NEB, in the node error table. Successive DFHSNEP TYPE=ERRPROC macros should use groups 1, 2, 3, and so on.
The DFHSNEP TYPE=ERRPROC macros serve several purposes. They:
  • Inform the NEP generation how many error groups there are
  • Show which error types are to be included in each group
  • Introduce the code for each group.

Note that any one DFHZNAC error code should only figure in one error group, and that any code not mentioned is ignored by the NEP. You follow each DFHSNEP TYPE=ERRPROC macro with your own logic. This should begin with standard code to save registers, or set up addressability, which is best copied from sample NEP listings.

CICS provides some standard error processors to handle specific errors on two different types of LU. These are for non-SNA 3270s (BSC 3270s attached to CICS-z/OS® Communications Server), and for interactive SNA logical units like a 3767. More information is given in What happens when an abnormal condition occurs.

The code for non-SNA 3270s can be generated by coding 
DFHSNEP TYPE=DEF3270
where you would otherwise code a DFHSNEP TYPE=ERRPROC macro plus logic of your own. In effect, TYPE=DEF3270 defines two error groups, and associates each with an error processor. The first group comprises the four DFHZNAC error codes X'D9', X'DC', X'DD', and X'F2'. The second group contains only error code X'42', corresponding to the ‘unavailable printer' condition, a specific exception condition signaled when CICS cannot allocate a printer in response to a 3270 print request.

The 3270 sample code is not intended to cover all error conditions. Note that the code is not suitable for SNA 3270s (LU session type 2). Error conditions arising from these result in different DFHZNAC error codes and may require different handling.

You may find that the CICS-supplied code is not sufficient for other, application-related, reasons. Perhaps you want to try to reacquire lost sessions after a time interval. The code supplied for the 3767 covers only one error group with one DFHZNAC error code, X'DC', which may occur under contention protocol.

You can use these CICS-supplied error processors to generate a valid DFHZNEP listing, for tutorial purposes, without having to write any user code.

You should be aware of the following limitations of this NEP design:
  • Any error types you have not allowed for are ignored by the NEP, and not accumulated into error buckets.
  • You may want to handle a particular situation whenever it arises, even though DFHZNAC may assign it different error codes in different situations. For example, on an SNA 3270, switching in and out of TEST state generates status X'082B' (presentation-space integrity lost). This might result in one of several DFHZNAC error codes.

In the sample NEP structure, you would need either to test for this last case in separate error processors, or group all the DFHZNAC error codes together. If you wrote your own NEP code from scratch, you would , on entry to your NEP, test the communication area field containing the status.