The sample terminal error program

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.

Components of the sample terminal error program

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).

TEP error table

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):

Figure 16. TEP error table
 The picture shows a rectangle representing the TEP error table. The rectangle is divided horizontally into two. The top section is labeled "TEP error table header (TETH)". The lower section is labeled "Terminal error blocks (P-TEBs and R-TEBs)".

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.

Note:
Ensure that the pool is large enough to hold the maximum number of terminals for which errors are expected to be outstanding at any one time. If the pool limit is exceeded, handling of terminal errors may become intermittent. No warning is given of this condition.

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.

Figure 17. Terminal error block (TEB)
 The picture shows a terminal error block consisting of a symbolic terminal ID, a number of error status elements, and a common error bucket.

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.

TEP default table

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.

Structure of the sample terminal error program

The structure of the sample terminal error program (DFHXTEP) can be broken down into six major areas as follows:

  1. Entry and initialization
  2. Terminal identification and error code lookup
  3. Error processor selection
  4. Error processing execution
  5. General exit
  6. Common subroutines.

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.

Entry and initialization

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.

Terminal ID and error code lookup

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.

Error processor selection

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.

Error processing execution

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.

General exit

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.

Common subroutines

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:

TEPACT
Used to output the names of the action bits set by DFHTACP and the sample DFHTEP in the communication area field TEPCAACT if appropriate PRINT options are selected when the program is generated.
TEPDEL
Used to delete the terminal error block and error status elements for a terminal from the TEP error table on exit from an error processor.
TEPHEXCN
Used by TEPPUTTD to convert a 4-bit hexadecimal value to its 8-bit printable equivalent.
TEPINCR
Used to update and test the count and time threshold totals maintained in the terminal’s error status element.
TEPLOC
Used to locate or assign terminal error blocks and error status elements for a terminal ID.
TEPPUTTD
Used to output character or hexadecimal data to a user-defined transient data destination.
TEPTMCHK
Used by TEPINCR to determine whether the time threshold has been passed.
TEPWGHT
Used to update the weight/time threshold values maintained in the terminal’s error status elements.
Figure 18. Overview of the sample terminal error program (DFHXTEP)
 The picture shows the structure of the sample terminal error program, as described in the preceding pages. The program is seen to move through the following stages: entry and initialization; terminal ID and error code lookup; error processor selection (a number of alternative error processors are shown, some of which make use of common subroutines); error processor execution; general exit.

Sample terminal error program messages

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:

DFHTEP, ERROR - error text
During DFHTEP module generation, the PRINT parameter specified ERRORS. This message can be suppressed by using the NOERRORS option. The error text is one of the following:
Unsupported error code, "xx"
The error code presented to DFHTEP by DFHTACP is unknown to DFHTEP.
"DFHTEPT" not defined in system
The DFHTEP table could not be loaded into storage.
Unknown error status message, "xxxx"
The error status message presented from a remote 3270 type device could not be decoded.

None of these errors should occur.

DFHTEP, ACTION - action flag names
During DFHTEP module generation, the PRINT parameter specified TACPACTION or TEPACTION or both. If both are specified, this message is logged twice each time DFHTEP is called. The first message indicates the action flags as set by DFHTACP on entry to DFHTEP. The second message indicates the action flags as returned to DFHTACP by DFHTEP after error processing. These messages can be suppressed by using the NOTACPACTION and NOTEPACTION options.

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.

Flag name
Description
LINEOS
Place line out of service
NONPRGT
Nonpurgeable task exists on terminal
TERMOS
Place terminal out of service
ABENDT
Abend task on terminal
ABORTWR
Abort write, free terminal storage
RELTTIOA
Release incoming message
SIGNOFF
Sign off terminal.
DFHTEP, TID - tid
During the DFHTEP module generation, the PRINT parameter specified TID. This message contains the symbolic terminal ID of the device associated with the error. This message can be suppressed by using the NOTID option.
DFHTEP, DECB - DECB information
During the DFHTEP module generation, the PRINT parameter specified DECB. This two-line message contains the DECB (printed in hexadecimal format) of the terminal causing the error. The DECB is contained in the TACLE (displacement +16 [decimal]). See the TACLE DSECT described in Writing your own terminal error program. This message can be suppressed by using the NODECB option.
DFHTEP, TACLE - TACLE information
During the DFHTEP module generation, the PRINT parameter specified TACLE. This message (printed in hexadecimal format) contains the first 16 bytes of the TACLE passed to DFHTEP by DFHTACP. See the TACLE DSECT described in Writing your own terminal error program. This message can be suppressed by using the NOTACLE option.
DFHTEP, ESE - ESE information
During the DFHTEP module generation, the PRINT parameter specified ESE. This message contains the error status element. The message can be suppressed by using the NOESE option.

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:

