Usage of the trace buffer

System trace records are stored in the trace buffer of each process when the TraceFlagBuffer is switched on. The trace buffer is a ring; trace records are written sequentially into the buffer, and when the end of the buffer is reached, storage continues at the beginning of the buffer, overwriting older records. The size of the ring buffer is determined by the value of the TraceMaxSizeBuffer attribute. The default value is 131,072, the unit is bytes. The attribute can be set to any positive integer, but changes cannot be made while CICS® is running.

The ring buffer is the default destination for system trace records. The storing of trace records in the ring buffer puts the least load on the process that is being traced, making this the best way to trace production systems.

Records that are in the ring buffer must be retrieved before they can be read; this is done by dumping the ring buffer to a file. CICS processes dump their ring buffers automatically; see Automatic ring-buffer dumps for more information.

The location of all system trace files, including those that are dumped from the buffer, is determined by the value of the TraceDirectorySystem attribute. Files that are generated from ring buffers are named in accordance with the following pattern:

regionName.processName.processNumber.cicsdmp.indexCounter

Under this naming convention, processName is the name of the CICS process from which the trace is generated (see Table 1 for a list of CICS process names), the processNumber is the identifier that is assigned by CICS, not by the operating system. The indexCounter is a three-digit integer that indicates the number of dumps that have occurred since the region was cold-started. These numbers ensure that a process does not overwrite its dump files. They can also be used to match dump files from different processes across the region; all processes dumped at the same time will use the same index counter.

The trace files that are generated from ring buffers are unformatted. They must be formatted by using the cicstfmt utility before they can be read.