Exploring CICS Sequential Terminal Processing

For many years, IBM has allowed CICS customers to execute transactions during start-up using a facility called sequential terminal processing.  According to IBM documentation,

The original purpose of sequential terminal support was to permit application developers to test online code before they had access to real terminals. This requirement rarely occurs any more, but sequential terminals are still useful for:
  • Printing –  Sequential terminals are particularly useful for output that is sometimes directed to a low-speed CICS printer, for which BMS or terminal control commands are required, and sometimes directed to a high-speed system printer.  If you define the high-speed printer as a sequential terminal, you can use terminal control or BMS commands, and you can use the same code for both types of printers. 
  • Regression testing – Tests run from sequential terminals leave a permanent record of both input and output. This encourages systematic and verifiable initial testing. Also, it allows you to repeat tests after modifications, to ensure that a given set of inputs produces the same set of outputs after the change as before.
  • Initialization –  Some installations use a sequential terminal to execute one or more initialization transactions, in preference to program list table programs. Transactions initiated from a sequential terminal begin execution as soon as the terminal is in service, and they continue as quickly as CICS can process them until the input is exhausted. Hence the inputs from a sequential terminal can be processed immediately after startup, if the sequential terminal is initially in service, at some later time  or even as part of a controlled shutdown.
In the case of HostBridge, sequential terminal processing is used to run transactions that perform initialization functions for BPIC (Batch Programs In CICS).   This post describes how to configure sequential terminals for a region and use it to perform transactions at startup time.
The process consists of the following steps:
1. Define the input and output sequential terminals using terminal control table (TCT) entries.
2. Create the input file used when invoking the sequential terminal facility.
3. Modify the system initialization table (SIT) for your region.
4. Modify your CICS startup JCL to contain the files used for sequential terminal processing.
Following are the details for each of the above steps.

Define the input and output sequential terminals using TCT entries

The sequential terminal facility uses two TYPE=SDSCI terminal definitions (CARDIN and PRINTER).  These are required to be defined using TCT entries (not by RDO).  Here is a sample:

         DFHTCT TYPE=INITIAL,SUFFIX=SQ,ACCMETH=(VTAM,NONVTAM)
*
         DFHTCT TYPE=SDSCI,                                            X
               DEVICE=2540, X
               DSCNAME=CARDIN
*
         DFHTCT TYPE=SDSCI,                                            X
               DEVICE=1403,                                            X
               DSCNAME=PRINTER
*
         DFHTCT TYPE=LINE,                                             X
               ACCMETH=BSAM,                                           X
               TRMTYPE=CRLP,                                           X
               INAREAL=80,                                             X
               ISADSCN=CARDIN,                                         X
               OSADSCN=PRINTER
*
         DFHTCT TYPE=TERMINAL,                                         X
               TRMIDNT=SAMA,                                           X
               LPLEN=80,                                               X
               TRMSTAT=TRANSACTION 
         DFHTCT TYPE=FINAL
         END

The CARDIN DD is where the transactions to be executed are taken from.  The PRINTER DD is where output that would normally be sent to a terminal is written to.

You should then assemble the TCT into whatever load library you keep other CICS assembled table definitions (such as PLT initialization and shutdown routines).  The load module name should be DFHTCTxx, where xx is the same as the value of SUFFIX in the TCT definition.  Here is some sample JCL to do the assembly:

