CTRACECS — Setting fields in the trace buffer writer control area

Description

The CTRACECS macro allows you to set fields in the trace buffer writer control area (TBWC). By setting these fields, your application can manage and track the status of its trace buffers. When a buffer is full, the application uses the CTRACEWR macro to have the component trace external writer write the buffer out to DASD or tape.

See TBWC in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for complete field names and lengths, offsets, and descriptions of the fields of the TBWC, which is mapped by the ITTTBWC mapping macro.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or PSW key 0
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN=SASN
AMODE:	24- or 31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	No requirement
Control parameters:	Must be in the primary address space or be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL)

Programming requirements

The program checking the bits in the TBWC must include the ITTTBWC mapping macro.

Restrictions

None.

Register information

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the caller issued the macro. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

When control returns to the caller, the ARs contain:

Register: Contents
0-15: Unchanged

Performance implications

None.

Syntax

The standard form of the CTRACECS macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One of more blanks must precede CTRACECS.

CTRACECS
␢	One or more blanks must follow CTRACECS.

TBWC=`tbwcaddr`	`tbwcaddr`: RS-type address or register (2) - (12).

,MODE=AVAIL
,MODE=FULL
,MODE=FILLING,BUFFSEQ#=seq#addr

,BUFFSEQ#=`seq#addr`	`seq#addr`: RS-type name or address in register (2) - (12).

,TESTMODE=CURRENT	Default: TESTMODE=CURRENT
,TESTMODE=AVAIL
,TESTMODE=FULL
,TESTMODE=FILLING

,TESTSEQ#=`testseq#`	`testseq#`: RS-type name or address in register (2)-(12). that specifies the expected buffer sequence number.
,TESTSEQ#=TBWCSEQ#	Default: TESTSEQ#=TBWCSEQ#

,CSLABEL=`cslabel`	`cslabel`: A-type name of a label.
	Optional for TESTMODE=CURRENT.
	Required for TESTMODE=AVAIL/FULL/FILLING and TESTSEQ#.
,CSLABEL=RETRY	Default: CSLABEL=RETRY

,COM=`comment`	`comment`: A comment string.
,COM=NULL	Default: COM=NULL

Parameters

The parameters are explained as follows:

TBWC=tbwcaddr

Specifies the storage for the TBWC which contains the state of the buffer and the buffer sequence number. The storage must be 8 bytes in length and aligned on a doubleword boundary.

If a register is used to give the address of the TBWC and the program is running in access register ASC mode, then the corresponding AR must be set appropriately to contain the ALET of the TBWC.

,MODE=AVAIL

,MODE=FULL

,MODE=FILLING

Indicates the requested state to which the buffer is to be set.

AVAIL: Requests that the trace buffer be set to the available state. Use MODE=AVAIL to initialize the trace buffers to the available state before filling them with data. If the buffer is eventually written out to an external writer data set using the CTRACEWR macro, CTRACE will mark the buffer available when it is finished with it. If the buffer is not going to be written using CTRACEWR, use CTRACECS to mark the buffer available before reusing it.
FILLING: Requests that the buffer be set to the filling state. Use this parameter before you have put any trace entries in the buffer to indicate that it is about to be filled.
IBM® recommends that TESTMODE=AVAIL be used with MODE=FILLING to make sure that you will not overlay data in a buffer that is already in use.
FULL: Requests that the buffer be set to the full state. Use this parameter to indicate that the buffer is filled with trace data. No more data should be put into the buffer until its state is set to available. If you are using CTRACEWR, CTRACE will mark the buffer available when it is finished writing its contents to the output dataset. If you are not using CTRACEWR, you will have to mark the buffer available using the CTRACECS macro, specifying MODE=AVAIL.

,BUFFSEQ#=seq#addr

Specifies the name (RS-type) or address (in register 2-12) of a fullword that contains the address of TBWCxxxx, a field that contains the buffer sequence number. The number, starting at one and incremented by 1 for every buffer, must be unique for every buffer passed to an external writer by a given trace.

