Requesting data asynchronously from a monitor program

You can create a monitor program that requests an asynchronous buffer, which records trace data as trace events occur. Monitor programs can call the READA function to read data asynchronously from an OPn buffer.

About this task

Begin program-specific programming interface information.Db2 can buffer all IFCID data that is activated by the START TRACE command and pass it to a monitor program on a READA request. The IFCID events include the following types of information:
  • Serviceability
  • Statistics
  • Accounting
  • Performance
  • Audit data
  • IFCIDs defined for the IFI write function

Procedure

To create a monitor program that requests asynchronous data, use the following approaches:

  • Issue a START TRACE command from the monitor program and specify a buffer location to start the collection of asynchronous data.
    FL 504 Start of changeYou can specify a generic value or specific online performance monitor destinations, OPn, where n is any integer in the range 1–16.End of change
    After the trace is started, Db2 collects and buffers the information as it occurs.
  • Specify the generic OPX option in the initial START TRACE command to avoid conflicts with other traces or programs.
    When OPX is specified, the instrumentation facility assigns the next available buffer destination slot and returns the OPn destination name to the monitor program. The program can use subsequent START TRACE or MODIFY TRACE commands to direct the data to the destination specified by the instrumentation facility.
  • Issue READA requests to move the buffered data to the monitor program.
  • Use specific initial OPn destinations in the following situations:
    • When you plan to start numerous asynchronous traces to the same OPn destination. To do this, you must specify the OPn destination in your monitor program. The OPn destination that is started is returned in the IFCA.
    • When the monitor program specifies a particular monitor class (defined as available) together with a particular destination (for example OP7) to indicate that certain IFCIDs are started. An operator can use the DISPLAY TRACE command to determine which monitors are active and what events are being traced.
  • Configure the monitor program to use large buffers and specify small WBUFBC values to prevent data loss.
    Data loss occurs when the buffer fills before the monitor program can obtain the data. Db2 does not wait for the buffer to be emptied. Instead, it informs the monitor program on the next READA request (in the IFCARLC field of the IFCA) that the data was lost.
  • Display the asynchronous data on a terminal by creating a program that uses the following logic:
    1. Initialize.
    2. Use GETMAIN to obtain a storage area equal to the BUFSIZE value in the START TRACE command.
    3. Issue the following command through IFI to wake up this routine by a POST whenever the buffer is 20% full: 
      START TRACE=ACCTG DEST=OPX
    4. Check the status in the IFCA to determine if the command request was successful.
    5. WAIT for the buffer to be posted.
    6. Clear the post flag.
    7. Issue a READA request to obtain the buffer data.
    8. Check the status of the READA request.
    9. De-block in the information.
    10. Display the information on the terminal.
    11. Loop back to the WAIT.End program-specific programming interface information.