Description

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

The ITTWRITE macro asynchronously captures a full trace buffer while the application continues processing and writing trace entries to another trace buffer.

Parent topic: ITTWRITE — Write a full trace buffer to DASD or tape

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: 64-bit.
ASC mode: Primary or access register.
Interrupt status: Enabled or disabled for I/O and external interrupts.
Locks: No locks may be held.
Control Parameters: Must be in the 64-bit 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

All registers are viewed as 64-bit values. 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 ITTWRITE macro is written as follows:

Syntax Description
   
name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede ITTWRITE.
   
ITTWRITE  
   
␢ One or more blanks must follow ITTWRITE.
   
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).
   
,TBWCADDR64=tbwc_address64 tbwc_address64: 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
Specifies a required parameter that indicates the number of bytes in length of the buffer to be written externally. Though the buffer length is 64-bits, it is required to keep the buffer size within manageable limits. IBM® suggest that the length be between 4KB and 512M. Component trace splits buffers that are too large to fit into a single block.
,TOKEN=token
Specifies 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 the z/OS Internet library for complete field names and lengths, offsets, and descriptions of the fields of the TBWC.
TBWCADDR64=tbwc_address64
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 the z/OS Internet library 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 ITTWRITE function executes synchronously. The SYNCH keyword is optional. NO causes the ITTWRITE function to execute asynchronously.
Note: Because your application runs slower, IBM does not suggest that you use the SYNCH keyword on every ITTWRITE invocation. Use the SYNCH keyword in the start/stop routine any time that the trace buffers are to 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 ITTWRITE macro with the SYNCH keyword. The system copies the buffers to I/O buffers that CTRACE then can write to the external data set. 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 ITTWRITE 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 ITTWRITE Macro
Abend Code Reason Code Description
00D 00010100 For the ITTWRITE 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 ITTWRITE macro parameter list.
00D 00010300 The buffer length passed was 0 or less.
00D 00010400 The buffer length is unusually large and is not supported by CTRACE.

Return and reason codes

When control returns from ITTWRITE, 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 ITTWRITE 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 ITTWRITE Macro
Hexadecimal Return Code Hexadecimal Reason Code Meaning
00 None. ITTWRITE was successful.
04 None. ITTWRITE 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 ITTWRITE 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 ITTWRITE 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 ITTWRITE macro in TCRCODE and TCRSNCODE. 
         ITTWRITE 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