For MODE=FILLING, the BUFFSEQ# parameter is required. Do not specify BUFFSEQ# with MODE=FULL or AVAIL.

,TESTMODE=CURRENT

,TESTMODE=AVAIL

,TESTMODE=FILLING

,TESTMODE=FULL

Optional input specifying the expected state of the buffer. The expected state is compared to the current state of the buffer. The TBWC is only updated with the requested state (MODE) if the expected state (TESTMODE) is the same as the current state of the buffer.

CURRENT: CURRENT is the default. It sets the state of the buffer to the state specified by the MODE keyword regardless of the current state.
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. Use this parameter with MODE=FILLING to change the state of the buffer to its next valid state. CSLABEL is required with TESTMODE=AVAIL.
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. Use this parameter with MODE=FULL to change the state of the buffer to its next valid state. CSLABEL is required with TESTMODE=FILLING.
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. Use this parameter with MODE=AVAIL to change the state of the buffer to its next valid state. CSLABEL is required with TESTMODE=FULL.

,TESTSEQ#=testseq#

,TESTSEQ#=TBWCSEQ#

Optional fullword input value that is used to test the current buffer sequence number. If the input value matches the current buffer sequence number the TBWC is updated to the expected requested state (specified by the MODE keyword). If you are using more than one buffer, TESTSEQ# ensures that your are changing the state of the correct buffer by verifying its sequence number in the TBWC.

,CSLABEL=label

,CSLABEL=RETRY

Specifies the name of a label within your application to which the system returns control when the current mode or sequence number does not equal the expected buffer mode or sequence number. CSLABEL is required when using the TESTMODE and TESTSEQ# keywords; however, it is optional when used with TESTMODE=CURRENT.

If CSLABEL=RETRY is specified, the application will branch to a system generated label that retries the CDS instruction with the current value of the TBWC. CSLABEL=RETRY is not valid with the TESTMODE and TESTSEQ# parameters. It is provided for existing applications that invoked the CTRACECS macro before the two parameters became available.

,COM=comment

,COM=NULL

Optional input. Comments the macro invocation. The comment string must be enclosed in quotation marks if it contains any lowercase characters.

Return and reason codes

None.

Example 1

Indicate to component trace that you are starting to fill a trace buffer. Then indicate to component trace that the buffer is full. Note that this example does not use the, TESTMODE TESTSEQ#, and CSLABEL parameters which would prevent buffers from being overwritten, especially in a sysplex environment.

         CTRACECS TBWC=TBWCAREA,MODE=FILLING,BUFFSEQ#=REQ#
             .
             .
             .
         CTRACECS TBWC=TBWCAREA,MODE=FULL

         TBWCAREA DS CL8               Trace Buffer Writer Control area
*                                      TBWC contains buffer seq #
         REQ#     DS F                 Buffer Seq #
*

Example 2

Test to ensure that the next buffer associated with the input TBWC is currently available. If it is, update the mode to FILLING. If the buffer is not available the code will branch to the subroutine TLABL.

           CTRACECS TBWC=TBWCAREA,MODE=FILLING,BUFFSEQ#=next#,
                  TESTMODE=AVAIL,CSLABEL=TLABL

             .

             .

           TLABL: (next instruction)

Example 3

Update the status of the buffer from FILLING to FULL if its sequence number is equal to the expected buffer sequence number in the TESTSEQ# parameter.

         CTRACECS TBWC=TBWCAREA,MODE=FULL,TESTMODE=FILLING,
                  TESTSEQ#=xtestseq#,CSLABEL=TLABL

Example 4

Update the status of the buffer to FILLING regardless of its current status. The following example uses the default values for TESTMODE and CSLABEL.

         CTRACECS TBWC=TBWCPTR,MODE=FILLING,BUFFSEQ#=BUFFNUM,
                  TESTMODE=CURRENT,CSLABEL=RETRY