//YOURJOB  JOB 
//* PLT TCT ASSEMBLY FOR SEQUENTIAL TERMINALS
//* MODULE NAME SHOULD BE DFHTCTxx, WHERE xx is SUFFIX= value in TCT
//ASSEMBLY EXEC PGM=ASMA90,
//             REGION=1024K,
//             PARM='DECK,NOOBJECT,LIST,XREF(FULL),SYSPARM(MAP)'
//SYSLIB   DD  DSN=DFH520.CICS.SDFHMAC,DISP=SHR
//         DD  DSN=SYS1.MODGEN,DISP=SHR
//         DD  DSN=SYS1.MACLIB,DISP=SHR
//         DD  DSN=SYS1.AMACLIB,DISP=SHR
//         DD  DSN=CEE.SCEESAMP,DISP=SHR
//         DD  DSN=CEE.SCEEMAC,DISP=SHR
//SYSUT1   DD  UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSUT2   DD  UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSUT3   DD  UNIT=SYSDA,SPACE=(1700,(400,400))
//SYSPUNCH DD  DSN=YOUR.TEST.OBJLIB(DFHTCTSQ),DISP=OLD
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  *
-- insert TCT definition cards from sample above -- 
/*
//LKED     EXEC PGM=IEWL,
//             PARM=(LET,LIST,MAP,XREF,'AMODE=24','RMODE=24'),
//             COND=(4,LT,ASSEMBLY)
//SYSPRINT DD  SYSOUT=*
//SYSLMOD  DD  DSN=YOUR.CICS.TABLES.LOADLIB,DISP=SHR
//SYSLIB   DD  DSN=DFH520.CICS.SDFHLOAD,DISP=SHR
//CICLIB   DD  DSN=YOUR.TEST.OBJLIB,DISP=SHR
//SYSUT1   DD  UNIT=SYSDA,SPACE=(CYL,(3,1))
//SYSLIN   DD  *
 INCLUDE CICLIB(DFHTCTSQ)
 NAME DFHTCTSQ(R)
/*
//

Creating the sequential terminal input file

The sequential terminal input file must be defined as a 80 column fixed, unblocked file.  It consists of a series of transaction invocations:
HBZT START,SUBR\
CESF GOODNIGHT\
Each transaction must be specified exactly as it would be typed in at a terminal and must end with an end-of-data character (in this case, the default of x’E0′, or backslash; this can be changed using the SIT EODI parameter, but normally the default is taken).  The maximum length of a transaction invocation is equal to the INAREAL value in the TCT; anything longer then that causes an abend.
There are some special rules concerning what happens at the end of sequential terminal processing.  End-of-file does not terminate sequential input.  You can use CESF GOODNIGHT as the last transaction to close the device and stop reading from the device.  Otherwise, CICS invokes the terminal error program (DFHTEP), and issues the following warning messages at end-of-file on the sequential device:
DFHTC2507 … Input event rejected return code zz {on line w/term|at term}termid {, trans}tranid{, rel line=} rr,time
DFHTC2500 … {Line|CU|Terminal} out of service {Term|W/Term} termid
Using CESF GOODNIGHT puts the sequential device into RECEIVE status and terminates reading from the device. However, if you close an input device in this way, the receive-only status is recorded in the warm keypoint at CICS shutdown. This means that the terminal is still in RECEIVE status in a subsequent warm start, and CICS does not then read the input file.
You can also use CESF LOGOFF to close the device and terminate reading from the device, but CICS still invokes DFHTEP to issue messages DFHTC2507 and DFHTC2500 at end-of-file. However, the device remains in TTI status, and is available for use when restarting CICS in a warm start.
If you want CICS to read from a sequential input data set, either during or following a warm start, you can choose one of the following methods:
  • Close the input with CESF LOGOFF, and ignore the resultant messages. This leaves the terminal in TTI state, and CICS reads input automatically in the next startup.
  • Do not close the input, and ignore the resultant messages. This leaves the terminal in TRANSCEIVE state, and CICS reads input automatically in the next startup.
  • Close the input with CESF GOODNIGHT. This puts the sequential terminal into RECEIVE status and terminates reading from the terminal. In this case, it is recommended that you code a PLT program to change the status of the terminal to TRANSCEIVE.

Modifying the SIT

You will need to include a TCT=xx (where xx is the suffix of the TCT you created; SQ in our example) in your SIT or SIT overrides:
–snip–
STATRCD=OFF
SYSIDNT=CICA
TCPIP=YES
*TCT=NO changed to TCT=SQ to support sequential terminals
TCT=SQ
TRTABSZ=64
USSHOME=/usr/lpp/cicsts/cicsts52
XAPPC=NO
XCMD=NO
–snip–

Modifying the CICS Startup JCL

You will need to make the following changes to your CICS startup JCL:
  • If you are using the CESF GOODNIGHT command to terminate sequential terminal processing, you will need to specify START=INITIAL in your SIT PARM overrides.
  • You need to make sure that the library containing the TCT is available in your DFHRPL concatenation.
  • You will need to include the CARDIN and PRINTER DD statements in your startup JCL.  A recommended technique for ensuring that  the input is in 80-byte fixed unblocked format is to insert an IEBGENER step before the actual DFHSIP execution, copying your input transaction records to a temporary sequential file which is then read at startup.  This way, input can be provided from multiple sources.  Following are samples of the CARDIN and PRINTER DD statements and the IEBGENER step within a typical CICS startup PROC:
//CICSTS52 PROC START='INITIAL',
// INDEX1='DFH520',
// INDEX2='DFH520.CICS',
// INDEX3='DFH520.CPSM',
// REGNAM='A',
// REG='0M', 
// DUMPTR='YES',
// RUNCICS='YES',
// OUTC='*'
//*SIP=1
//*
//* INDEX1 - HIGH-LEVEL QUALIFIER(S) OF CICS RUN TIME DATASETS
//* INDEX2 - HIGH-LEVEL QUALIFIER(S) OF CICS LOAD LIBRARIES
//* REGNAM - REGION NAME FOR SINGLE OR MRO REGION
//* REG - MVS REGION STORAGE REQUIRED
//* START - TYPE OF CICS START-UP REQUIRED
//* DUMPTR - DUMP/TRACE ANALYSIS REQUIRED, YES OR NO
//* RUNCICS - CICS STARTUP REQUIRED, YES OR NO
//* OUTC - PRINT OUTPUT CLASS
//* SIP - SUFFIX OF DFH$SIP MEMBER IN THE SYSIN DATASET
//*
//* SET THE RETURN CODE TO CONTROL IF CICS SHOULD BE
//* STARTED OR NOT
//CICSCNTL EXEC PGM=IDCAMS,REGION=1M
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  DISP=SHR,
// DSN=&INDEX1..SYSIN(DFHRC&RUNCICS)
//*
//* SET THE RETURN CODE TO CONTROL THE DUMP AND TRACE
//* ANALYSIS STEPS
//DTCNTL   EXEC PGM=IDCAMS,REGION=1M
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  DISP=SHR,
// DSN=&INDEX1..SYSIN(DFHRC&DUMPTR)
//*
//SEQTERM  EXEC PGM=IEBGENER 
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  DUMMY
//SYSUT1   DD  DISP=SHR,DSN=YOUR.SEQ.TRANS
//SYSUT2   DD  DSN=&&CARDIN,DISP=(NEW,PASS),
// UNIT=SYSDA,SPACE=(TRK,(5,1),RLSE),
// DCB=(RECFM=F,LRECL=80,BLKSIZE=80)
//*
//***********************************************************
//******************* EXECUTE CICS ************************
//***********************************************************
//CICS     EXEC PGM=DFHSIP,REGION=&REG,TIME=1440,
// COND=(1,NE,CICSCNTL),
// PARM='START=&START,SYSIN'
//*
//* THE CAVM DATASETS - XRF
//*
//* THE "FILEA" APPLICATIONS SAMPLE VSAM FILE
//* (THE FILEA DD STATEMENT BELOW WILL
//* OVERRIDE THE CSD DEFINITION IN GROUP DFHMROFD)
//FILEA    DD  DISP=SHR,
// DSN=&INDEX1..CICS&REGNAM..FILEA
//*
//SYSIN    DD  DISP=SHR,
// DSN=SHARED.SYSIN(CICS&REGNAM)
//DFHCMACD DD  DSN=DFH520.DFHCMACD,DISP=SHR
//***********************************************************
//* THE CICS STEPLIB CONCATENATION
//***********************************************************
//STEPLIB  DD  DISP=SHR,DSN=&INDEX2..SDFHAUTH
//         DD  DISP=SHR,DSN=&INDEX2..SDFJAUTH
//         DD  DISP=SHR,DSN=&INDEX3..SEYUAUTH
//         DD  DISP=SHR,DSN=CEE.SCEERUN2
//         DD  DISP=SHR,DSN=CEE.SCEERUN
//         DD  DISP=SHR,DSN=DSNB10.SDSNLOAD
//         DD  DISP=SHR,DSN=DFH520.CICS.SDFHLINK
//         DD  DISP=SHR,DSN=DFH520.SDFHLIC
//         DD  DISP=SHR,DSN=YOUR.APF.AUTH.LIBRARY
//***********************************************************
//* THE CICS LIBRARY (DFHRPL) CONCATENATION
//***********************************************************
//DFHRPL   DD  DISP=SHR,DSN=&INDEX2..SDFHLOAD
//         DD  DISP=SHR,DSN=&INDEX3..SEYULOAD
//         DD  DISP=SHR,DSN=CEE.SCEECICS
//         DD  DISP=SHR,DSN=CEE.SCEERUN2
//         DD  DISP=SHR,DSN=CEE.SCEERUN
//         DD  DISP=SHR,DSN=YOUR.TCT.LIBRARY
//         DD  DISP=SHR,DSN=YOUR.APPL.LIBRARY
//*
//* SEQUENTIAL TERMINAL SUPPORT
//*
//CARDIN   DD  DISP=(OLD,DELETE),DSN=&&CARDIN
//PRINTER  DD  SYSOUT=*,DCB=(LRECL=125,RECFM=F)
//*
//* THE AUXILIARY TEMPORARY STORAGE DATASET
//*
//DFHTEMP  DD  DISP=SHR,
// DSN=&INDEX1..CNTL.CICS&REGNAM..DFHTEMP
//*
//* THE INTRAPARTITION DATASET
//*
//DFHINTRA DD  DISP=SHR,
// DSN=&INDEX1..CNTL.CICS&REGNAM..DFHINTRA
//*
//* THE AUXILIARY TRACE DATASETS
//*
//DFHAUXT  DD  DISP=SHR,DCB=BUFNO=5,
// DSN=&INDEX1..CICS&REGNAM..DFHAUXT
//DFHBUXT  DD  DISP=SHR,DCB=BUFNO=5,
// DSN=&INDEX1..CICS&REGNAM..DFHBUXT
//*
//* THE CICS LOCAL CATALOG DATASET
//*
//DFHLCD   DD  DISP=SHR,
// DSN=&INDEX1..CICS&REGNAM..DFHLCD
//*
//* THE CICS GLOBAL CATALOG DATASET
//*
//DFHGCD   DD  DISP=SHR,
// DSN=&INDEX1..CICS&REGNAM..DFHGCD
//*
//* THE CICS LOCAL REQUEST QUEUE DATASET
//*
//DFHLRQ   DD  DISP=SHR,
// DSN=&INDEX1..CICS&REGNAM..DFHLRQ
//*
//* EXTRAPARTITION DATASETS
//*
//DFHCXRF  DD  SYSOUT=&OUTC
//LOGUSR   DD  SYSOUT=&OUTC,DCB=(DSORG=PS,RECFM=V,BLKSIZE=136)
//MSGUSR   DD  SYSOUT=&OUTC,DCB=(DSORG=PS,RECFM=V,BLKSIZE=140)
//CEEMSG   DD  SYSOUT=&OUTC
//CEEOUT   DD  SYSOUT=&OUTC
//LOGFILE  DD  SYSOUT=&OUTC
//*
//* THE DUMP DATASETS
//*
//DFHDMPA  DD  DISP=SHR,
// DSN=&INDEX1..CICS&REGNAM..DFHDMPA
//DFHDMPB  DD  DISP=SHR,
// DSN=&INDEX1..CICS&REGNAM..DFHDMPB
//SYSABEND DD  SYSOUT=&OUTC
//SYSUDUMP DD  SYSOUT=&OUTC
//SYSPRINT DD  SYSOUT=&OUTC
//CSQSNAP  DD  SYSOUT=&OUTC,DCB=BLKSIZE=121
//*
//* THE CICS SYSTEM DEFINITION DATASET
//*
//DFHCSD   DD  DISP=SHR,
// DSN=SHARED.TS52.DFHCSD
//

Summary and Conclusion

Sequential terminal processing, when used correctly, can be a very handy way of executing initialization requests or running certain types of tests within a CICS region.

Further information about sequential terminal processing can be found the IBM Manual CICS/TSxx Resource Definition Guide in the chapter ‘Defining Terminal Resources’ and section ‘ Defining Sequential (BSAM) Devices’.  You can also review information for the EODI and TCT SIT parameters in the CICS/TSxx System Definition Guide.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s