How to trace data streams

You can use the trace feature to capture data streams for analysis. Even data streams that were not optimized can be captured. Only one wraparound trace at a time can be active.

Wraparound data stream trace

The wraparound trace continues capturing data streams by wrapping to the top of the storage that you have allocated. This trace lets you continue capturing data streams until your target data stream is captured.

The wraparound trace is a powerful tool. The diagnostic wraparound trace provides valuable information for support personnel and customers.

To capture a large number of data streams or to leave the trace active for a long period of time to capture an error, use a wraparound trace.

How wraparound data stream trace works

An outbound or inbound data stream is captured only if it matches the selection criteria that you established with the trace. If no criteria are specified, all data streams are captured.

One set of environment statistics and options is captured for each of the following types of data streams:

• Inbound (before and after optimization)
• Outbound (before and after optimization)

The trace status is retained between Optimizer shutdown and startup. If the trace was started before shutdown, it will continue tracing data streams after startup. The wrap trace buffer is deleted at shutdown.

Data stream trace display panels

After a data stream has been captured, the panels that are listed in following table are available for your use:

From the Wraparound Data Stream Trace panel, you can perform the following actions:

• Start a trace
• Stop a trace
• Display a condensed list of traced data streams
• Print the captured information
• Delete a wraparound data stream trace

Even data streams that were not optimized can be captured for analysis.

Retention of entries at shutdown

If the COPOPT options file has been defined and allocated to CICS, the entries are retained (except the Trace Header) after the Optimizer is shut down. For more information about this feature, see Customizing-after-installation. This file is updated by the Monitor when any fields on this panel are changed.

Wraparound data stream trace status

The Wraparound Data Stream Trace panel displays the status of the wraparound data stream trace.

• Inactive

           The trace is not running, and there is no trace data to be examined.

• Started

           The trace has been started, and data streams are being captured.

• Stopped

           The trace has been stopped, and there might be trace data to examine.

Trace buffer allocation size

When a wraparound data stream trace is started, the Monitor sets aside a storage area to store any captured trace data. The trace buffer allocation size area is obtained above the 16 MB line.

Any amount from 1 through 9999 can be used. The amount of storage that you allocate must be at least twice the size of the Data stream storage size that you used on the Work Area Storage panel The default storage size is listed in following table:

The trace storage area is not released until the trace is stopped and the captured trace is deleted, or until no trace has been captured. If the Optimizer does not have enough storage area to store the trace, the trace is not started.

If you are using the XA option of CICS 1.7 or later in an MVS/ESA, OS/390, or z/OS environment, the trace storage area is obtained above the 16 MB line. Otherwise, the trace storage area is obtained from the CICS shared subpool in the CICS dynamic storage area (DSA). No data set is required, and no I/O activity will take place until requested.

If you are using CICS 3 or later, storage is obtained from extended DSA (EDSA).

Wraparound data stream trace start options

You can capture a data stream by leaving all start option fields blank, or by specifying one or more of the start options that are listed in following table.

The Transid, Termid, or Data Stream Error Code fields, as well as stop conditions, can be changed without stopping the trace, even if some data streams have been captured. If you overlay an old entry with a new entry, the old entry is replaced and only the new entry applies.

The Transid, Termid, and Data Stream Error Code entries can be generic. To indicate a generic entry, use an asterisk (*). For example, A*, CDC*, A0*, or VTA*.

Wraparound data stream trace stop conditions

The stop condition specifies when to stop the trace. Select a stop condition at the same time that you select your start options. To stop a wraparound data stream trace, specify one of the stop options in following table:

When you start a wraparound data stream trace, you can specify when the trace is to automatically stop capturing data streams. If you do not specify either stop condition (Stop when Data Stream Error Code or At Buffer Wrap), the trace continues to capture data streams until you stop it manually.

Wraparound data stream trace statistics

When a wraparound data stream trace starts, and at least one data stream has been captured, the lower portion of Wraparound Data Stream Trace panel displays the following information about the last data stream that was captured:

• Number that is assigned to the data stream (from 1 to 99,999)
• Termid
• Transid
• Outbound or inbound length before and after optimization

If an outbound data stream was excluded from optimization, before and after lengths will be the same.

Wraparound data stream trace (List) panel

When a wraparound data stream trace has been started, you can display a condensed list of the data streams that have been captured. The last captured data stream is displayed at the bottom of the list. The list is updated when new data streams are captured.

The data streams are numbered from 1 to 99,999. If an application or hardware error has been found in any data stream, the data stream is highlighted.

The Optimizer does not stop capturing data streams until one of the following actions occurs:

• The Stop options that you specified when starting the trace have been satisfied (the data stream error code was found, or the buffer wrap point was reached).
• You stop the trace, from this panel or from the Wraparound Data Stream Trace panel.

For each captured data stream, the following information is displayed on the Wraparound Data Stream Trace List panel:

• Number assigned to each data stream
• Data stream direction (In for inbound and Out for outbound)
• Length of the before data stream
• Length of the after data stream
• Termid of the data stream
• Transid of the data stream
• Time that the data stream was captured
• First six hexadecimal characters of the data stream

