Using CTRACECS to manage trace buffer status

Your application is responsible for managing trace buffers when writing to them and deleting them. Component trace manages the buffers while they are being captured until they are ready for reuse. Your application uses the CTRACECS macro to update and track the status of its buffers. Each buffer has an associated trace buffer writer control (TBWC) area to store the state of the buffer and the sequence number associated with the buffer. Each buffer has 4 possible states:

State	Description	Set by:
FILLING	trace is filling the buffer	application
FULL	full and ready to be written to datasets	application
CAPTURE	Component trace is writing to datasets	Component trace
AVAILABLE	available for use by the trace	Component trace

CTRACECS, which sets the fields in the TBWC area mapped by the ITTTBWC mapping macro, tests the state of the application's trace buffers to prevent data loss due to buffers being overwritten before being written to tape or DASD by the CTRACEWR macro. The current state of the application's trace buffer can be compared to the expected buffer state, before setting the buffer to the requested state. You can use the CTRACECS macro to ensure that:

Only when the buffer is in the available state can it be set to filling.
Only when the buffer is in the filling state can it be set to full.
Only when the buffer is in the full state can it be set to available. When the writer is active there is no need to use the CTRACECS macro to mark the buffer available.
You are working with the correct buffer by comparing the current buffer sequence number to the expected buffer sequence number.

Figure 1. Managing Buffer Status

The following steps are an example of how you might use the CTRACECS macro to manage multiple trace buffers:

Mark all buffers available. You cannot use the TESTMODE keyword in subsequent invocations if the buffer is not initialized to a known state.

  CTRACECS    TBWC=TBWCAREA,                               x
              MODE=AVAIL,                                  x
              COM='Initialize buffers to available state'

Mark an available buffer filling and start putting data into it.

              LA R6,3                                      x
              ST R6,EXPSEQ                                 x

  CTRACECS    TBWC=TBWCAREA,                               x
              TESTMODE=AVAIL,                              x
              MODE=FILLING,                                x
              CSLABEL=NOT_AVAIL,                           x
              BUFFSEQ#=NEWSEQ#,                            x
              COM='Mark Buffer filling if available'
              .
              .
NOT_AVAIL
*The buffer is not available, try another buffer.

When there is no more room for trace entries in the buffer, mark the buffer full.

            LA R6,2                                      x
            ST R6,EXPSEQ                                 x
                                                         x
  CTRACECS  TBWC=TBWCAREA,                               x
            MODE=FULL,                                   x
            TESTMODE=FILLING,                            x
            TESTSEQ#=EXPSEQ,                             x
            CSLABEL=NOT_FILLING,                         x
            COM='MARK buffer full if filling'
            .
            .
NOT_FILLING
*The buffer is not filling or the buffer sequence number
assigned to the buffer is not the expected value.  The
buffer is not marked full.

If using the external writer, invoke the CTRACEWR macro to write the trace buffer entries to the external data set. Component trace will mark the buffer available, once CTRACEWR has finished writing the trace entries to the data set.

If you are not using an external writer, mark the buffer available yourself so that it can be reused.

           LA R6,1                                       x
           ST R6,EXPSEQ                                  x
                                                         x
 CTRACECS  TBWC=TBWCAREA,                                x
           MODE=AVAIL,                                   x
           TESTSEQ#=EXPSEQ,                              x
           CSLABEL=WRONGBUFFER,                          x
           COM='Mark buffer# 1 available'
           .
           .
 WRONG_BUFFER
 *The is not buffer# 1 and is not marked available.

The TBWC mode field indicates the requested status of the trace buffers.

MODE: Status
AVAIL: The trace buffer is available and ready to be filled with trace entries.
FILLING: The application is entering trace entries into the trace buffer.
FULL: The application cannot enter any more trace entries into the trace buffer.
CAPTURE: The system is writing the trace buffer out to DASD or tape.

The CTRACECS macro requires that a unique TBWC buffer sequence number be provided by the application. The application must serialize the buffer sequence number assigned to each buffer. The sequence number must be unique for every buffer passed to the external writer on the CTRACEWR macro.

Support for testing the application's trace buffers is provided by the TESTMODE and TESTSEQ# parameters. The system updates the TBWC to the requested status, if:

The expected status (TESTMODE) is equal to the current mode (MODE), and
The expected buffer sequence number (TESTSEQ#) equals the current buffer sequence number (BUFFSEQ#).

A successful comparison will update the TBWC to the requested status. Otherwise, the application will branch to a subroutine that you specified using the CSLABEL keyword.

CSLABEL is optional with TESTMODE=CURRENT but required with TESTMODE=AVAIL/FULL/FILLING and TESTSEQ#. If you specify CSLABEL=RETRY, the default, the code will branch to a generated label that retries the current value of the TBWC until the update is successful.

Note: IBM® recommends using TESTMODE and TESTSEQ# to test the state of the buffer.

The following lists the keyword parameters for TESTMODE:

TESTMODE: Status
AVAIL: Requests that the state of the buffer be set to the state requested by the MODE keyword only when the buffer is in the available state.
FILLING: Requests that the state of the buffer be set to the state requested by the MODE keyword only when the buffer is in the filling state,
FULL: Requests that the state of the buffer be set to the state requested by the MODE keyword only when the buffer is in the full state.
CURRENT: Is the default value that sets the state of the buffer to the state specified by the MODE keyword regardless of the current state.

The TBWC contains the current buffer sequence number (TBWCSEQ), which must also equal the expected buffer sequence number (TESTSEQ#), before it can be updated to the desired buffer status. Use TESTSEQ# to ensure a new buffer sequence number is not being associated with the current TBWC. All four TBWC fields and the buffer sequence number are used to communicate between your application and a component trace external writer.

Your application might do the following:

Check whether a trace buffer is available to be filled using TESTMODE=AVAIL. IBM recommends more than one trace buffer when tracing with an external writer and of course the TBWC would need to be initialized to the available state when it is obtained.
If no buffers are available, your application should consider obtaining more buffers or increase the buffer size the next time the trace is started.
When using the CTRACECS macro to mark a new buffer FILLING, make sure that the buffer sequence number is always incremented. The buffer sequence number is in the TBWC. Increment the buffer sequence number when using the external writer even if the return code from the CTRACEWR macro is not zero.

THE CTRACEWR macro: To write trace buffers to trace data sets on DASD or tape, your application must be connected to an external writer. The CTRACEWR macro writes the trace buffers out to trace data sets. The trace buffer status should be set to full by the application using the CTRACECS macro before issuing the CTRACEWR macro. When the CTRACEWR macro is issued, CTRACE marks the buffer captured and when CTRACE is finished capturing the buffer, it marks the buffer available for use again. If the application tries to reuse the buffer when it is marked captured, CTRACE will not write the buffer to the external data set.