Externalizing trace data through the external writer

By using the external writer, you can write application trace buffers directly to a trace data set on DASD or tape rather than requesting a dump. While you might still view your trace buffers by requesting a dump, the advantages of using the external writer are:

You do not need to code a component trace buffer find exit routine for IPCS processing.
Depending on the size of the trace data set, you can capture more trace data without using valuable system resources, such as central or auxiliary storage.

The following describes tracing through component trace using an external writer.

The programmer plans and sets up the user-defined control structures.
The installation establishes a procedure for the external writer in SYS1.PROCLIB.
The application defines itself to component trace with an external writer.
The operator starts the external writer.
The operator turns on the application's trace and connects the application to the external writer.
The system passes control to the start/stop exit routine to start tracing.
The application starts tracing by creating trace entries and placing them in trace buffers.
The application manages trace buffers using the external writer.
The operator turns off the application's trace; this action disconnects the application from the external writer.
The system passes control to the start/stop exit routine to stop tracing.
The operator stops the external writer.
The application deletes itself from component trace.
A diagnostician or systems analyst formats the trace data sets through IPCS.

Using an external writer involves a number of trace-related activities. The trace-related activities are:

Trace-related activity:	How to accomplish the activity:
Define the application to component trace allowing connection to an external writer	CTRACE DEFINE with the WTR and WTRMODE parameters
Start an external writer	An installation-written procedure in SYS1.PROCLIB and one of the following: TRACE CT operator command with the WTRSTART parameter On a TRACE CT operator command, a parmlib member with PRESET and WTRSTART parameters On a TRACE CT operator command, a parmlib member with the WTRSTART parameter On CTRACE DEFINE, a parmlib member with the WTRSTART parameter
Connect an external writer	An installation-written procedure in SYS1.PROCLIB and one of the following: TRACE CT,ON operator command and REPLY operator command with the WTR=wtrname parameter On a TRACE CT operator command, a parmlib member with PRESET and WTR parameters On a TRACE CT operator command, a parmlib member with the WTR parameter On CTRACE DEFINE, a parmlib member with the WTR parameter
Manage trace buffers	CTRACECS macro CTRACEWR macro ITTTBWC mapping macro
Disconnect an external writer	One of the following: TRACE CT,OFF operator command TRACE CT,ON operator command and REPLY operator command with the WTR=DISCONNECT parameter On a TRACE CT operator command, a parmlib member with the WTR=DISCONNECT parameter
Stop an external writer	One of the following: TRACE CT operator command with the WTRSTOP parameter On a TRACE CT operator command, a parmlib member with the WTRSTOP parameter

Starting the external writer Starting an external writer means preparing the external writer to receive requests and write trace buffers out to trace data sets. To start an external writer, the operator issues the TRACE CT command with the WTRSTART parameter. An external writer that has been started is said to be active.

To start an external writer and connect an application to it without operator intervention, specify a CTncccxx parmlib member on the PARM parameter of CTRACE DEFINE.

Connecting an application to the external writer: Connecting an application to an external writer means the application can write out its trace buffers to an active external writer. To connect to an external writer, the operator issues the TRACE CT and REPLY operator commands. To connect an external writer without operator intervention, you can specify the CTncccxx parmlib member on the PARM parameter of CTRACE DEFINE. For example, the application can issue:

CTRACE DEFINE,NAME=ABCD,WTR=YES,PARM=CTXABC04

Parmlib member CTXABC04 might look like this:

TRACEOPTS
WTRSTART(CTWDASD)
ON
WTR(CTWDASD)
ASID(ASID01)
OPTIONS ('option1,option2')

When you start and connect the component trace with an external writer, the system passes control to your start/stop exit routine. Once the start/stop exit gets control, it should set a flag in the application's control information to indicate that the application should start managing its trace buffers to be passed to the external writer.

Disconnecting an application from the external writer: Disconnecting an application from an external writer means that the application cannot write out its trace buffers to an active external writer. To disconnect an external writer, the operator issues the TRACE CT and REPLY commands.

Note: Turning the application's trace off causes an automatic disconnect of that application from the external writer. In normal processing there is no need to disconnect an application from an external writer. Simply turning the trace off will automatically cause a disconnect to occur.

When you disconnect the application from the external writer or stop the trace, the system passes control to your start/stop exit routine. Once the start/stop exit gets control, it should set a flag in the application's control information to indicate that the application no longer needs to manage trace buffers to be passed to the external writer.

Stopping the external writer: Stopping an external writer means any application trace requests sent to the external writer will not be written out to trace data sets. To stop an external writer, the operator issues the TRACE command with the WTRSTOP parameter.

If the application supports the external writer and either dynamically changes the buffer size or deletes buffers in a start/stop routine, then there may be a data integrity exposure when minimum options (MINOPS) is not supported. Component trace could possibly copy storage that is now allocated to another task because the buffer was deleted before copying was complete. Applications that fall into this situation could use TESTMODE=AVAIL to check the buffer's availability before deleting it, or not change the buffer size when the external writer is active. There is no integrity problem if MINOPS is supported and the buffer size does not change.

If you are running under z/OS® V1R8 or a later release, you may place your buffers above the bar. Each buffer can be as long as X'FFFFFFFF_80000000' bytes. Individual CTRACE entries remain limited to 64000 bytes in length.