Generate MQ, CICS related reports using CA Explore Report writer

 We can use CA Explore Report writer to generate Various sub system reports such as CICS, MQ, MVS, IMS etc from Sysview Log streams.

The below sample job gerenates "MQ OBJECT STATISTICS" from Sysview MQ log stream

//***************************************************************       

//* You can use logstreams as input:                            *       

//*                                                             *       

//* SET SMFIN='sysview.AUDIT.ADTT'                              *       

//* SET SMFIN='sysview.CICSLOGR.TRAN'                           *       

//* SET SMFIN='sysview.CICSLOGR.TSUM'                           *       

//* SET SMFIN='sysview.CICSLOGR.SYSD'                           *       

//* SET SMFIN='sysview.CICSLOGR.XLOG'                           *       

//* SET SMFIN='sysview.IMSLOGR.IMTR'                            *       

//* SET SMFIN='sysview.IMSLOGR.IMRS'                            *       

//* SET SMFIN='sysview.MQSDATA.MQHR'                            *       

//* SET SMFIN='sysview.SMFDATA.SMFD'                            *       

//* SET SMFIN='sysview.SYSDATA.XLOG'                            *       

//*                                                             *       

//* Type LGLOGS command in SYSVIEW to find out names of the     *       

//* logstreams.                                                 *       

//*                                                             *       

//***************************************************************       

//* Type Sysview high level qualifier below.                    *       

//***************************************************************       

// SET SMFIN='XXX0150.MQSDATA.MQHR'          

// SET SYSVIEW='CA.SYSVIEW.R17'                                        

//*                                                                     

//REPORT   EXEC PGM=XPFRMAIN,REGION=4M                                  

//STEPLIB  DD DISP=SHR,DSN=&SYSVIEW..CNM4BLOD                           

//ERPTPRM  DD DISP=SHR,DSN=&SYSVIEW..CNM4RSAM                           

//SYSUDUMP DD SYSOUT=*                                                  

//SYSPRINT DD DSN=USERID.MQ.SYSVIEW.TEST,                              

//            DISP=(NEW,CATLG,DELETE),                                  

//            SPACE=(CYL,(50,50)),                                      

//            DCB=(RECFM=FB,LRECL=1024)                                 

//TAPSMF   DD DISP=SHR,DSN=&SMFIN,                              *       

//            SUBSYS=(LOGR,GSVXLGEX,                            *       

//            'FROM=OLDEST,TO=YOUNGEST,LOCAL',                  *       

//            'STATS,EXPAND,BACKWARD,NORDW'),                   *       

//            DCB=(DSORG=PS,RECFM=VB,LRECL=32756,BLKSIZE=32760) *       

//*                                                             *       

//SYSIN    DD DISP=SHR,DSN=&SYSVIEW..CNM4RSAM(MQ001)               

//*                                                                

//***************************************************************  

//* Use this utility to transform created report to CSV format. *  

//*                                                             *  

//* Optional parameters: (one character long only)              *  

//*  - VS - Value Separator (default is ,)                      *  

//*  - DS - Decimal Separator (default is .)                    *  

//*                                                             *  

//***************************************************************  

//*                                                                

//PARSE    EXEC PGM=IKJEFT01                                       

//SYSEXEC  DD DISP=SHR,DSN=&SYSVIEW..CNM4RSAM                      

//SYSTSPRT DD SYSOUT=*                                             

//RWO      DD SYSOUT=*,DCB=(RECFM=FB,LRECL=1024)                   

//CSVIN    DD DSN=USERID.MQ.SYSVIEW.TEST,DISP=SHR                 

//CSVOUT   DD DSN=USERID.MQ.SYSVIEW.TEST.CSV,  

//            DISP=(NEW,CATLG,DELETE),          

//            SPACE=(CYL,(50,50)),              

//            DCB=(RECFM=FB,LRECL=1024)         

//SYSTSIN  DD *                                 

  CSVGEN CSVIN CSVOUT VS=; DS=,                 