Scrolling to a specific data stream

The Num field on the very first data stream line can be modified. You can enter the number of any data stream to which you would like to scroll.

Scrolling through the list of data streams

Use F8 (or F20) to scroll down through the data and F7 (or F19) to scroll up through the data. You can only scroll through the list after the trace has been stopped. When the trace is active, the most recently captured data stream is displayed.

Displaying a wraparound data stream trace panel

Summary: In this task, you will display a Wraparound Data Stream Trace panel.

                   To display the Wraparound Data Stream Trace panel, perform the following steps:

1. Select option 3 on the Monitor Primary Menu.
2. Press Enter.
   The Data Stream Analysis Menu is displayed.
3. Select option 4.

4. Press Enter.
   The Wraparound Data Stream Trace panel is displayed.

   (3.4.0)                             3270 SUPEROPTIMIZER/CICS                     January 20, 2001
   Option. . ______                   Wraparound Data Stream Trace                 19:19:25
                                       CICSID:CICSMGF
   
    Trace action. . . . . . . . . . . . . _      1. Start Status. . : Inactive
                                                *. Stop
                                                *. List
                                                *. Delete
                                                5. Start diagnostic trace
    Trace buffer allocation size . . . .     100 K
    Termid . . . . . . . . . . . . . . .     ________
    Transid. . . . . . . . . . . . . . .     ____
   Data Stream Error Code . . . . . . .     ___
    Stop when data stream error code . .     ___ or At Buffer Wrap _ Y=Yes

Starting a diagnostic wraparound data stream trace

Summary: When you execute a diagnostic wraparound data stream trace, you can specify certain start options and a stop condition. Or, you can start a trace with no options or conditions specified. In this task, you will start a diagnostic wraparound data stream trace for BMC Customer Support.

                  To start a diagnostic trace for BMC Customer Support, perform the following steps:

1. Type 5 in the Trace action field.
2. Enter a value in one or more of the following start options, if desired (none are required):
   • Trace buffer allocation size
   • Termid
   • Transid
   • Data Stream Error Code
3. To use one of the Stop options to stop a trace automatically, type Y (for yes) in one of the following fields:
   • Stop when data stream error code
   • At Buffer Wrap
4. Press Enter.
   The Monitor starts a diagnostic trace, based on the start options that you specified. The message BMC 7102I Trace options set is displayed. Trace status changes to Started.

Starting a wraparound data stream trace

Summary: When you execute a wraparound data stream trace, you can specify certain start options and a stop condition. Or, you can start a trace with no options or conditions specified.

                   To start a wraparound data stream trace, perform the following steps:

1. Type 1 in the Trace action field.
2. Enter a value in one or more of the following start options, if desired (none are required):
   • Trace buffer allocation size
   • Termid
   • Transid
   • Data Stream Error Code
3. To use one of the Stop options to stop a trace automatically, type Y (for yes) in one of the following fields:
   • Stop when data stream error code
   • At Buffer Wrap

4. Press Enter.
   The Monitor starts a data stream trace that is based on the start options that you specified. Message BMC 7102I Trace options set is displayed. Trace status changes to Started.

   Warning

   Note

   The wraparound data stream trace can be restarted at any time. The trace does not have to be deleted before it is restarted.

Stopping a wraparound data stream trace

Summary: In this task, you will stop a wraparound data stream trace.

                   A trace can be stopped at any time. To stop a wraparound data stream trace, perform the following steps:

1. Type 2 in the Trace action field.
2. Press Enter.

The wraparound data stream trace is stopped when all data stream pairs have been captured. Trace status changes to Stopped or Inactive when the trace has stopped.

Displaying the wraparound data stream trace (List) panel

Summary: In this task, you will display the Wraparound Data Stream Trace (List) panel.

                  To display the Wraparound Data Stream Trace (List) panel, perform the following steps:

1. Type 3 in the Trace action field.

2. Press Enter.
   The Wraparound Data Stream Trace (List) panel is displayed. Following section shows a sample Wraparound Data Stream Trace (List) panel:

    (List)                           3270 SUPEROPTIMIZER/CICS                    November 30, 2001
   Option. . ______                 Wraparound Data Stream Trace                15:46:05
                                    CICSID:CICSMGF
   
   Start Trace. . . _               Status. . . : Stopped
   Actions are;   B=Before,   A=After,   E=Environment,   O=Option,   or P=Print
   Act      Num       Dir      Before       After       Termid        Transid       Time        Data
    _      00001      Out      1,210         685         A000         COPM        15:45:00   7EC71140401D
    _      00002      In       42            42          A000         COPM        15:45:09   7DC15C1140D6
    _      00003      Out      222           181         A000         COPM        15:45:09   F1C61140D51D
    _      00004      Out      0             0           A000         COPM        15:45:09
    _      00005      In       46            46          A000         COPM        15:45:15   7D4DC81140D6
   
   F1=Help F2=Keys F3=End F4=Return F7=Scroll Up F8=Scroll Down

In the Act field on each data stream line, you can enter one of the actions that are listed in following table:

