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:
|
Connect an external writer | An installation-written procedure
in SYS1.PROCLIB and one of the following:
|
Manage trace buffers |
|
Disconnect an external writer | One of the following:
|
Stop an external writer | One of the following:
|
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.
CTRACE DEFINE,NAME=ABCD,WTR=YES,PARM=CTXABC04
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.
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.