/*                                              

The sample control cards to generate various reports can be found at 

sysview.CNM4RSAM($$INDEX) library

The below job generates last 1 hour "CICS Transaction Detail Report" from Sysview CICS logstream  

// SET SMFIN='XXXX150.CICSLOGR.TRAN'      

// SET SYSVIEW='CA.SYSVIEW.R17'                                    

//*                                                                 

//REPORT   EXEC PGM=XPFRMAIN,REGION=4M                              

//STEPLIB  DD DISP=SHR,DSN=&SYSVIEW..CNM4BLOD                       

//ERPTPRM  DD DISP=SHR,DSN=&SYSVIEW..CNM4RSAM                       

//SYSUDUMP DD SYSOUT=*                                              

//*YSPRINT DD SYSOUT=*                                              

//SYSPRINT DD DSN=USERID.CICS.SYSVIEW.TEST,                        

//            DISP=(NEW,CATLG,DELETE),                              

//            SPACE=(CYL,(50,50)),                                  

//            DCB=(RECFM=FB,LRECL=1024)                             

//TAPSMF   DD DISP=SHR,DSN=&SMFIN,                              *   

//            SUBSYS=(LOGR,GSVXLGEX,'LOCAL,DURATION=(1,HOURS)'),    

//            DCB=BLKSIZE=32760                                     

//SYSIN    DD DISP=SHR,DSN=&SYSVIEW..CNM4RSAM(CICS031)   

//PARSE    EXEC PGM=IKJEFT01                          

//SYSEXEC  DD DISP=SHR,DSN=&SYSVIEW..CNM4RSAM         

//SYSTSPRT DD SYSOUT=*                                

//RWO      DD SYSOUT=*,DCB=(RECFM=FB,LRECL=1024)      

//CSVIN    DD DSN=USERID.CICS.SYSVIEW.TEST,DISP=SHR  

//CSVOUT   DD DSN=USERID.CICS.SYSVIEW.TEST.CSV,      

//            DISP=(NEW,CATLG,DELETE),                

//            SPACE=(CYL,(50,50)),                    

//            DCB=(RECFM=FB,LRECL=1024)               

//SYSTSIN  DD *                                       

  CSVGEN CSVIN CSVOUT VS=; DS=,                       

/*                                                    

Documentation for Sample reports can be found at https://techdocs.broadcom.com/us/en/ca-mainframe-software/performance-and-storage/ca-sysview-performance-management/17-0/reporting/using-ca-explore-report-writer/sample-reports/cics-sample-reports.html

Why/When AICA abend happens in CICS region

Following content is copied from https://planetmainframe.com/2023/08/cics-programming-best-practices/

The option ICVR (Interval Control Value Runaway) is the amount of Task time that a task can consume between Calls to CICS. You see CICS is a very friendly system; it just says that you can freely use my services, you just have to talk to me once in a while. However, if you don’t talk to me, then I’m going to assume that you are looping and abend you. How does it do this? When you issue an EXEC CICS command and CICS processes your request, then control returns to your program. CICS then starts a Clock and decrements it while you have the CPU processing your COBOL/Assembler statements. If the Clock falls to zero, CICS, by Interval Control, will abend your task AICA.  Actually, it’s quite clever; it abends the Task with an S0C1 (Operation Exception). ICVR controls this Clock and it’s specified in the Overrides and changeable online by a CEMT SET SYSTEM command. 2000 milliseconds (2 seconds) is the default. This is a system-wide value but can be specified differently for each transaction. 

CICS File Openstatus Enablestatus

 In CICS, the open status of a VSAM file can either be OPEN or CLOSED, and this is indicated by the OPENSTATUS attribute in the file entry in the CICS file control table. If CICS closes a file, it is also de-allocated so that it can be processed by batch jobs. A file also has an enabled status, indicated by the ENABLESTATUS attribute, which can be either ENABLED, DISABLED, or UNENABLED. The enabled status determines whether or not a CICS application program request to a VSAM file can be attempted. If a file is disabled or unenabled, CICS fails the application program request without even attempting to send the request to VSAM. If the file is enabled, CICS issues the VSAM request on behalf of the application program.

The following are the most common combinations of these two states:

OPEN, ENABLED

CLOSED, ENABLED

OPEN, DISABLED

CLOSED, DISABLED

CLOSED, UNENABLED

In the first case (OPEN, ENABLED), the file is open and available to CICS application programs and if a batch job tries to access the file, it generally fails.

In the second case (CLOSED, ENABLED), the file is closed and not allocated, but it is available to CICS programs. In this state, if your application program issues a file access request, CICS attempts to allocate then open the file. If CICS cannot allocate and open the file, it is most probably because it is allocated to a batch job, and the application program request fails. Also in this case, as long as the file is closed, it is available for access by batch jobs.

In the last three cases in the above list (OPEN, DISABLED; CLOSED, DISABLED; and CLOSED, UNENABLED), CICS fails all file control requests without even attempting them because the file is not enabled. The key difference in these three cases is that in one the file is open and in the other two it is closed. In the open case, it is allocated to CICS so that batch jobs that attempt to access the file will probably fail. In the closed cases , it is not allocated to CICS, and is available for access by batch jobs.

Note that when a file is closed to CICS, and therefore de-allocated, the file can even be deleted by a batch job.

For the most part, the DISABLED and UNENABLED states are the same. Both states prevent an application program from accessing the file. However, there is one important difference that you must take into consideration when changing the state of a file.

The only way that a file becomes unenabled is when you close the file without altering its enabled status. You can do this using the CICS BAC batch request utility, or by using the EXEC CICS SET FILE command or the CEMT SET FILE transaction. For example, if FILEA is currently open and enabled, and you issue the CEMT command SET FILE(FILEA) CLOSED, the resulting file attributes are set to CLOSED and UNENABLED. However, if the file is currently open and disabled, the same command results in the file state being set to CLOSED and DISABLED.

The difference between a disabled and an unenabled file is in how the file state is set when a closed file is subsequently opened. If a file is currently closed and disabled, and a request is made through the CICS BAC batch request utility, CICS system programming interface (SPI), or CICS CEMT command to open the file without altering its enable status attribute, the file is opened (assuming there is nothing to keep it from being opened), but its enable status remains DISABLED. On the other hand, if a file is unenabled, an open request that does not also specify an enabled status results in the file state being set to OPEN and ENABLED.

If you issue a request that alters the enable status of a file explicitly, the file ENABLESTATUS attribute is changed regardless of whether the current state is ENABLED, DISABLED, or UNENABLED.

How to extract CICS transaction log from CA Sysview

The Below JCL would pull the latest 500 transactions from CA sysview for CICS and put in MYID.PRN(M1). You need to allocate the MYID.PRN PDS before running this job 

//STEP1 EXEC PGM=GSVXBAT,PARM='LINECNT=66,SHOWINP=NO'          

//SYSPRINT DD SYSOUT=*,DCB=(LRECL=81,BLKSIZE=8100,RECFM=FBA)   

//SYSOUT   DD SYSOUT=*,DCB=(LRECL=81,BLKSIZE=8100,RECFM=FBA)   

//SYSIN DD *                                                   

COMMAND=(SET COPYDSNAME 'MYID.PRN')                         

COMMAND=(PRINT OPEN M1)                                        

COMMAND=(CTRANLOG LINES  500 LIMIT  500)                       

COMMAND=(PRINT ALL)                                            

COMMAND=(PRINT CLOSE)                                          

//*                                                            

CICS BMS MAP LOW-VALUES

Input Mapping

When BMS makes the map available to your program on a RECEIVE MAP operation it
places data in three areas for each input field. These three areas are the length
field, the flag/attribute byte and the data field.

There are several situations at execution time for which BMS allows. In the
physical map, a length for the field is specified. If more data is keyed in than
is specified in this length, the data is truncated on the right and the length
field is set to the truncated length. If less data is keyed in than the length
specified, the length field is set to the number of characters entered and the
data field is padded on the right with blanks or on the left with zeros
(depending on whether the field is alpha or numeric). However, if any data was
previously in the field and the keyed data failed to cover up the old data, the
entire field would be returned with a length representing the original field
length.

There is an exception to the right-justify, zero-fill feature for a numeric item.
If the numeric field is initialized with other characters previous to the data
you entered, your data may not come in right-justified and zero-filled.

The flag byte is almost always initialized to X'00' when the map comes to you.
The length field is usually used to tell whether or not any data has been
entered. Data has been entered in the field when the length field is not equal
low-values (nulls). However, a special situation occurs when a field is modified
but no data is sent (as when a field is modified to low values with the erase to
end-of-file key). The length field would show as zero and there would be no data
in the data field. To be able to tell when this has happened, the flag byte is
set to X'80' and the length area is set to zeros. Therefore, if the flag byte is
set to X'80', the user has cleared the field. The length and data areas of any
fields that are defined but not modified are set to low values (X'00').

Output Mapping

Do not re-use symbolic mapping areas under BMS unless they are cleared to low
values. BMS relies on x'00' in the first byte of a field to construct
an accurate output data stream.

To place data in the output map, move it to the output data field. Be careful,
however, not to let any low-value (X'00') characters begin your field or BMS will
ignore that field. If a field begins with low values, the data in the field is
not returned to the program.

It is also possible to change the attribute of the output field. This can be done
when the input and output portions of the map redefine each other. In that case,
you have to move the desired attribute byte into the input map's attribute byte
and your attribute will override what was originally specified. However, when the
map is received, that byte is reset.

You may code your own attribute constants to supplement the attributes supplied
by IBM. Sample explanation for some of the attributes followed by the COBOL
statements defining some additional attributes are shown as follows:

'I': Moving 'I' to the attribute byte for an alphanumeric field in error will
make this field high intensity, unprotected and MDT on.

'R': Moving 'R' to the attribute byte for a numeric field in error will make this
field high intensity, unprotected, numeric lock on and MDT on.

'4': Moving '4' to the attribute byte for a edited field that has passed the
edits will protect this field.

NOTE: If an attribute is needed for the FSET, BRT combination, define the
following in WORKING-STORAGE:

01  FSET-BRT            PIC X VALUE 'I'.

Using the map fields defined under the "Input Mapping" topic, the move statement
to set this attribute would be coded:

MOVE  FSET-BRT TO INFLDA.

MAPFAIL

There is an important situation that occurs under BMS called "MAPFAIL". This
occurs when a RECEIVE MAP command is issued but no data was returned to the
program. One common way this would happen is when no field is modified on a map.
When no field is modified, the length, flag and data fields are not changed or
updated in any way. You must know if data is returned or entered before you start
your edit checking.

One technique that is used to avoid the MAPFAIL condition is the code
in the mapset a one-byte dummy "autoskip" field with FSET specified so at least
one byte of date is sent to the program when the map is returned.

You can test EIBAID to ensure that data was entered via the ENTER key (or other
planned key) by checking for which AID key was pressed. The clear or PA key will
look like data entry, but no data is returned. See the "Input Mapping" topic for
more information about receiving a map with no data. There is a MAPFAIL
exceptional condition that is handled by the HANDLE CONDITION command in command-
level programming.

In command-level programming, if the HANDLE AID command is specified, it could
override the MAPFAIL handle condition specified. This could mean that the handle
aid would take precedence over the handle condition. The RESP and RESP2 options
may also be used to test for exceptional conditions. Since the use of RESP
implies NOHANDLE, you must be careful when using it with the RECEIVE command,
because NOHANDLE overrides the HANDLE AID command as well as the HANDLE CONDITION
command. The result is that PF key responses are ignored.

CICS : How TDQ Automatic transaction initiation works

Below content was taken from IBM manual

For intrapartition queues, CICS® provides the option of automatic transaction initiation (ATI). A basis for ATI is established by the system programmer by specifying a nonzero trigger level for a particular intrapartition destination.

When the number of entries (created by WRITEQ TD commands issued by one or more programs) in the queue reaches the specified trigger level, a transaction specified in the definition of the queue is automatically initiated. Control is passed to a program that processes the data in the queue; the program must issue repetitive READQ TD commands to deplete the queue.

When the queue has been emptied, a new ATI cycle begins. That is, a new task is scheduled for initiation when the specified trigger level is again reached, whether execution of the earlier task has ended. The exact point at which a new ATI cycle begins depends on whether the queue is defined as logically recoverable. If the queue is defined with a recoverability attribute (RECOVSTATUS) of No or Physical, the new ATI cycle begins when the queue is read to QZERO. But if the queue is defined with a recoverability attribute of Logical, the new ATI cycle begins only after the task terminates after having read the queue to QZERO.

If an automatically initiated task does not empty the queue, access to the queue is not inhibited. The task can be normally or abnormally ended before the queue is emptied (that is, before a QZERO condition occurs in response to a READQ TD command). If the contents of the queue are to be sent to a terminal, and the previous task completed normally, the fact that QZERO has not been reached means that trigger processing has not been reset and the same task is reinitiated. A subsequent WRITEQ TD command does not trigger a new task if trigger processing has not been reset.

If the contents of the queue are to be sent to a file, the termination of the task has the same effect as QZERO (that is, trigger processing is reset). The next WRITEQ TD command initiates the trigger transaction (if the trigger level has been reached).

If the trigger level of a queue is zero, no task is automatically initiated.

If a queue is logically recoverable, initiation of the trigger transaction is deferred until the next sync point.

If the trigger level has already been exceeded because the last triggered transaction abended before clearing the queue, or because the transaction was never started because the MXT limit was reached, another task is not scheduled. This is because QZERO has not been raised to reset trigger processing. If the contents of a queue are destined for a file, the termination of the task resets trigger processing and means that the next WRITEQ TD command triggers a new task.

To ensure that an automatically initiated task completes when the queue is empty, the application program should test for a QZERO condition in preference to some other application-dependent factor (such as an anticipated number of records). Only the QZERO condition indicates an emptied queue.

If the contents of a queue are to be sent to another system, the session name is held in EIBTRMID. If a transaction (started with a destination of system) abends, a new transaction is started in the same way as a terminal.

If you use ATI with a transient data trigger mechanism, it might create inter-transaction affinities that adversely affect your ability to perform dynamic transaction routing. See Affinity for more information about transaction affinity.

A trigger transaction is shunted if it suffers from an indoubt failure. Another trigger transaction is not attached until the shunted UOW commits or backs out the changes it has made following resynchronization.

Transactions that are initiated because of a transient data trigger-level transaction do not create previous hop data and are treated as executing at a point of origin. For more information about previous hop data, see Previous hop data characteristics.

CICS TSQ Handling

Normally, temporary storage control maintains TSQ’s in single VSAM ESDS called temporary storage file or DFHTEMP. For pseudo conversational programs, that’s an efficient way to store data between program executions. The one big advantage the TSQ’s have over communication area is that it makes better use of the systems resources by not tying up the main memory for long periods of time.

One can also store the TSQ’s on disks as Temporary Storage Control allows that but that means overheads in storing and retrieving the data in a single task execution. But if we specify main storage over disk, the processing is faster at the cost of critical main memory in the CICS system.

1. Write to a TSQ (creates the Q if not present already)

            EXEC CICS

                        WRITEQ TS QUEUE(TS-QUEUE-NAME)

                                             FROM(TS-QUEUE-RECORD)

                                             LENGTH(TS-QUEUE-LENGTH)

                                            [ MAIN ]

                                            [ AUXIALLIARY ]

            END-EXEC.

           

TS-QUEUE-LENGTH : PIC S9(4) COMP FIELD (Half-Word binary).

TS-QUEUE-NAME     : 1 TO 8 CHARACTER name that should be unique to avoid using other TSQ’s.

MAIN/AUXIALLIARY  : Specifies that TSQ shall reside on main/disk storage. OPTIONAL FIELDS.

2. Update an existing record.

           

            EXEC CICS

                        WRITEQ TS QUEUE(TS-QUEUE-NAME)

                                             FROM(TS-QUEUE-RECORD)

                                             LENGTH(TS-QUEUE-LENGTH)

                                             ITEM(TS-ITEM-NUMBER)

                                             REWRITE

                                             RESP(RESPONSE-CODE)

            END-EXEC.

Within a TSQ, each record is assigned an ITEM-NUMBER just like an array-index. The item #s start from 1,2,…..To rewrite a record in the TSQ you need to specify the item number of the record to be updated. Since most TSQ’s have one record only that is updated, its never a problem. In case a TSQ name is not found it raises a QIDERR. In case it doesn’t find the item-number, then an ITEMERR is raised.

3. To read from a TSQ :

            EXEC CICS

                        READQ TS QUEUE(TS-QUEUE-NAME)

                                          INTO(TS-QUEUE-RECORD)

                                          LENGTH(TS-QUEUE-LENGTH)

                                          ITEM(TS-ITEM-NUMBER)

                                          RESP(RESPONSE-CODE)

                                          [  NEXT ]               

            END-EXEC.

NEXT : Specifies that the next record in the sequence following the most recently read record should be read. OPTIONAL         

            parameter. Its always a good practice to use the item #.

            In case of a readq also, the possible exceptions are QIDERR and ITEMERR. The response code can be used to handle an abnormal termination as in any CICS program.

4. Deleting a TSQ :

           

            EXEC CICS

DELETEQ TS QUEUE(TS-QUEUE-NAME)

            END-EXEC.     

            this command needs to be issued explicitly after the completion of processing to delete the TSQ. If we do not, then the TSQ remains indefinitely wasting storage space. The command deletes the entire TSQ and not just the record. That shouldn’t be problem either coz most of the times the TSQ is going to have a single entry.         

All the variables used will be defined in the working storage before you can use these lines of code in your program. Something like……

WORKING-STORAGE DIVISION.

           

            01  TSQ-AREA.

                       

                  05  TS-QUEUE-RECORD           PIC X(100).

                  05  TS-QUEUE-NAME                PIC X(8).

                  05  TS-QUEUE-LENGTH            PIC S9(4) COMP.

                  05  TS-ITEM-NUMBER                PIC 9(02).  

             ……………………………….

PROCEDURE DIVISION.

………………

2000-PROCESS SECTION.

            ……………..

MOVE “NIL001” TO TS-QUEUE-NAME.

            MOVE WS-Q-RECORD TO TS-QUEUE-RECORD.

            MOVE 100 TO TS-QUEUE-LENGTH.

             …………………..

            EXEC CICS WRITEQ TS QUEUE(TS-QUEUE-NAME

                               FROM(TS-QUEUE-RECORD)

                               LENGTH(TS-QUEUE-LENGTH)

            END-EXEC.     

……………………………

CICS: What is the difference between transaction and task ?

   A transaction is a piece of processing initiated by a single request,
   usually from an end user at a terminal.  A single transaction will consist
   of one or more application programs that, when run, will carry out the
   processing needed.

   In other words, "transaction" means in CICS what it does in everyday
   English:  a single event or item of business between two parties.  In
   batch processing, transactions of one type are grouped together and
   processed in a batch (all the updates to the personnel file in one job, a
   list of all the overdue accounts in another, and so on).  In an online
   system, by contrast, transactions aren't sorted by type, but instead are
   done individually as they arrive (an update to a personnel record here, a
   customer order entered there, a billing inquiry next, and so on).

   Having given you this straightforward definition, we'll immediately
   complicate things a bit by admitting that the word "transaction" is used
   to mean both a single event (as we just described) and a class of similar
   events.  Thus, we speak of adding Mary Smith to the Payroll File with a
   (single) "add" transaction, but we also speak of the "add" transaction,
   meaning all additions to that particular file.

   Things are further complicated by the fact that one sometimes describes
   what the user sees as a single transaction (the addition to a file,
   perhaps) as several transactions to CICS. 
   Now, what about a task?

   Users tell CICS what type of transaction they want to do next by using a
   transaction identifier.  By convention, this is the first "word" in the
   input for a new transaction, and is from one to four characters long,
   although this source of the identifier is sometimes overridden by
   programming.

   CICS looks up the transaction identifier to find out which program to
   invoke first to do the work requested.  It creates a task to do the work,
   and transfers control to the indicated program.  So a task is a single
   execution of some type of transaction, and means the same thing as
   "transaction" when that word is used in its single event sense.

   A task can read from and write to the terminal that started it, read and
   write files, start other tasks, and do many other things.  All these
   services are controlled by and requested through CICS commands in your
   application programs.  CICS manages many tasks concurrently.  Only one
   task can actually be executing at any one instant.  However, when the task
   requests a service which involves a wait, such as file input/output, CICS
   uses the wait time of the first task to execute a second; so, to the
   users, it looks as if many tasks are being executed at the same time.

Temporary storage in CICS

Temporary Storage Queues

Temporary storage provides a means for storing data records in queues. Like files, these records are identified by a unique symbolic name. Temporary storage queues do not have to be predefined to Cics. They can be created in main storage or on auxilliary storage devices. Once created, these records can be read either sequentially or randomly by any other Cics program.

Temporary storage queues are not directly attached to a task. This means that temporary storage queues are task independant. Once a temporary storage queue is written, it remains intact after the task that created it has terminated.

Temporary Storage Queue Commands

There are three commands that process data in temporary storage queues.
* The WRITEQ TS command allows you to write records to a temporary storage queue. If no queue exists when this command is issued, one will be created and the records will be written to it.
* The READQ TS command allows you to read records, either sequentially or randomly, from a temporary storage queue.
* Records in a temporary storage queue can be updated and rewritten by using the REWRITE option of the WRITEQ TS command
* The DELETEQ TS command allows you to delete an entire temporary storage queue. Individual records cannot be deleted
* The queue name specified in a temporary storage command must not exceed eight characters in length

WRITEQ TS QUEUE (queue name)
 FROM (data area)
[LENGTH (data value)]
[ITEM (data area)]
[MAIN / AUXILLIARY]
[SYSID (name)]

READQ TS QUEUE (queue name)
 INTO (data area)
[LENGTH (data area)]
[ITEM (data value) / NEXT]
[NUMITEMS (data area)]
[SYSID (name)]

WRITEQ TS QUEUE (queue name)
 FROM (data area)
[LENGTH (data value)]
[ITEM (data area) [REWRITE]]
[MAIN / AUXILLIARY]
[SYSID (name)]

DELETEQ TS QUEUE (queue name)
 [SYSID (name)]

Transient Data Queues

Like temporary storage queues, transient data queues are task dependent. However transient data queues can only be read sequentially.

Unlike temporary storage queues, transient data queues must be defined before they are used. This definition takes place in a special Cics table called the Destination Control Table (DCT). The DCT is usually maintained by a sys prog. One of the fields in each DCT entry tells whether the queue is an intrapartition or extrapartition queue.

Intrapartition Data Queues
Intrapartition transient data queus may only reside on auxilliary storage and can only be read sequentially by other CICS programs. Reading an intrapartition data queue is destructive.
Intrapartition queues may also be associated with Automatic Task Initiation. When the number of records in an intrapartition queue reaches a predefined count a special task is automatically initiated.

Extrapartition Data Queues
Unlike intrapartition queus, extrapartition queues can be accessed by other Cics programs as well as batch programs executing outside of the CICS partition or region. They can reside on any sequential device, such as disk or tape, or be sent directly to an off line printer. Reading records in an extrapartition queue is non-destructive.

WRITEQ TD QUEUE (queue name)
 FROM (data area)
[LENGTH (data value)]
[SYSID (name)]

READQ TD QUEUE (queue name)
 INTO (data area)
[LENGTH (data area)]
[SYSID (name)]

DELETEQ TD QUEUE (queue name)
 [SYSID (name)]

* The WRITEQ TD command allows you to write records sequentially to a transient data queue
* The READQ TD command allows you to read sequentially from a transient data queue
* The DELETEQ TD command allows you to delete the contents of an intrapartition TD queue.
* Transient Data Queues are referenced by these commands using a symbolic name which must be predefined in the DCT
* The queue name specified in transient data commands must not exceed four characters in length
 
Exceptional Conditions

IOERR - An undetermined error has occured during input or output
ISCINVREQ - an undetermined error has occured on a remote system
ITEMERR - The requested item number is invalid
LENGERR - The length of a record is invalid or missing
NOSPACE - A write has failed due to lack of space
QIDERR - The requested queue cannot be found
QZERO - A read has been attempted on an empty queue
SYSIDERR - The specified remote system is unavailable or not defined

VSAM File Handling in CICS

In CICS, VSAM file operations are peformed using READ, WRITE, REWRITE, DELETE, UNLOCK, STARTBR, ENDBR, READPREV and READNEXT commands. These commands are explained in detail below.

The READ Command

READ
 DATASET (file name)
INTO (data area)
RIDFLD (record key area)
[UPDATE]
[EQUAL / GTEQ]
[LENGTH (record length area)]
[GENERIC]
[KEYLENGTH (data value)]
[SYSID (system name)]

The DATASET, INTO and RIDFLD options are required in every READ command. DATASET gives the name, in quotes, of the file that you wish to read. INTO names the data area within your program into which the record should be copied from the file. RIDFLD stands for Record IDentification FieLD. This option names the data area that contains the key value of the record you wish to read from the file.
The UPDATE option is used to establish exclusive control over a record. This is necessary to prepare CICS to update or delete a record later in your program.
EQUAL and GTEQ refer to the collating sequence in which record keys occur in the file. By default, the READ command will only read a record whose key is equal to the key specified in RIDFLD. If GTEQ is specified, the first record whose key is greater than or equal to the RIDFLD is read.
The LENGTH option is mandatory for reading variable length records. It specifies a data area that contains the maximum length input record that the program is expecting. When Cics executes the READ it stores the actual length of the record it reads into the data area specified in the LENGTH option. If this length exceeds the maximum length that the program had specified, the LENGERR exception condition is raised.
GENERIC tells CICS that the RIDFLD specifies only a partial key. KEYLENGTH, which is mandatory with the GENERIC option, tells CICS how many bytes of the RIDFLD key should be used to retrieve the record. The data value associated with the KEYLENGTH option may be a constant number, or it may be a variable data area defined in working storage.
The SYSID option is needed only if your installation uses the Intersystem Communication (ISC) facility to communicate with other systems. The four character system ID that you specify tells Cics on which system the file to be read is located. Whenever you specify the SYSID option, the LENGTH and KEYLENGTH options must be specified.

The WRITE command

WRITE
 DATASET (file name)
FROM (data area)
RIDFLD (record key area)
[LENGTH (data value)]
[KEYLENGTH (data value)]
[SYSID (system name)]

With the exception of FROM and LENGTH, all of these options are coded in the same way that they are coded for the READ command.
The FROM option indicates the name of the data area in working storage from which the record will be written.
The LENGTH option specifies the exact length of the record to be written. There is no need for CICS to return a length value to the program after the record has been written. Therefore, in the WRITE command, the LENGTH option can be specified by a constant number instead of by the name of the data area, as in the READ command. As with the READ command, the LENGTH option is required for variable length records.

The REWRITE Command

REWRITE
 DATASET (file name)
FROM (data area)
[LENGTH (data value)]
[SYSID (system name)]

After a record has been READ from a file with the UPDATE option, and the program has updated fields within the record, the REWRITE command can be issued to rewrite the record to the file and complete the update option.
Notice that the options that affect the WRITE command also affect the REWRITE command with the exception of the RIDFLD and KEYLENGTH options. These options are unnecessary because, if used at all they must be specified in the READ UPDATE command which must precede a REWRITE.
 
The DELETE Command

DELETE
 DATASET (file name)
[RIDFLD (record key area)]
[LEYLENGTH (data value)
[SYSID (system name)]

The DELETE command can be used in two ways to delete records. One way is to issue a DELETE command using the DATASET and RIDFLD options.
The other, safer, method is to issue a READ UPDATE command prior to deleting the record. The program can the inspect fields within the record to help determine whether the record should be deleted. If a record is deleted after being retrieved with a READ UPDATE command, the DELETE command may be issued without the RIDFLD option. RIDFLD is unnecessary in this instance because it was already specified on the READ UPDATE command.
The KEY LENGTH and SYSID options need to be issued only when the record to be deleted resides in a file on another system.

The UNLOCK Command

UNLOCK
 DATASET (file name)
[SYSID (system name)]

When a record is read with the UPDATE option, exclusive control for that record remains in effect until the record is either rewritten or deleted or until the transaction is terminated.
If once the record has been read, it is determined that an update is not necessary, exclusive control should be released from the record so that it can be accessed by other transactions.
The UNLOCK command releases the program's exclusive control over a record.
 
Writing a Browse Program
A browse transaction reads and displays multiple records from a file in a single transaction. Browse programs are usually coded to allow the user to continue browsing the file by pressing enter.
All browse programs contain the following Cics commands:
* STARTBR - Initiates the browse by establishing the key of the first record to be read.
* READNEXT - Reads the first and all subsequent records in a browse
* ENDBR - Terminates the Browse.

The STARTBR Command

STARTBR
 DATASET (file name)
RIDFLD (data area)
[GTEQ / EQUAL]
[GENERIC]
[KEYLENGTH (data value)]
[SYSID (system name)]

Most of these options are the same as for the READ command, except that STARTBR does not have INTO or LENGTH options. These options are unnecessary because STARTBR does not actually read a record into the program. It merely sets up a starting record key from which the READNEXT command works. Also note that, unlike the READ command, STARTBR takes GTEQ as a default option.
When a STARTBR command is issued with the GENERIC option the transaction is known as a generic browse.

The READNEXT command

READNEXT
 DATASET (file name)
INTO (data area)
RIDFLD (data area)
[LENGTH (data area)]
[KEYLENGTH (data value)]
[SYSID (system name)]

The READNEXT command reads just one record each time it is executed, therefore a browse program must include a loop that issues the READNEXT command multiple times. The loop should terminate after enough records have been read to fill up the screen, or until some earlier end point (such as end of file) has been reached.
The READNEXT command looks a lot like the READ command. Unlike STARTBR it does include the INTO and LENGTH options, records are actually being read into the program. Unlike READ, READNEXT does not have the GTEQ and GENERIC options, because these options establish the starting browse key, which is taken care of by STARTBR. The KEYLENGTH and SYSID options are required if the file to be read resides on another system.
 
The ENDBR Command

ENDBR
 DATASET (file name)
[SYSID (system name)]

The ENDBR command has two options, DATASET and SYSID. They perform the same functions in ENDBR as they do in all the other file handling commands.
Using the COMMAREA
After issuing the ENDBR command, you must issue a RETURN command to return control of the program to CICS. Use the COMMAREA option of the RETURN command in case the user wishes to continue the browse. It is common practice to store the last record key returned by the READNEXT command into a COMMAREA field. When the user resumes execution of the program, the key stored in DFHCOMMAREA may be moved to the data area referenced by the RIDFLD option of the STARTBR command.
 
The READPREV Command

A browse that reads a file in descending key sequence is called a reverse browse. A reverse browse program is coded using the READPREV command instead of the READNEXT command. The options of the READPREV command are identical to those of the READNEXT command. A reverse browse program is coded just like a normal browse, except that, after an initial mandatory READNEXT command is issued, the program loop executed the READPREV command instead of the READNEXT command.
The RESETBR Command
The RESETBR combines the effects of an ENDBR and a STARTBR. It's options are identical to those of the STARTBR. The RESETBR command can be used for a skip-sequential browse. During this type of application, the starting key of the browse is reset one or more times during the same transaction.

 Exceptional Conditions
Like any CICS commands, a file handling command may raise an exceptional condition when executed. Your programs should include either a HANDLE CONDITION or RESP options and some corresponding routines to handle the more common conditions that may occur.

CICS/FEPI

What is FEPI?
FEPI stands for Front End Programming Interface. It is a terminal emulator implemented via a Programming Interface. FEPI is integrated into CICS, so if you have CICS (CICS/ESA V3.3 or above) then you already have access to FEPI. FEPI can communicate with transactions running on CICS or IMS systems.

What can I do with FEPI?
FEPI can be used to integrate your existing CICS applications into one system without needing to alter the existing systems.
 For example if two companies merge, FEPI can be used to provide a single user interface to both of the merged companies' systems. Another example, if you want to be able to access all a customer's details from a number of different systems in one single system - you could have a single screen where the user enters the customer's name and the FEPI interface will go to, for example, the Home Insurance system, the Motor Insurance system and Accounts system retrieve details from each of these systems. The information from each of these different systems will be returned and be available for displaying on one screen. This could be useful, for example, for cross selling. You might be able to see that a customer has Motor Insurance, but not Home Insurance, you could then ask the customer if they had considered buying your company's Home Insurance product!
You could also use FEPI to add new functions to a system. Say you want to keep an existing system stable, but want to add new functionality, you could write a program which would use FEPI to access the stable system, and access the programs which contain the new functionality when it is required.
As part of your company's Web enablement you could use FEPI to provide an interface between your CICS systems and your Web site. You could keep the existing CICS systems, but have a FEPI based system to handle enquiries from the Web. The FEPI programs would extract the required information from the existing system and return it to the Web server.
 

Further Reading
CICS Front End Programming Interface User's Guide (IBM SC33-1629-02)
The CICS Programmer's Guide to FEPI (McGraw Hill ISBN 0-07-7077793-8)

CICS Program Compilations under TS

CICS Transaction Server includes an ‘integrated translator component’. This means that you can compile programs to be used under CICS using a single job step no more CICS Translate Step.

The CICS Translate step was required to translate any EXEC CICS commands into something that the language compiler could understand, in COBOL for example EXEC CICS commands were converted into CALLs. Once the translator had completed the generated code was passed to the compiler and finally the compiled code was passed to the link editor.

For DB2 CICS Programs you would have to feed the source code firstly to the DB2 Preprocessor, then through the CICS translator, and then that would go to the compile and link edit steps.

 The integrated translator in CICS TS combines the translate and compile into one. The integrated translator can handle CICS API commands, CICS SPI (System Programming Interface) commands, CICSPlex SM API commands and DL/I EXEC DLI commands. DB2 commands (EXEC SQL) are translated using the ‘SQL integrated coprocessor’.

You now only need two steps in your job, the Compile and the Link Edit.

All the diagnostic messages will now appear in the one listing, And the compiler statement numbers will be the same as they are in the original source code.

The combining of the translator and compiler now means it is possible to have CICS and DB2 commands inside copybooks. Previously the copybooks were not expanded until the compile step, so any CICS or DB2 Commands in a copybook would be missed by the translate and preprocessor phases.

 Another feature of using the integrated translator is that when you CALL another program you no longer have to pass DFHEIBLK and DFHCOMMAREA as arguments. These two areas are defined as GLOBAL in the outermost program and so are available to any called programs.

An important change has taken place with the Execute Interface Block (DFHEIBLK) definitions. All binary (COMP) fields are now defined as COMP-5. This means that they are unaffected by what you specify in the TRUNC compiler option, which has been the source of some problems in the past.

For more information visit http://www.ibm.com/software/ts/cics/v2
IBM Document, ‘Application development improvements with CICS TS Version 2.2’