Preparing CTRACE controls and resources

You must prepare CTRACE controls and resources before using it for trace data.

1. Decide whether to write CTRACE data to trace data sets (recommended) or keep CTRACE data in memory buffers only.
2. If you wish to use trace data sets, perform these steps.
   1. Decide whether to create one trace data set for all WebSphere Application Server activity on a single z/OS system or separate trace data sets for each cell or WebSphere Application Server release.

      Trace data sets cannot be shared between z/OS systems; each system should have its own trace data sets.

   2. Choose names for the trace data sets.

      To simplify external writer setup, include the z/OS system name in the data set name.

      Recommendation: For a single trace data set for all WebSphere Application Server activity, use something similar to SYS1.sysname.WAS390.CTRACE.

   3. Allocate a trace data set on each z/OS system.
      Best practice: Do not specify DCB parameters RECFM, LRECL, or BLKSIZE; the external writer will allocate them with record format VB and a system-optimal blocksize and logical record length. For trace data sets on disk, you should use a minimum of 10 cylinders (3390). Secondary extents are ignored unless the NOWRAP option is specified when the external writer is started. For example:

      //	EXEC PGM=IEFBR14
      //TRACE DD DSN=SYS1.MVSS14.WAS390.CTRACE,UNIT=3390,VOL=SER=HPK19A,
      //   SPACE=(CYL,(20,0)),DISP=(NEW,CATLG),DCB=DSORG=PS

   4. Choose a job name for the external writer.

      Recommendation: Use BBOWTR if the same trace data set is to be used for all WebSphere Application Server activity on each z/OS system.

   5. Create the external writer cataloged procedure.
      1. Copy member BBOWTR from the WebSphere Application Server for z/OS product directory /util/zos/JCL/ to SYS1.PROCLIB or another procedure library defined to the master scheduler.
      2. Rename the procedure to the external writer job name that you chose.
      3. Customize the cataloged procedure by providing your trace data set name where indicated.
      4. If the cataloged procedure will be shared among several z/OS systems, make sure that the trace data set DD statements point to the appropriate trace data sets on each system.
   6. Choose a system user ID under which the external writer started task will run.
      This user ID must have read/write access to the trace data sets; you may wish to use an existing started task user ID such as the default started task user ID for your system. Use the following RACF® command or equivalent to cause the external writer cataloged procedure to run under the started task user ID:

      RDEFINE STARTED external_writer_procname.* STDATA(USER(system_user_ID)) TRACE(YES)

      The external writer started task should run with at least as high a dispatching priority as the WebSphere Application Server address spaces that will use it for tracing.
   7. Start the external writer to verify that the previous steps were performed correctly.
      Enter the following MVS™ console command:

      TRACE CT,WTRSTART=external_writer_procname

3. Create a CTRACE parmlib member.
   1. Copy member BBOCTI00 from the WebSphere Application Server for z/OS product directory /util/zos/JCL/ to a data set in your system parmlib concatenation.
   2. Rename the parmlib member to CTIBBOxx, where xx is a two-character suffix to be associated with the external writer.

      This is the value that will be specified during WebSphere Application Server for z/OS customization.

   3. Customize the CTIBBOxx parmlib member to indicate whether trace data sets and an external writer are to be used and, if so, whether the external writer should be started automatically when WebSphere Application Server activates the CTRACE.
4. If you plan to use separate trace data sets for different WebSphere Application Server cells or releases, repeat all of these steps while choosing a new external writer name and parmlib member suffix for each.