The sample node error program provides a general environment for the execution of error processing routines (error processors), each of which is specific to certain error codes generated by the node abnormal condition program. Sufficient optional error processors for normal operation of VTAM® 3270 or interactive logical unit networks are provided; these can be easily supplemented or replaced by user-supplied error processors.
There are three types of error that may occur in a VTAM network:
A sample node error program is supplied with CICS®, and can be used as the basis of each subsequent node error program that you write. This provides you with:
The CICS-supplied sample node error program is described in greater detail below.
Receipt of sense or status codes corresponds to error codes X'D9', X'DC', X'DD', and X'F2'. Weighted counts of these messages are maintained against numeric and time thresholds. If the numeric threshold is exceeded, default actions are taken. If the time threshold is reached, the count is reset. This is equivalent to the function in the sample TEP, except that sense or status arising out of the "from" device on a COPY command is now presented to the node error program as an error on the "to" device; this causes the threshold to be exceeded, resulting in the request being terminated, although the terminal remains in service. Some of the weights for errors that occur on the 3270 display device have been revised, but otherwise the weight and threshold values are the same as the defaults used in the sample TEP. Time threshold maintenance for the sample NEP is mandatory, and not optional as in the sample TEP.
For further information about time and threshold count limits, see the information about the sample terminal error program in Writing a terminal error program.
The 3270 message ‘unavailable printer’ corresponds to error code X'42' (interval control PUT request has failed). The algorithm used for printer selection differs in VTAM support. The retry algorithm in the sample node error program is similar to this new selection algorithm.
The sample node error program comprises the following components:
The components are described in the sections that follow.
On entry, the sample NEP uses DFHEIENT to establish base registers and addressability to the EXEC interface. It uses an EXEC CICS LOAD PROGRAM command to establish addressability to the node error table (NET) and, if included, the common subroutine vector table (CSVT). It uses an EXEC CICS ADDRESS COMMAREA command to obtain addressability to the communication area passed by DFHZNAC, and an EXEC CICS ADDRESS EIB command to obtain addressability to the EXEC interface block. If time support has been generated, the error is time-stamped for subsequent processing.
The routing mechanism invokes the appropriate error processor depending on the error code provided by the node abnormal condition program.
Groups of one or more error codes are defined in the DFHSNEP macro (see below). Each group is associated with an index (in the range X'01' through X'FF') and an error processor. A translate table is generated and the group index is placed at the appropriate offset for each error code. Error codes not defined in groups have a zero value in the table. An error processor vector table (EPVT) contains the addresses of the error group processors, positioned according to their indexes. The vector table extends up to the maximum index defined; undefined intermediate values are represented by zero addresses.
The error code is translated to obtain the error group index. A zero value causes the node error program to take no further action; otherwise the index is used to obtain the address of the appropriate error processor from the EPVT. A zero address causes the node error program to take no further action; otherwise a call is made to the error processor. This is entered with direct addressability to the NET and CSVT areas. When the error processor has been executed, the node error program returns control to the node abnormal condition program.
The node error program may use a node error table (NET) that comprises the node error blocks (NEBs) used to maintain error status information for individual nodes (see Figure 26). Some or all of the NEBs can be permanently reserved for specific nodes; others are dynamically assigned to nodes when errors occur. Dynamically assigned NEBs are used exclusively for the nodes to which they are assigned until they are explicitly released. All the NEBs have an identical structure of error status blocks (ESBs). Each ESB is reserved for one error processor and associated with it by means of the appropriate error group index. The ESB length and format can be customized to the particular error processor that it serves.
The common subroutines are addressed via the CSVT and provide error processors with the following functions:
Two error processors are supplied for 3270 LUs, as follows:
These error codes correspond to the receipt of sense or status bytes in the user sense fields of the RPL. The error processor locates an ESB of the standard format and updates a weighted error count. The weight, threshold, and timer values are based on those used by the sample terminal error program 3270 except as noted in the previous section. If the threshold is not exceeded, the abend SEND, abend RECEIVE, abend transaction flags, and all the print action flags are turned off. Otherwise the default actions are taken and the NEB is released if it is reusable.
This code means that no 3270 printer was available to satisfy a print request made at a 3270 screen. The error processor examines the printers defined for this screen to determine why they were unavailable. If either is busy on a previous PRINT or COPY request (that is, a task is attached with a transaction ID of CSPP or CSCY) or is no longer unavailable, that printer address is returned to the node abnormal condition program which retries the print request with an IC PUT command. Otherwise the default actions are taken. (For more details, see the section Coding for the 3270 ‘unavailable printer’ condition.)
Only one error processor is supplied for interactive LUs: group index 1, with error code X'DC'.
This error code, in combination with a user sense value of X'081B', indicates a ‘receiver in transmit mode’ condition. The action flags in TWANPFW are manipulated to allow the failing SEND request to be retried.
The routing mechanism, common subroutines, CICS-supplied error processors, and user-supplied error processors are generated by means of DFHSNEP macros.
The sample node error program and table need to be translated, assembled, and link-edited. For information about the job control statements required to assemble and link-edit user-replaceable programs, refer to Assembling and link-editing user-replaceable programs.
Note that you should code the translator options NOPROLOG and NOEPILOG in your node error program.
Note also that an extra 24 bytes are required for the common subroutines register save area, and further space is required for the error processor save area. The CICS sample processors use 4 bytes of this area.
The DFHSNEP macro to generate the sample node error program has seven types, as follows:
The DFHSNEP TYPE=USTOR macro has the following format:
DFHSNEP TYPE=USTOR
This macro indicates the start of user storage definitions. It must be followed by your storage definitions, and then by DFHSNEP TYPE=USTOREND. If you use DFHSNEP TYPE=USTOR to define storage, then both it and DFHSNEP TYPE=USTOREND must be coded before DFHSNEP TYPE=INITIAL.
The DFHSNEP TYPE=USTOREND macro has the following format:
DFHSNEP TYPE=USTOREND
This macro indicates the end of user storage definitions. Its use is mandatory if DFHSNEP TYPE=USTOR has been coded. If you use DFHSNEP TYPE=USTOR to define storage, then both it and DFHSNEP TYPE=USTOREND must be coded before DFHSNEP TYPE=INITIAL.
One DFHSNEP TYPE=INITIAL macro must appear immediately after DFHSNEP TYPE=USTOR and DFHSNEP TYPE=USTOREND (if they are coded) and before the remaining macros.
DFHSNEP TYPE=INITIAL
[,CS=NO]
[,NAME=name]
[,NETNAME=netname]
The DFHSNEP TYPE=DEF3270 macro has the following format:
DFHSNEP TYPE=DEF3270
DFHSNEP TYPE=ERRPROC,GROUP=1,CODE=(D9,DC,DD,F2)
Sense/status error processor code.
DFHSNEP TYPE=ERRPROC,GROUP=2,CODE=42
Unavailable printer error processor code.
The DFHSNEP TYPE=DEFILU macro has the following format:
DFHSNEP TYPE=DEFILU
DFHSNEP TYPE=ERRPROC,GROUP=1,CODE=DC
(receiver in transmit mode error processor code)
One DFHSNEP TYPE=FINAL macro must follow all the other DFHSNEP macros. It has the following format:
DFHSNEP TYPE=FINAL
The DFHSNEP TYPE=ERRPROC macro is used to indicate the start of a user-supplied error processor. The actual error processor code should immediately follow this macro. The assembly should be terminated by the statement END DFHNEPNA.
The following operands can be used on the DFHSNEP TYPE=ERRPROC macro:
DFHSNEP TYPE=ERRPROC
,CODE=(error-code,...)
,GROUP=error-group-index
If you intend to add your own error processors to the sample node error program, you should consider the following factors:
Register | Use |
---|---|
0 | Work register |
1 | Address of the EXEC parameter list |
2 | NEB base register (DFHSNEP only) |
3 | ESB base register (DFHSNEP only)
NEP error class register (DFHZNEPI only) |
4 | NEP name pointer register (DFHZNEPI only) |
5 | NEP interface base register (DFHZNEPI only) |
6 | Work register |
7 | Work register |
8 | Work register |
9 | Work register |
10 | Code base register |
11 | Address of the EIB |
12 | Address of the communication area |
13 | Address of DFHEISTG storage |
14 | CSVT base and error processor link register
Common subroutine link register |
15 | Error processor branch register
Common subroutine branch register. |
The DFHSNET macro is used to generate a node error table. Each node error table that you generate must be defined to CICS.
DFHSNET [NAME=DFHNET|name]
[,COUNT=100|threshold]
[,ESBS=1|(index,length,...)]
[,NEBNAME=(name,...)]
[,NEBS=10|number]
[,TIME=(7,MIN)|(interval,units)]
This operand is optional and defaults to 1. This causes each NEB to be generated with one ESB for error group 1 with a status area length of 6 bytes.
The following DSECTs are provided:
Node Error Table Header: This contains the table name and common information relevant for all the node error blocks (NEBs) in the table.
DFHNETH DSECT
NETHNAM DS CL8 Table name
NETHNBN DS H Number of NEBs in table
NETHNBL DS H Length of NEBs in table
NETHTIM DS PL8 Error count time interval
NETHECT DS H Error count threshold
NETHFLG DS X Flag byte
NETHINI EQU X'01' Table initialized
DS X Reserved
NETHFNB DS 0F First NEB
Node Error Block: The table contains node error blocks that are used for recording error information for individual nodes. These can be permanently assigned to specific nodes or dynamically assigned at the request of error processors.
DFHNETB DSECT
NEBNAM DS CL4 Node name
NEBFLG DS X Flag byte
NEBPERM EQU X'01' Permanently assigned NEB
DS XL3 Reserved
NEBFESB DS 0X First NEB
Error Status Block: The NEBs can contain error status blocks. These are reserved for specific error processors and are identified by the corresponding error group index. An ESB can have a format defined by you, or can have a standard format suitable for counting errors over a fixed time interval.
DFHNETE DSECT
ESBEGI DS X Error group index
ESBFLG DS X Flag byte
ESBSTAN EQU X'01' Standard format ESB
ESBTTE EQU X'02' Time threshold exceeded
ESBCTE EQU X'04' Count threshold exceeded
ESBSLEN DS XL2 Status area length
ESBHLEN EQU *-DFHNETE ESB header length
ESBSTAT DS 0X Status area
The following fields apply to the standard format:
ESBTIM DS PL8 Time stamp
ESBEC DS XL2 Error count
Common Subroutine Vector Table: The CSVT provides error processors with addressability to the common subroutines. The error processor link register gives addressability to the CSVT and so the first section of the DSECT overlies the code required to branch around the actual table.
DFHNEPC DSECT
DS F Load instruction
DS F Branch instruction
CSVTNEP DS A Node error program base address
CSVTESBL DS A NEPESBL - ESB locate routine
CSVTNEBD DS A NEPNEBD - NEB delete routine
CSVTECUP DS A NEPECUP - error count update
routine