To return to the Wraparound Data Stream Trace (List) panel from any panel, press F3 (or F15).

The Wraparound Data Stream Trace (Data Display) panel displays the inbound and outbound data streams. The following information is displayed on each line of the Wraparound Data Stream Trace (Data Display) panel:

• Hexadecimal displacement of the line
• Trace in hexadecimal
• Trace line translated into character display

Following section shows a sample Wraparound Data Stream Trace (Data Display) panel:

Displaying a specific displacement

To display a specific hexadecimal displacement, modify the Offset field. You can enter any hexadecimal characters from 0 to F.

The length of the data stream is displayed for your information.

Scrolling through the data

Use F8 (or F20) to scroll down through the trace and F7 (or F19) to scroll up through the trace. The default scroll value is ’0100’.

Displaying a before or after data stream

If the Wraparound Data Stream Trace (Data Display) panel is displaying a Before data stream information field, you can switch to an After data stream by changing the B in the word Before to A.

If the Wraparound Data Stream Trace (Data Display) panel is displaying an after data stream, you can switch to a before data stream by changing the A in the word After to B.

The Wraparound Data Stream Trace (Environment) panel displays the following information about the environment of the data stream that was captured:

• Operating system
• CICS environment
• Information about the terminal
• Lengths of the captured data streams
• Information about any errors that were found

If you are using VTAM 1.3 or later, the Location field is shown as Unknown. Following section shows the Wraparound Data Stream Trace (Environment) panel:

Following section shows the Wraparound Data Stream Trace (Options) panel with Optimization Control options that are used to process the data stream:

The wraparound data stream trace can be printed at any time after at least one data stream has been captured and the trace has been stopped. The trace is deleted at shutdown.

The printed trace will contain the following information for outbound and inbound data streams:

• Wraparound Data Stream Trace panel 
• Environment panel
• Options panel
• Data Display panel  with the data stream
  
  • Before optimization
  • After optimization (only if no errors were found)

SUPEROPT provides you with a number of ways to print the data streams that you captured with the Wraparound Data Stream Trace option. You can select from the options that are listed in following table:

If you type a nonblank character in the Print Trace field, an entry is required in one of the following fields:

• VSAM File ID
• Printer ID
• DCT ID

To print the Wraparound Data Stream Trace, use the print options that are in above table.

Performing a wraparound data stream trace (List) action

Summary: In this task, you will perform one of the Wraparound Data Stream Trace (List) actions.

                   To perform one of the Wraparound Data Stream Trace (List) actions on a specific data stream, perform the following steps:

1. Type one of the following actions in the Act field of the data stream that you want to display:
   • B for before
   • A for after
   • E for environment
   • O for option
   • P for print
   • C for TCTTE (diagnostic trace only)
   • R for RPL (diagnostic trace only)
2. To select a data stream, perform one of the following actions:
   • Type the number of the data stream you want to select in the Num field. (For example, to select data stream 46, type 00046 in the Num field.)
   • Scroll through the list of data streams, using F8 (or F20).
3. Press Enter.
   The action is performed on the data stream that you selected.

Printing the entire wraparound data stream trace

Summary: In this task, you will print the entire wraparound data stream trace.

                  To print the entire wraparound data stream trace, perform the following steps:

1. Type a nonblank character in the Print Trace field.
2. Type an entry in one of the following fields:
   • VSAM File ID
   • Printer ID
   • DCT ID
3. Type a trace header in the Trace Header field. The trace header can be up to 20 characters.
4. Type one of the following values in the Uppercase field to indicate the type of printing that you prefer:
   • Y (print uppercase characters only)
   • N (print mixed-case characters)
5. Press Enter.
   The print job is sent to the output media that you selected.

Printing a portion of the wraparound data stream trace

Summary: In this task, you will print a portion of the wraparound data stream trace.

                   To print a portion of the wraparound data stream trace, perform the following steps:

1. Type 3 in the Trace action field.
2. Type a value for one of the following fields:
   • VSAM File ID
   • Printer ID
   • DCT ID
3. Type a trace header in the Trace Header field.
   The trace header can be up to 20 characters.
4. Type one of the following values in the Uppercase field to indicate the type of printing that you prefer:
   • Y (print uppercase characters only)
   • N (print mixed-case characters)
5. Press Enter.
   The Wraparound Data Stream Trace List panel is displayed.
6. To select a data stream, perform one of the following actions:
   • Type the number of the data stream that you want to print in the Num field. (For example, to select data stream 46, type 00046 in the Num field.)
   • Use F8 (or F20) to scroll through the list of data streams.
7. Type P in the Act field of each data stream that you want to print.
8. Press Enter.
   The print job is sent to the output media that you selected.

Deleting a wraparound data stream trace

Summary: The Monitor will not delete a trace unless directed to do so. If you do not delete the trace, the trace is deleted when the Optimizer is shut down. In this task, you will delete a wraparound data stream trace.

To delete a wraparound data stream trace, perform the following steps:

1. Type 4 in the Trace action field.
2. Press Enter.

The trace is deleted. The trace status changes to Inactive when the trace has been deleted.