Table 21. Format of error status element on DFHTEP, ESE messages--NOTIME specified
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.
Table 22. Format of error status element on DFHTEP, ESE messages--TIME specified
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.

Generating the sample terminal error program

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.

Job control for generating the sample terminal error program

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:

DFHTEP
Sample TEP module, assembled from DFHXTEP
DFHTEPT
Sample TEPT table, assembled from DFHXTEPT.

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.

DFHTEPM-generating the sample DFHTEP module

The sample DFHTEP module is generated by the following macros:

Note:
You must code the translator options NOPROLOG and NOEPILOG in your error processors if you use these 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])]
TYPE=INITIAL
establishes the beginning of the generation of the sample DFHTEP module itself.
DSECTPR={YES|NO}
controls the printing of CICS DSECTs on the sample DFHTEP assembly listing. Its purpose is to reduce the size of the listing. The default is DSECTPR=YES.
YES
Printing of the DSECTs is allowed.
NO
Printing of selected CICS DSECTs is suppressed. This parameter should not be used under Assembler F.
OPTIONS=optional-routines
includes or excludes optional routines in the DFHTEP module. The parentheses are required even when only one option is specified. If this operand is omitted, all default options are generated.
TD|(TD, destid)|NOTD
specifies whether information regarding the errors is to be written to a transient data destination.
TD
The transient data output routine is to be generated. The implied transient data destination is CSMT.
(TD, destid)
The transient data output routine is to be generated. The messages are sent to the destination specified by "destid", which must be defined in the destination control table.
NOTD
No messages are to be written to a transient data destination.
EXITS|NOEXITS
specifies whether "ENTRY" and "EXIT" user routine support is to be included.
EXITS
Branches are taken to ENTRY and EXIT routines before and after error processing. Dummy routines are provided if user routines are not used.
NOEXITS
No branches are taken to user routines.
TIME|NOTIME
specifies whether threshold tests are to be controlled over prescribed time intervals. An example might be putting a terminal out of service if more than three instances of a given type of error occur in one hour. The parameter must be the same as the OPTIONS operand in the DFHTEPT TYPE=INITIAL macro.
TIME
This type of threshold testing is supported.
NOTIME
This type of threshold testing is not supported.
PRINT=print-information
specifies which types of information are to be logged to the transient data destination each time an error occurs. If NOTD is specified on the OPTIONS operand, all PRINT parameters default to NO. All PRINT parameters require the transient data output routine. The parentheses are required even when only one parameter is specified.
ERRORS|NOERRORS
specifies whether unprocessable conditions detected by the sample DFHTEP are to be recorded on the transient data destination.
ERRORS
Error messages are to be logged.
NOERRORS
No error messages are to be logged.
TACPACTION|NOTACPACTION
specifies whether DFHTACP default actions are to be recorded on the transient data destination.
TACPACTION
The default actions are logged.
NOTACPACTION
No default actions are logged.
TEPACTION|NOTEPACTION
specifies whether the actions selected as a result of sample DFHTEP processing are to be recorded on the transient data destination.
TEPACTION
The final actions are logged.
NOTEPACTION
No final actions are logged.
TID|NOTID
specifies whether the symbolic terminal ID of the terminal associated with an error is to be recorded on the transient data destination.
TID
The terminal ID is to be logged.
NOTID
No terminal IDs are to be logged.
DECB|NODECB
specifies whether the DECB of the line associated with error is to be recorded on the transient data destination.
DECB
The DECB is logged. The hexadecimal representation of the DECB is logged as two 24-byte messages.
NODECB
No DECB logging occurs.
TACLE|NOTACLE
specifies whether the TACLE prefix is to be recorded on the transient data destination.
TACLE
The 16-byte TACLE prefix as received from DFHTACP is logged.
NOTACLE
No TACLE prefix logging occurs.
ESE|NOESE
specifies whether the ESE associated with the error is to be recorded on the transient data destination.
ESE
The ESE, after being updated, and before being deleted (if the action puts the terminal out of service) is logged.
NOESE
No ESE logging occurs.

DFHTEPM TYPE=ENTRY and EXIT-for user entry and exit routines

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.

