You can write your own terminal error program in any of the languages supported by CICS®. However, CICS-supplied code is provided in assembler language only. The names of the supplied source files and macros, and the libraries in which they can be found, are listed in Table 24.
Name | Type | Description | Library |
---|---|---|---|
DFHXTEP | Source | Sample terminal error program (assembler language) | CICSTS31.CICS.SDFHSAMP |
DFHXTEPT | CSECT | Sample terminal error tables (assembler language) | CICSTS31.CICS.SDFHSAMP |
DFHTEPM | Macro | Sample TEP program generator (assembler language) | CICSTS31.CICS.SDFHMAC |
DFHTEPT | Macro | TEP table generator (assembler language) | CICSTS31.CICS.SDFHMAC |
DFHTEPCA | Macro | Assembler-language communication area | CICSTS31.CICS.SDFHMAC |
The user-written DFHTEP receives control in the same manner as the CICS-supplied sample DFHTEP, described in The communication area. It should therefore use the communication area as its basic interface with DFHTACP.
There are certain restrictions on the commands that a TEP can issue. The use of any commands that require a principal facility causes unpredictable results, and should be avoided. In particular, you should not use commands that invoke the following functions:
After your terminal error program receives control from DFHTACP, it should obtain the address of the communication area by means of an EXEC CICS ADDRESS COMMAREA command.
You generate the communication area DSECT by coding DFHTEPCA TYPE=DSECT in your program. The layout of the communication area is shown in Figure 21.
IN/OUT
PARM
0XL4 Standard Header
TEPCALDS DS XL1 I Function Code Always '1'
TEPCAGDS DS XL2 I Component Code Always 'TC'
DS XL1 Reserved
TEPCATCA DS A I Address of TACLE being processed
TEPCECIA DS A I Address of TCTUA
TEPCECIL DS H I Length of TCTUA
TEPCAACT DS XL1 I/O User action byte
TEPCATID DS CL4 I Terminal identity
TEPCATDB DS F I Current time of day binary
The parameter list contains the following information:
On return to DFHTACP, the flags represent the actions as modified by DFHTEP.
The following factors should be considered when altering the action bits in TEPCAACT:
None of the abend-task, abend-write, or nonpurgeable-task bits is set if the dummy terminal indicator is on, even if DFHTACP would normally set abend task as the default for the error being processed. Therefore, the following remarks apply only to errors related to a real terminal.
The TACLE is created by the terminal control program when the error occurs, and contains all the I/O error information provided by BSAM.
To address the contents of the TACLE, the user-written terminal error program should contain the COPY DFHTACLE and COPY DFHTCTLE statements, in that order. These define the complete DFHTCTLE DSECT. The symbolic names in this DSECT are used to address fields in both the TACLE and the real line entry associated with the error.
The TACLE consists of a 16-byte prefix (defined by COPY DFHTACLE) and a further 48-byte section, which is a modified copy of the DECB of the real line entry at the time the TACLE was created.
To address the TACLE, the user-written terminal error program should therefore contain the statements:
COPY DFHTACLE
COPY DFHTCTLE
L TCTLEAR,TEPCATCA POINT TO TACLE
USING DFHTCTLE,TCTLEAR
Note that fields normally part of the real line entry DECB have offsets increased by 16 in the TACLE.
The following fields in the DECB copy in the TACLE do not represent data copies from the real line entry:
TCTLEDCB (Offset 24 in TACLE,
8 in real TCTLE)
This field in the TACLE points to the real line entry; in the real line entry, it points to the BSAM DCB for the line group.
TCTLECSW (Offsets 46, 48 in TACLE,
TCTLEALP 30, 32 in real TCTLE)
These are used in the TACLE for SAM error information.
The following statements give direct addressability to the real line entry:
COPY DFHTCTLE
COPY DFHTCTTE
L TCTLEAR,TEPCATCA POINT TO TACLE
USING DFHTCTLE,TCTLEAR
L TCTTEAR,TCTLEPTE POINT TO ERROR TCTTE
USING DFHTCTTE,TCTTEAR
DROP TCTLEAR
L TCTLEAR,TCTTELEA POINT TO TCTLE
USING DFHTCTLE,TCTLEAR
After you have carried out the required functions and, optionally, altered the default actions scheduled by DFHTACP, the user-written DFHTEP must return control to DFHTACP by issuing the EXEC CICS RETURN command. DFHTACP then performs the actions specified in the TACLE and causes the error processing task to terminate.
The format of the TACLE DSECT is shown in Figure 22.
TERMINAL ABNORMAL CONDITION LINE ENTRY
Displacement
Dec Hex Code Bytes Label Meaning
0 0 4 TCTLEPSA Storage accounting
RESERVED
8 8 1 TCTLEPFL Error flags
81 Message too long
84 TCT search error
85 Write not valid
87 Unsolicited input
88 Input event rejected
8C Output event rejected
8D Output length of zero
8E No output area
8F Output area exceeded
94 Unit check
95 Unit check
(should not occur)
96 Unit exception
97 Unit exception
(should not occur)
99 Undetermined I/O error
9F Invalid destination
(TCAM: no longer supported)
.
. (All codes not listed are reserved and are
. not intended for use by DFHTEP)
.
9 9 1 TCTLEPF2 Special indicator
01 dummy terminal
12 C 4 TCTLEPTE Address of terminal
entry for terminal
in error
16 10 4 TCTLEECB DECB/copy of line
when error occurred
60 3C 4 TCTLEOA For TCAM lines only.
(No longer supported)
The DFHTEP recursive retry routine is an example of the logic steps necessary to design a portion of the terminal error program. In Figure 23, 10 retries are provided for each terminal; however, the logic could be used for any number of retries. The following assumptions are made:
Because this example requires access to the TCT terminal entry (TCTTE) to examine the SYSTEM COUNT and to locate the process control information (PCI) area, the DFHTCTTE symbolic storage definition is included so that fields can be symbolically referenced.
*ASM XOPTS(NOPROLOG NOEPILOG SP)
************************************************************************
* *
* DFHTEP RECURSIVE RETRY ROUTINE *
* *
************************************************************************
DFHEISTG
DFHEIEND
DFHTEPCA TYPE=DSECT COMMAREA passed by TACP
COPY DFHA06DS Statistics DSECT
USING DFHA06DS,STATBAR
PCIAREA DSECT
PCISAVE DS XL6 User Field A
PCICNT DS PL2 User Field B
*
TCTLEAR EQU 2 Pointer to TACLE
STATBAR EQU 4 Pointer to statistics DSECT
TCTUABAR EQU 5 Pointer to TCTUA
COMMABAR EQU 12 Pointer to COMMAREA passed by TACP
EJECT
DFHTEP CSECT
***********************************************************************
* Establish addressability *
***********************************************************************
DFHEIENT
*
EXEC CICS ADDRESS EIB(11)
*
EXEC CICS ADDRESS COMMAREA(COMMABAR)
*
USING DFHTEPCA,COMMABAR
L TCTLEAR,TEPCATCA Load TACLE address
*
USING PCIAREA,TCTUABAR
L TCTUABAR,TEPCECIA Load TCTUA address
*
***********************************************************************
* Start processing *
***********************************************************************
TM PCICNT+1,X'0C' Has User Field B been initialized
* to a packed decimal number?
BO CKCOUNT YES .... so compare the system count
* with the existing count in Field B
RESET DS 0H
MVC PCICNT,=PL2'+0' NO .... so initialize field B to
* packed zero.
*
EXEC CICS COLLECT STATISTICS TERMINAL(TEPCATID) SET(STATBAR)
* Get statistics for this terminal
* using TERMID passed in Commarea
*
MVC PCISAVE,A06TENI Save the current system counts. This
* is a new error, or first time
* through.
INCR DS 0H
AP PCICNT,=P'1' Increment the number of times this
* error has occurred (recursive count)
*
CP PCICNT,=P'10' Has the maximum recursive error
* limit been reached?
BNE RETRY NO .... set action
*
ZAP PCICNT,=P'0' Clear and reset user fields for next
* error set
EXEC CICS COLLECT STATISTICS TERMINAL(TEPCATID) SET(STATBAR)
* Get statistics for this terminal
* using TERMID passed in COMMAREA
*
MVC PCISAVE,A06TENI Get current system counts
B NORETRY Action indicators for no retry
*
CKCOUNT DS 0H
EXEC CICS COLLECT STATISTICS TERMINAL(TEPCATID) SET(STATBAR)
* Get statistics for this terminal
* using TERMID passed in COMMAREA
*
CLC PCISAVE,A06TENI Has system count changed since last
* entry to TEP?
BNE RESET YES .... this is a new error since
* some I/O activity has occurred on
* terminal.
B INCR NO .... this is a recursive error,
* so increment the recursive count and
* check for retry.
RETRY DS 0H
* The user would include here the code
* necessary to alter the flags in the
* COMMAREA so that a retry can be
* performed on the terminal.
NORETRY DS 0H
* The user would include here the code
* necessary to allow DFHTACP to take
* final actions on the terminal; that
* is, abend task, put line out of
* service, and others.
LTORG ,
END
Note that the code in Figure 23 is intended only as an illustration of a recursive error handling technique and of the steps necessary to establish addressability to the applicable control blocks.