Writing your own terminal error program

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.

Table 24. Supplied source files and macros
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.

Why write your own terminal error program?

Restrictions on the use of EXEC CICS commands

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:

Addressing the contents of the communication area

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.

Figure 21. The DFHTACP/DFHTEP communication area
                              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:

TEPCALDS
Function Code. The Function Code is a printable character representing the identity of the task within the TCP which invoked DFHTEP. It always has the value ‘1’.
TEPCAGDS
Component Code. This always has the value ‘TC’, representing a component of the TCP.
TEPCATCA
Contains the address of the TACLE being processed.
TEPCECIA
Contains the address of the terminal control table user area (TCTUA).
TEPCECIL
Contains the length of the TCTUA.
TEPCAACT
The User action byte. One of the main uses of the communication area is to transmit the actions that are to be taken for a terminal. TEPCAACT contains the following flags, which can be reset within DFHTEP:
LINEOS (X'80')
Place line out of service
NONPRGT (X'40')
Nonpurgeable task exists on the terminal
TERMOS (X'20')
Place terminal out of service
ABENDT (X'10')
Abend the task on the terminal
ABORTWR (X'08')
Abend write, free terminal storage
RELTTIOA (X'04')
Start of changeRelease TCAM incoming message. (TCAM is no longer supported.)End of change
SIGNOFF (X'02')
Call sign-off program.
On entry to DFHTEP, the above flags represent the default actions set by DFHTACP. The write-abend bit (communication area field ABORTWR) and the abend-task bit (communication area field ABENDT) are always set if the place-line-out-of-service bit (X'80') is set; but both bits are suppressed if "dummy terminal" is indicated (see Resetting the flags in the user action byte, TEPCAACT).

On return to DFHTACP, the flags represent the actions as modified by DFHTEP.

TEPCATID
Contains the identity of the terminal in error.
TEPCATDB
Contains the time of day when the error occurred, in binary format.

Resetting the flags in the user action byte, TEPCAACT

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.

Addressing the contents of the TACLE

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.

Figure 22. Format description of the TACLE DSECT
               TERMINAL ABNORMAL CONDITION LINE ENTRY
 
 The picture shows, in graphical format, the same information that is presented, in text format, in the second part of the figure.
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)

Example of a user-written terminal error program

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:

USER FIELD A
(PCISAVE)
represents a 6-byte field in the process control information (PCI) area of the TCTTE. This field is used to preserve the count of input and output from the TCTTE when the first error occurs. These counts are contained in 3-byte fields located at TCTTENI and TCTTENO within the TCTTE.
USER FIELD B
(PCICNT)
represents a user-defined field used to accumulate the count of recursive errors. It should be in the process control information (PCI) area of the TCTTE.
SYSTEM COUNT
(TCTTENI)
represents the 6-byte field in the TCTTE that contains the terminal input and output counts (TCTTENI+TCTTENO). In the example, these two adjacent fields are considered as one 6-byte field.

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.

DFHTEP recursive retry routine

Figure 23. DFHTEP recursive retry routine
*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.

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