DFHTEPM TYPE=ERRPROC-replacing error processors

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)
TYPE=ERRPROC
indicates that a CICS-supplied error processor routine is to be replaced with the user-written error processor that immediately follows the macro. This macro is optional; if used, it must follow the DFHTEPM TYPE=INITIAL macro. One DFHTEPM TYPE=ERRPROC macro must precede each user-written error processor source routine.
CODE=errcode
is used to identify the error code assigned to the appropriate error condition. These codes are listed in Figure 22.

DFHTEPM TYPE=FINAL-ending the sample DFHTEP module

The macro to terminate the sample DFHTEP module is:

DFHTEPM  TYPE=FINAL

This is followed by an END DFHTEPNA statement.

DFHTEPM macro examples

  1. The following is an example of the minimum number of statements required to generate a sample DFHTEP module:
       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.

  2. Figure 19 is an example of a more tailored sample DFHTEP module. In this example no 3270 support is generated. All default types of information except for TACP and TEP actions are to be logged to the TEPQ transient data destination. The CICS DSECTs are not printed on the sample DFHTEP assembler-language listing. There are two error processor routines (codes ‘87’ and ‘9F’ respectively).
Figure 19. Example of DFHTEPM macros used to generate a sample DFHTEP module
  * 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
 

DFHTEPT-generating the sample DFHTEP tables

The following macros are required to generate the terminal error program tables:

DFHTEPT TYPE=INITIAL-establishing the control section

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}]
TYPE=INITIAL
establishes the beginning of the generation of the TEP tables.
MAXTIDS=number
specifies the total number of permanent and reusable terminal error blocks to be generated in the TEP error table. Permanent entries are defined by the DFHTEPT TYPE=PERMTID macro described later in this section. Any entries not defined as permanent are reused when the terminal is taken out of service, or are deleted at the request of an error processor. If an error occurs, and no TEB space is available, the error is not processed, and DFHTACP default actions are taken. The minimum number of blocks is 1. A maximum number is not checked for but should be no greater than the number of terminals in your network.
MAXERRS=25|number
specifies the number of errors to be recorded for each terminal. This value determines the number of permanent and reusable error status elements in each TEB. The maximum number that can be specified is 25 (the default value). If more are requested, only the maximum are generated. If fewer are requested, one extra ESE is generated for each TEB. The extra ESE is the common error bucket. Permanently reserved ESEs are defined by the DFHTEPT TYPE=PERMCODE macro described later in this section. Any ESEs not defined as permanent are dynamically assigned on the first occurrence of a nonpermanent error type associated with the terminal. By defining a number less than the maximum, and allowing the sample DFHTEP to assign ESEs dynamically, you can minimize the size of the table and still control and account for the error types relevant to the network. The minimum number that can be specified is zero. In this case only a common error bucket is generated.
OPTIONS={TIME|NOTIME}
specifies whether time threshold space is to be reserved in support of the TIME option specified in the DFHTEPM TYPE=INITIAL macro. The default is OPTIONS=TIME.
TIME
Time threshold space is reserved.
NOTIME
Time threshold space is not reserved.

DFHTEPT TYPE=PERMTID-assigning permanent terminal error blocks

The DFHTEPT TYPE=PERMTID macro to define permanently reserved terminal error blocks for specific terminals is:

DFHTEPT  TYPE=PERMTID
         ,TRMIDNT=name
TYPE=PERMTID
defines permanently reserved terminal error blocks for specific terminals. Permanent TEBs are defined for terminals that are critical to system operation to ensure that error processors are always executed in the event of errors associated with that terminal. If no permanent TEBs are to be defined, this macro is not required. A separate macro must be issued for each permanently reserved TEB. The maximum number of permanent TEBs is the number specified in the MAXTIDS operand of the DFHTEPT TYPE=INITIAL macro.
TRMIDNT=name
is used to provide the symbolic terminal ID (1-4 characters) for a permanently defined TEB. Only one terminal can be specified in each macro.

