Administering output from a CICS region

Note: This information only applies to dynamically allocated data sets with the SYSOUT=<class name> parameter. Transient data queues that are written to MVS™ data sets must continue to be defined in the region's JCL.

Output written to the CICS® transient data queues appears in JCL DDNAMEs that are allocated to a CICS region. An example of this transient data queue is CSSL, which is defined as an extra partition transient data queue and assigned to DDNAME MSGUSR. Over time the amount of data written to the data set can become very large and the data set needs to be deallocated from the region in order to reduce JES spool usage. Here are some recommendations for you to consider.

The recommended implementation is to allow CICS to dynamically allocate DDNAMEs and data sets rather than specifying them in the CICS JCL. In this way, all transient data queues that are defined as extra partition with a DDNAME such as MSGUSR, CEEMSG and CEEOUT are dynamically allocated when the associated transient data queue is opened. This associated data set is deallocated when the transient data queue is closed, and a new data set is dynamically allocated when it is reopened.

We also recommend that the indirect routing of transient data queues to CSSL be tailored to your environment and user requirements, specifically when a high number of messages could be written to the transient data queue. Example for transient data queue CESE DDNAME CEEMSG shows where directing all output to CSSL should be reviewed and possibly changed.

For SPI auditing:
Every time a resource is modified, message DFHAP1900 is written to the CADS transient data queue, which then redirects the output to CSSL. The message could get lost amongst all the other messages that get written to CSSL. Therefore, we recommend that CADS be defined as an extra partition data set with its own DDNAME. For example:

DEFINE TDQUEUE(CADS)          GROUP(DFHDCTG)     
       TYPE(EXTRA) TYPEFILE(OUTPUT) DDNAME(CADSMSGS)
       DESCRIPTION( )
For Java™ in CICS:
Some users prefer the STDOUT and STDERR messages written by Java programs to be displayed in the CICS job log and these messages appear in DDNAME MSGUSR because transient data queues CSJO and CSJE are defined with TYPE(INDIRECT) INDIRECTNAME(CSSL). This often results in MSGUSR being overloaded with messages, making any form of problem determination difficult, so we recommend that CSJO and CSJE be defined as extra partition transient data queues, each with its own DDNAME, as follows:

DEFINE TDQUEUE(CSJO)          GROUP(DFHDCTG)     
       TYPE(EXTRA) TYPEFILE(OUTPUT) DDNAME(your_ddname)
       DESCRIPTION(CICS JVM STDOUT redirection)  
                                                 
DEFINE TDQUEUE(CSJE)          GROUP(DFHDCTG)     
       TYPE(EXTRA) TYPEFILE(OUTPUT) DDNAME(your_ddname)
       DESCRIPTION(CICS JVM STDERR redirection)
Important:
  • Do not specify the OUTLIM parameter on any SYSOUT dataset defined in the CICS JCL. Doing so will cause the CICS region to abend with system completion code 722 as soon as the limit is exceeded.
  • Be very aware that the moment a transient data queue is closed, all attempts to access that queue will fail with potential loss of important messages. For this reason, take special care when closing and reopening transient data queue CSSL associated with DDNAME MSGUSR.
  • Do not code DDNAME MSGUSR in the CICS JCL. When CICS starts, MSGUSR will be dynamically allocated.
  • Liberty and Java create their own SYSPRINT, STDOUT, or STDERR DD cards over which CICS has no control.
  • If you are using z/OS® Communications Server, the trace should always be switched to OFF in production; in addition, SPIN=(UNALLOC,2M) should be specified in the JCL for both TCPDATA and SYSTCPT, which causes the output to be available each time a size of 2 megabytes is reached.
  • Transient data queues CESE and CESO to which Language Environment® writes output are already defined as extra partition transient data queues, each with a dedicated DDNAME. To reduce the amount of data written to these data sets, especially CEEMSG, we recommend that the Language Environment runtime option TERMTHDACT be set to QUIET. This setting reduces the amount of data, and more importantly for problem determination, dramatically reduces the number of EXEC CICS WRITEQ TD QUEUE(CESE) entries in the CICS trace table.
  • CICS-supplied resource definition group DFHDCTG contains all the transient data queue definitions that could be used by CICS. It is not a locked group, so we recommend that you take a backup copy so that it will be possible to undo changes at some point in the future.

Example for transient data queue CESE DDNAME CEEMSG

Transient data queue CESE DDNAME CEEMSG is used for this example.
Before you begin:
  • CICS resource group DFHDCTG contains the definition for transient data queue CESE. Ensure that the definition has not been changed and is defined as an extra partition queue that does not redirect to CSSL.
  • Do not code //CEEMSG DD SYSOUT=* in the region's JCL. The default value for the SPIN parameter is YES, which means that there is no need for it to be coded.

When the region starts, DDNAME CEEMSG will be dynamically allocated to the address space as soon as CICS opens transient data queue CESE.

When CESE needs to be emptied and a new one allocated, simply log on to the region (or use some form of user-written code or a vendor product), and issue this sequence of commands:
Figure 1. Commands to deallocate and reallocate data sets

EXEC CICS SET TDQUEUE(CESE) CLOSED 
EXEC CICS SET TDQUEUE(CESE) OPEN

When the command sequence is complete, a new spool data set will be allocated to DDNAME CEEMSG and the old one is now available for processing.

Write your own code or use a third party product to spin off output data sets. If writing your own code, see IBM Redbooks: Implementing REXX Support in SDSF for information about how to use REXX and the SDSF interface to write data from CEEMSG or any other DDNAME to a user-defined data set and then use the SDSF interface to issue the PO (Purg Output) command to purge the output that is no longer required.

Java samples can be found in zFS structure /usr/lpp/sdsf/java/samples/com/ibm/zos/sdsf/sample.

What to do next

We recommend you review all transient data queues defined with TYPE(INDIRECT) INDIRECTNAME(CSSL). It is a good idea to separate important transient data queues and those that contain large amounts of output. If needed, you can change the definition to TYPE(EXTRA) TYPEFILE(OUTPUT) DDNAME(your_ddname) so that it does not redirect output to CSSL but to your specified transient data queue.