CICS® provides a sample terminal error program that can be used as a generalized program structure for handling terminal errors. Note that, although the source code form of the sample TEP (DFHXTEP) is provided in assembler language only, you can write your own terminal error program in any of the languages supported by CICS.
After DFHXTEP has been assembled, it is link-edited as DFHTEP. For information about the job control statements necessary to assemble and link-edit user-replaceable programs, refer to Assembling and link-editing user-replaceable programs.
You can generate and use the sample terminal error program with the default options provided, or you can customize the terminal error support to the needs of the operating environment by selecting the appropriate generation options and variables. Because each error condition is processed by a separate routine, you can replace a CICS-provided routine with a user-written one when the sample TEP is generated.
The sample terminal error program consists of the terminal error program itself and two terminal error program tables:
Both tables contain "thresholds" defined for the various error conditions to be controlled and accounted for by the sample DFHTEP. A "threshold" may be thought of as the number of error occurrences that are permitted for a given type of error on a given terminal before the sample DFHTEP accepts the DFHTACP default actions. Optionally, the number of occurrences can be controlled and accounted for over prescribed time intervals (for example, if more than three of a given type of error occur in an hour, the terminal is put out of service).
The terminal error program (TEP) error table maintains information about errors that have occurred on a terminal. The table consists of two parts (shown in Figure 16):
TEBs maintain error information associated with terminals. You must specify the total number of TEBs to be generated. The maximum number needed is one per terminal. In this case the TEBs are permanent.
You can reduce the total amount of storage used for TEBs by allocating a pool of reusable TEBs, that are not permanently associated with a particular terminal. Reusable TEBs are assigned dynamically on the first occurrence of an error associated with a terminal, and are released for reuse when the appropriate error processor places the terminal out of service.
You should assign permanent TEBs to terminals that are critical to the network. For the remainder of the network, you can generate a pool of reusable TEBs.
Each TEB currently in use or permanently assigned contains the symbolic terminal identifier of the terminal, and one or more error status elements (ESEs), as shown in Figure 17.
An ESE records the occurrence of a particular type of error associated with the terminal. The contents of an error status element are described in the TEPCD DSECT (generated by the DFHTEPM TYPE=INITIAL macro) under the comment "ERROR STATUS ELEMENT FORMAT". The number of ESEs per TEB remains constant for all TEBs. You specify the number when the TEP tables are generated. If fewer than the maximum number of error types recognized by DFHTACP (25) are specified, one additional ESE, referred to as the "common error bucket", is generated for each TEB.
You can permanently reserve ESE space in each TEB for specific error types. Those not permanently reserved are considered reusable, and are assigned dynamically on the first occurrence of a particular error type associated with the terminal. If an error type occurs that is not currently represented by an ESE, and if all reusable ESEs are assigned to other error types, the occurrence of this error is recorded in the common error bucket. DFHTACP can recognize far more error types than can occur in a typical terminal network. By specifying less than the maximum and allowing the sample DFHTEP to assign ESEs dynamically, you can minimize the table size, and still control and account for the types of errors relevant to the network.
The terminal error program (TEP) default table contains the "number and time" thresholds for each type of error to be controlled and accounted for. An index array at the beginning of the default table serves a dual function. If the value in the index is positive, then the error code has a permanently defined ESE in each TEB and the index value is the displacement to the reserved ESE. If the index value is negative, then an ESE must be assigned dynamically from a reusable ESE if one has not already been created by a prior occurrence. The complement of the negative index value is the displacement to the thresholds for the error type retained in the TEP default table.
The structure of the sample terminal error program (DFHXTEP) can be broken down into six major areas as follows:
These areas are described in detail in the sections that follow.
Figure 18 gives an overview of the structure of the sample terminal error program.
On entry, the sample TEP uses DFHEIENT to establish base registers and addressability to EXEC Interface components. It obtains addressability to the communication area passed by DFHTACP by means of an EXEC CICS ADDRESS COMMAREA, and addressability to the EXEC interface block with an EXEC CICS ADDRESS EIB command. It gets the address of the TACLE from the communication area, and establishes access to the TEP tables with an EXEC CICS LOAD. If time support has been generated, the error is time-stamped for subsequent processing. (Current time of day is passed in the communication area.) The first entry into the sample TEP after the system is initialized causes the TEP tables to be initialized.
After the general entry processing, the TEP error table is scanned for a terminal error block (TEB) entry for the terminal associated with the error. If no matching entry is found, a new TEB is created. If all TEBs are currently in use (if no reusable TEBs are available), the processing is terminated and a RETURN request is issued, giving control back to DFHTACP, where default actions are taken.
After the terminal’s TEB has been located or created, a similar scan is made of the error status elements (ESEs) in the TEB to determine whether the type of error currently being processed has occurred before, or if it has permanently reserved ESE space. If an associated ESE is not found, an ESE is assigned for the error type from a reusable ESE. If a reusable ESE does not exist, the error is accounted for in the terminal’s common error bucket. The addresses of the appropriate control areas (TEB and ESE) are placed in registers for use by the appropriate error processor.
User-specified message options are selected and the messages are written to a specified transient data destination. The type of error code is used as an index to a table to determine the address of an error processor to handle this type of error. If the error code is invalid, or the sample TEP was not generated to process this type of error, the address points to a routine that optionally generates an error message and returns control to DFHTACP, where default actions are taken. If an address of a valid error processor is obtained from the table, control is passed to that routine.
The function of each error processor is to determine whether the default actions established by DFHTACP for a given error, or the actions established by the error processor, are to be performed. The common error bucket is processed by the specific error processor. However, the thresholds of the common error bucket are used in determining whether the limit has been reached. Subroutines are provided in the sample TEP to maintain count and time threshold totals for each error associated with a particular terminal to assist the error processor to make its decision. Also available are subroutines for logging the status of the error and any recovery action taken by the error processor.
You can replace any of the error processors supplied in the sample TEP with user-written ones. Register linkage conventions, error conditions, DFHTACP default actions, and sample TEP error processor actions are described in comments given in the sample DFHXTEP source listing. However, sample DFHXTEP actions, in many cases, can be altered by changing the thresholds when generating the TEP tables.
Control is passed to a general exit routine from each error processor. This routine determines whether the terminal is to remain in service. If the terminal is to be put out of service, the terminal error block and all error status elements for that terminal are deleted from the TEP error table unless the terminal was defined as a permanent entry. When the terminal is placed back in service, a new terminal error block is assigned if a subsequent error occurs.
A number of subroutines are provided in the sample DFHXTEP for use by the error processors. Each subroutine entry has a label of the form "TEPxxxxx" where "xxxxx" is the subroutine name. All labels within a subroutine start with TEPx where "x" is the first character of the subroutine name. All subroutines are arranged within the module in alphabetical order in the subroutine section. Register conventions and use of the subroutine are given as comments at the beginning of each subroutine in the source listing.
The following subroutines are available for writing your own error processors:
The messages logged to the transient data destination CSMT (or, optionally, to the destination specified in the OPTIONS operand of DFHTEPM TYPE=INITIAL) are of six types, each identified by a unique message prefix. You can control the selection of each type of message by using the appropriate parameters specified on the PRINT operand of DFHTEPM TYPE=INITIAL.
These messages are:
None of these errors should occur.
The action flag names and descriptions are listed below. For further information about the actions taken by DFHTACP, see the description of the TEPCAACT field in Addressing the contents of the communication area.
An ESE is either 6 bytes or 12 bytes long, depending on whether the TIME option was specified when generating the TEP tables. The formats are as follows:
Display
|
Length
(bytes) |
Significance -- NOTIME specified |
---|---|---|
0 | 2 | Error threshold counter or weight value in binary format |
2 | 2 | Current error count or weight value in binary |
4 | 1 | Error code |
5 | 1 | Not used. |
Display
|
Length
(bytes) |
Significance -- TIME specified |
---|---|---|
0 | 5 | Error threshold counter or weight value in binary format |
5 | 3 | Timed threshold value in hundredths of a second |
8 | 4 | Time of first occurrence of this error. Time given as binary integer in hundredths of a second. |
For information about how to generate the sample terminal error program and the sample terminal error table, refer to Assembling and link-editing user-replaceable programs.
The sample program and tables provide you with default error processing for terminal errors. If you want to replace the supplied error processors with user-written error processors, you must use the DFHTEPM and DFHTEPT macros to generate a sample error program and tables that include your user-written routines. Some of the parameters specified in the DFHTEPM and DFHTEPT macros are related and care must be taken to ensure compatibility. The parameters concerned are identified in the descriptions of the macros later in this section.
If you use the sample terminal error program (DFHXTEP), you can generate the required program and transaction definitions by using the CEDA INSTALL GROUP(DFHSTAND) command.
The generation of the sample terminal error program consists of two separate assembly and link-edit steps, one to create the sample TEP module itself, and the other to create the TEP tables. The names under which the components must be link-edited are:
For information about the job control statements necessary to assemble and link-edit user-replaceable programs, refer to Assembling and link-editing user-replaceable programs.
The sample DFHTEP module is generated by the following macros:
DFHTEPM TYPE=USTOR
This macro indicates the start of user storage definitions. It must be followed by your storage definitions, and then by DFHTEPM TYPE=USTOREND. If you use DFHTEPM TYPE=USTOR to define storage, then both it and DFHTEPM TYPE=USTOREND must be coded before DFHTEPM TYPE=INITIAL.
DFHTEPM TYPE=USTOREND
This macro indicates the end of user storage definitions. Its use is mandatory if DFHTEPM TYPE=USTOR has been coded. If you use DFHTEPM TYPE=USTOR to define storage, then both it and DFHTEPM TYPE=USTOREND must be coded before DFHTEPM TYPE=INITIAL.
DFHTEPM TYPE=INITIAL
[,DSECTPR={YES|NO}]
[,OPTIONS=([TD|(TD,destid)|NOTD]
[,EXITS|,NOEXITS]
[,TIME|,NOTIME]
[,PRINT=([ERRORS|NOERRORS]
[,TACPACTION|,NOTACPACTION]
[,TEPACTION|,NOTEPACTION]
[,TID|,NOTID]
[,DECB|,NODECB]
[,TACLE|,NOTACLE]
[,ESE|,NOESE])]
The sample DFHTEP provides guidance about how to prepare error processor routines, particularly with regard to register and subroutine linkage conventions. The routines must also observe the following restrictions:
The macro required for a user "ENTRY" routine is:
DFHTEPM TYPE=ENTRY
This macro must be immediately followed by user "ENTRY" routine code, starting with the label "TEPENTRY" and ending with a BR 14 instruction.
The macro required for a user "EXIT" routine is:
DFHTEPM TYPE=EXIT
This macro must be immediately followed by user "EXIT" routine code, starting with the label "TEPEXIT" and ending with a BR 14 instruction.
The macro necessary to replace error processors supplied with the sample DFHTEP with user-written error processors is:
DFHTEPM TYPE=ERRPROC
,CODE=errcode
(followed by the appropriate error
processor source statements)
The macro to terminate the sample DFHTEP module is:
DFHTEPM TYPE=FINAL
This is followed by an END DFHTEPNA statement.
DFHTEPM TYPE=INITIAL
DFHTEPM TYPE=FINAL
END DFHTEPNA
This example generates a sample DFHTEP module with CICS-supplied error processors and all default options. This is equivalent to the CICS-supplied sample terminal error program.
* GENERATE USER STORAGE
DFHTEPM TYPE=USTOR
USORFLD DS F
DFHTEPM TYPE=USTOREND
* MODULE SPECIFICATIONS
DFHTEPM TYPE=INITIAL, *
OPTIONS=((TD,TEPQ),NO3270,EXITS), *
PRINT=(NOTEPACTION,NOTACPACTION), *
DSECTPR=NO
* USER-SUPPLIED ERROR PROCESSORS
DFHTEPM TYPE=ERRPROC,CODE=87
TEPCD81 DS 0H
-
- error processor "87" source statements
-
B TEPRET
DFHTEPM TYPE=ERRPROC,CODE=9F
TEPCD9C DS 0H
-
- error processor "9F" source statements
-
B TEPRET
* USER "EXIT" EXIT CODE
DFHTEPM TYPE=EXIT
TEPEXIT DS 0H
-
-
Additional user source statements to be executed after
error processing:
-
-
BR R14
* CONCLUDE MODULE GENERATION
DFHTEPM TYPE=FINAL
END DFHTEPNA
The following macros are required to generate the terminal error program tables:
The DFHTEPT TYPE=INITIAL macro necessary to establish the control section for the TEP tables is:
DFHTEPT TYPE=INITIAL
,MAXTIDS=number
[,MAXERRS={25|number}]
[,OPTIONS={TIME|NOTIME}]
The DFHTEPT TYPE=PERMTID macro to define permanently reserved terminal error blocks for specific terminals is:
DFHTEPT TYPE=PERMTID
,TRMIDNT=name
The DFHTEPT TYPE=PERMCODE|ERRCODE macro is used to change the default threshold constants of the sample DFHTEP, and to define permanently reserved error status elements:
DFHTEPT TYPE={PERMCODE|ERRCODE}
,CODE={errcode|BUCKET}
[,COUNT=number]
[,TIME=(number[,SEC|,MIN|,HRS])]
Time control in the sample DFHTEP starts with the first occurrence of an error type. Subsequent occurrences of the same error type do not establish new starting times, but are accounted for as having occurred within the interval started by the first occurrence. This continues until an error count reaches the threshold within the interval started by the first occurrence, or until the interval has expired. In the latter case, the error being processed becomes a first occurrence, and a new interval is started. A time interval of 0 means that the number of occurrences is to be accounted for and controlled without regard to a time interval. Zero is the implied time interval if the value of the COUNT operand is 0 or 1. It is also the implied time interval if the time options are not generated.
The time interval can be expressed in any one of four units; hours, minutes, seconds, or hundredths of a second. The maximum interval must be the equivalent of less than 24 hours. A practical minimum would be 1 to 2 minutes. This allows for access method retries and the time required to create the task to service each error. The four methods of expressing the threshold time interval are:
Table 23 illustrates the default thresholds of the sample terminal error program, referred to in the TYPE, COUNT, and TIME operands of the DFHTEPT TYPE=PERMCODE|ERRCODE macro.
CODE= | COUNT= | TIME= |
---|---|---|
81 | 3 | (7,MIN) |
84 | 1 | 0 |
85 | 1 | 0 |
87 | 50 (Note 2) | 0 |
88 | 1 | 0 |
8C | 1 | 0 |
8D | 1 | 0 |
8E | 1 | 0 |
8F | 1 | 0 |
90 | 0 | 0 |
91 | 0 | 0 |
94 | 7 | (10,MIN) |
95 (Note 1) | 0 | 0 |
96 | 2 | (1,MIN) |
97 (Note 1) | 0 | 0 |
99 | 1 | 0 |
9F (Note 1) | 0 | 0 |
BUCKET | 5 | (5,MIN) |
Notes:
|
The DFHTEPT TYPE=BUCKET macro is used to ensure that specific error conditions are always accounted for in the common error bucket:
DFHTEPT TYPE=BUCKET
,CODE=errcode
The DFHTEPT TYPE=FINAL macro terminates the generation of the DFHTEP tables.
DFHTEPT TYPE=FINAL
DFHTEPT TYPE=INITIAL,MAXTIDS=10
DFHTEPT TYPE=FINAL
END
This example generates 10 reusable terminal error blocks, each capable of accounting for the maximum number of error types. Time threshold control is supported, and all threshold values are the defaults supported by the sample DFHTEP. This is equivalent to the CICS-supplied sample terminal error program.
* TABLE SPECIFICATIONS
DFHTEPT TYPE=INITIAL,MAXTIDS=10,
MAXERRS=5
* PERMANENT TERMINAL DEFINITIONS
DFHTEPT TYPE=PERMTID,TRMIDNT=TM02
* PERMANENT ERROR CODE DEFINITIONS
DFHTEPT TYPE=PERMCODE,CODE=81
DFHTEPT TYPE=PERMCODE,CODE=87,
COUNT=2,TIME=(1,MIN)
* OTHER THRESHOLD OVERRIDES
DFHTEPT TYPE=ERRCODE,CODE=BUCKET,
COUNT=3,TIME=(3,MIN)
* CONCLUDE TABLE GENERATION
DFHTEPT TYPE=FINAL
END
This example generates 10 terminal error blocks, one of which is reserved for the terminal whose symbolic ID is TM02, and the other nine are reusable. Each TEB has space for five error status elements plus a common error bucket. Of the five ESEs, two are reserved for error codes ‘81’ and ‘87’; the remaining ESEs are available to be assigned dynamically. The thresholds for error code ‘87’ and the common error bucket are being changed. No specific error code is to be accounted for in the common error bucket.