DFHTEPT TYPE=PERMCODE|ERRCODE-defining error status elements

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])]
TYPE={PERMCODE|ERRCODE}
identifies whether the error code specified in the macro is to have a permanently reserved or a dynamically assigned ESE. These macros are required only if permanently reserved ESEs are to be defined, or if the sample DFHTEP default threshold constants are to be overridden. These are listed in Table 23.
PERMCODE
Identifies the error code specified as having a permanently reserved ESE. Each permanently reserved ESE must be identified by a separate DFHTEPT TYPE=PERMCODE macro. All DFHTEPT TYPE=PERMCODE macros must precede all DFHTEPT TYPE=ERRCODE macros.
ERRCODE
Indicates that the error code specified does not require a permanently reserved ESE, but that the sample DFHTEP default threshold constants are to be changed. Each error code requiring a threshold constant change, other than those defined as permanently reserved, must be identified by a separate DFHTEPT TYPE=ERRCODE macro. All DFHTEPT TYPE=ERRCODE macros must follow all DFHTEPT TYPE=PERMCODE macros.
CODE={errcode|BUCKET}
identifies the error code referred to by the TYPE=PERMCODE|ERRCODE parameter. These codes are listed in Figure 22. CODE=BUCKET is only applicable to the DFHTEPT TYPE=ERRCODE macro. It is used to override the default threshold constants established for the common error bucket.
COUNT=number
can be used in either the DFHTEPT TYPE=PERMCODE or TYPE=ERRCODE macro to override the sample DFHTEP default count threshold (see Table 23). When the number of occurrences of the error type specified reaches the threshold, an error processor normally takes a logic path that causes DFHTACP default actions to be taken. If the number of occurrences is less than the threshold, the error processor normally takes a logic path that overrides the DFHTACP default actions. The updating and testing of the current threshold counts are normally performed by a DFHTEP subroutine that sets a condition code that the error processor can test to determine whether the limit has been reached. If you specify 0 as the number in the COUNT operand, you are not told when the threshold is reached.
TIME=(number[,SEC|,MIN|,HRS])
can be used in either the DFHTEPT TYPE=PERMCODE or TYPE=ERRCODE macros to override the sample DFHTEP default time threshold (see Table 23). This operand is only applicable when OPTIONS=TIME is specified on both the DFHTEPM and DFHTEPT TYPE=INITIAL macros. When the number of occurrences reaches the threshold specified on the COUNT operand (above) within the interval specified on this parameter, an error processor normally takes a logic path that causes DFHTACP default actions to be taken. If the number of occurrences within the interval is less than the threshold, the error processor normally takes a logic path that overrides the DFHTACP default actions. If the time interval has expired, the sample DFHTEP subroutine that normally updates and tests the current threshold count resets the occurrence counts, and establishes a new expiration time. In this case, the condition code set by the subroutine indicates that the thresholds had not been reached.

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:

number
The interval in units of one hundredth of a second. Parentheses are not required if this method is used. The maximum number must be less than 8 640 000 (24 hours).
(number,SEC)
The interval in whole seconds, which must be enclosed in parentheses. The maximum number must be less than 86 400 (24 hours).
(number,MIN)
The interval in whole minutes, which must be enclosed in parentheses. The maximum number must be less than 1440 (24 hours).
(number,HRS)
The interval in whole hours, which must be enclosed in parentheses. The maximum number must be less than 24.

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.

Table 23. Default thresholds of the sample TEP
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:
  1. The error processor maintains an error count only. DFHTACP default actions are always taken regardless of the thresholds.

  2. The error processor uses a threshold "weight" instead of a threshold count (see the source code of the sample DFHTEP).

DFHTEPT TYPE=BUCKET-using the error bucket for specific errors

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
TYPE=BUCKET
generates the macro to account for specific error conditions in the common error bucket. If MAXERR=25 on the DFHTEPT TYPE=INITIAL macro, this macro cannot be used. This macro is not required if no error codes are to be specifically accounted for in the common error bucket. Each error code must be identified by a separate DFHTEPT TYPE=BUCKET macro.
CODE=errcode
identifies the error code to be specifically accounted for in the common error bucket. The error code must not be specified in the DFHTEPT TYPE=PERMCODE or TYPE=ERRCODE macro.

DFHTEPT TYPE=FINAL-terminating DFHTEPT entries

The DFHTEPT TYPE=FINAL macro terminates the generation of the DFHTEP tables.

DFHTEPT  TYPE=FINAL

DFHTEPT-examples of how the macros are used

  1. The following is an example of the minimum number of statements required to generate the TEP tables:
    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.

  2. Figure 20 is an example of a customized TEP table (continuation characters omitted).
    Figure 20. Example of the use of DFHTEPT macros to generate DFHTEP tables
    * 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.

Related concepts
Background to error handling for sequential devices
Related tasks
Writing your own terminal error program
Rewriting user-replaceable programs
Assembling and link-editing user-replaceable programs
Related reference
User-replaceable programs and the storage protection facility
[[ Contents Previous Page | Next Page Index ]]