Description

Description

z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
SA23-1372-00

The CTRACEWR macro enables the component trace external writer to write a full trace buffer out to a trace data set on DASD or tape.

The CTRACEWR macro will asynchronously capture a full trace buffer while the application continues processing and writing trace entries to another trace buffer.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or PSW key 0-7
Dispatchable unit mode:	Task or SRB mode
Cross memory mode:	PASN=HASN=SASN or PASN¬=HASN¬=SASN
AMODE:	31-bit.
ASC mode:	Primary or access register.
Interrupt status:	Enabled or disabled for I/O and external interrupts.
Locks:	If SYNCH(YES) is specified, no locks can be held.
Control Parameters:	Must be in the primary address space

Programming requirements

None.

Restrictions

If either the BUFFALET or the TBWCALET identifies the secondary or home address space, then both must identify the same address space (that is, both the trace buffer and the trace buffer writer control area must be in the same address space).

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: If GPR 15 contains 0 or 4, GPR 0 is used as a work register by the system; otherwise, GPR 0 contains a reason code.
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the ARs contain:

Register: Contents
0-15: Unchanged

Performance implications

None.

Syntax

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

Syntax	Description

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

␢	One or more blanks must precede CTRACEWR.

CTRACEWR

␢	One or more blanks must follow CTRACEWR.

BUFFADDR=`buffer_address`	`buffer_address`: RS-type address or register (2)-(12).

,BUFFALET=`buffer_alet`	`buffer_alet`: RS-type address or register (2)-(12).
,BUFFALET=NOBUFFALET	Default: BUFFALET=NOBUFFALET

,BUFFLEN=`buffer_length`	`buffer_length`: RS-type address or register (2)-(12).

,TOKEN=`token`	`token`: RS-type address or register (2)-(12).

,TBWCADDR=`tbwc_address`	`tbwc_address`: RS-type address or register (2)-(12).

,TBWCALET=`tbwc_alet`	`tbwc_alet`: RS-type address or register (2)-(12).
,TBWCALET=NOTBWCALET	Default: TBWCALET=NOTBWCALET
,SYNCH=YES \| NO	Default: SYNCH=NO

,RC=`return_code`	`return_code`: RS-type address or register (2)-(12).

,RSNCODE=`reason_code`	`reason_code`: RS-type address or register (2)-(12).

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

,MF=(S)	Default: MF=(S)

Parameters

The parameters are explained as follows:

BUFFADDR=buffer_address: Specifies a required parameter that points to the address of the buffer to be written externally.
,BUFFALET=buffer_alet
,BUFFALET=NOBUFFALET: Contains the PASN ALET that identifies the address/data space where the buffer resides. Use this optional parameter when the buffer to be written externally resides in either a data space or an address space that is different from the current primary address space. The default is BUFFALET=NOBUFFALET.
,BUFFLEN=buffer_length: A required parameter that indicates the number of bytes in length of the buffer to be written externally. IBM® recommends the length be at least 4KB. Component trace will split buffers that are too large to fit into a single block.
,TOKEN=token: A required parameter that specifies the token passed to the start/stop exit routine when it was requested to start tracing externally.
TBWCADDR=tbwc_address: Specifies a required parameter that points to a word that points to the address of the storage obtained by the application for the trace buffer writer control area (TBWC) mapped by ITTTBWC. The TBWC provides communication between the application and component trace. 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.
,TBWCALET=tbwc_alet
,TBWCALET=NOTBWCALET: Contains the ALET that identifies the address/data space where the TBWC resides. Use this optional parameter when the TBWC resides in either a data space or an address space that is different from the current primary address space. The default is TBWCALET=NOTBWCALET.
,SYNCH=YES | NO: YES causes CTRACE to copy the application's buffers before control is returned instead of scheduling an asynchronous SRB to copy the buffer. The CTRACEWR function executes synchronously. The SYNCH keyword is optional. NO causes the CTRACEWR function to execute asynchronously.
Note: Because your application will run slower, IBM does not recommend that you use the SYNCH keyword on every CTRACEWR invocation. Use the SYNCH keyword in the start/stop routine any time that the trace buffers will be freed. For example, when the trace is being turned off or the buffer size is changing, you can free trace buffer storage after issuing the CTRACEWR macro with the SYNCH keyword and be assured that the buffers were copied to I/O buffers to be written to the external data set by CTRACE. The default is SYNCH=NO.
,RC=return_code: Specifies the location where the system is to store the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=reason_code: Specifies the location where the system is to store the reason code. If GPR 15 contains a return code other than 0 or 4, the reason code is also in GPR 0.
,COM=comment
,COM=NULL: Comments the macro invocation. If the comment contains any lowercase characters, it must be enclosed in quotation marks.
,MF=(S): Specifies the standard form of the CTRACEWR macro.

ABEND codes

The following table identifies abend code and reason code combinations, and a description of what each means:

Table 1. Abend codes for the CTRACEWR Macro
Abend Code	Reason Code	Description
00D	00010100	For the CTRACEWR macro, the parameter list version number is not correct.
00D	00010200	The system found either nonzero values in the reserved fields or unused fields for the requested service in the CTRACEWR macro parameter list.
00D	00010300	The buffer length passed was 0 or less.

Return and reason codes

When control returns from CTRACEWR, GPR 15 (and return_code, if you coded RC) contains one of the following return codes. The third byte of GPR 0 (and reason_code, if you coded RSNCODE) might contain one of the following reason codes.

Note: An application should always check the return code from the CTRACEWR macro. A non-zero code indicates that some data might have been lost in the next record output.

Table 2. Return and Reason Codes for the CTRACEWR Macro
Hexadecimal Return Code	Hexadecimal Reason Code	Meaning
00	None.	CTRACEWR was successful.
04	None.	CTRACEWR was unsuccessful. No data was captured because the trace is not connected to an active external writer.
08	xxxx01xx	Storage required to perform the write operation could not be obtained.
08	xxxx02xx	CTRACEWR was unable to schedule an SRB to process this request.
08	xxxx03xx	The control information (TBWC) has already been reused by the application.
0C	xxxx01xx	The caller is holding locks.
0C	xxxx02xx	The input token was not valid.
0C	xxxx0300	The TBWC is not valid because the sequence number is the same as a previous write request.
0C	xxxx0301	The TBWC is not valid for one of the following reasons: The TBWC is not in central storage and the CTRACEWR issuer is disabled. The BUFFALET is not the same as the TBWCALET.

Example

Indicate to component trace that the buffer at address TRACEADR is ready to be written out. Pass the token (TCWTRTKN) that the application received from the start/stop routine. Component trace is to store the return and reason codes from the CTRACEWR macro in TCRCODE and TCRSNCODE.

         CTRACEWR BUFFADDR=TRACEADR,BUFFLEN=TRACESIZ,                  X
               TOKEN=TCWTRTKN,TBWCADDR=TBWCADR,                        X
               RC=TCRCODE,RSNCODE=TCRSNCODE

         TBWCADR   DS A                TBWC address
         TRACEADR  DS A                Trace buffer address
         TRACESIZ  DS F                Trace buffer size
         TCWTRTKN  DS CL8              Trace writer token produced by
*                                      CTRACE upon connection
         TCRCODE   DS F                Return code from CTRACE
         TCRSNCODE DS F                Reason code from CTRACE