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 |
- 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.
- 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.
- 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.
- 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#).
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.
- 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.
- 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.