PDGuide - Controlling FFSTProbe Calls

Problem Determination Programmer's Guide
Introduction to Collecting and Managing Problem Determination Data Guide to Instrumenting Your Code Controlling FFSTProbe Calls Viewing and Analyzing Error Log Entries Analyzing Performance and Debugging Problems Using Trace Capturing and Saving Failure-Related Information through Dumps The Desktop Management Interface Summary of Functions and Interfaces Problem Determination APIs

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

After you install your code on the system, you can choose to capture data other than that specified on the call to the FFSTProbe function. This section describes how to temporarily change the values that FFSTProbe uses while your code is running. This eliminates the need to change the parameter values and recompile your code.

Controlling FFSTProbe

First Failure Support Technology (FFST) provides graphical user interfaces (GUIs) that are used to control how the FFSTProbe function captures information.

You use the FFST commands or the user interface icons in the Problem Determination Tools folder.

FFST provides the following user interfaces:

• FFST Setup icon
• FFSTCONF command

You can view and change the FFST setup information by using the FFSTCONF command. You can also update and view probe control table (PCT) information through the setup GUI. You can control probes from the SYSLOG utility by using the Tools menu option from any details window and selecting the Modify Entry Collection option.

Using FFST Setup (FFSTCONF)

You can use the FFST setup utility to define the following configuration information:

• where to store dump files
• total maximum size for all FFST files in kilobytes (KB)
• whether you allow files to be wrapped
• whether you allow files to be appended.

The FFST setup contains the following configuration information:

• Information that is required for FFST data collection
  • Location of dumps, space for dumps, and so on -
  • Suppression of calls to groups of calls to FFSTProbe
• Information that is required to control FFST outputs (Probe Control Table Configuration)

The system saves your updated configuration information. FFST can dynamically start using the new options when you are finished with the utility.

You can use the FFSTCONF command or select the FFST Setup icon in the Problem Determination Tools folder to access the FFST Setup window (FFST Setup Window).

FFSTSetupWindow

You use the FFST Setup window to maintain information dealing with FFST files. The information specifies:

• where the files reside
• total maximum size for all FFST files
• whether the file should wrap when the space is full
• how to control duplicate dumps
• probe suppression for a product.

The options on the FFST Setup window are:

File

which uses the Printer Setup, Print, and Exit functions.

Actions

which has two options:

Dumps takes you to the FFST Dump Files Summary window, where you can select a dump to view using the PM Dump Facility dump formatter.

PCT takes you to the PCT Summary window, where you can view or edit individual calls to FFSTProbe (see #Probe Control Table (PCT) User Interface).

The following actions are descriptions of the fields on the FFST Setup window. FFST dump management uses the fields to control the FFST files by defining the storage size and characteristics.

FFST Files Directory

This field specifies where to keep files that FFST creates. You can change the displayed pathname or select a new pathname. To select a new pathname, you can enter the new path name in the entry field or click on the list box selector to bring up a list of pathnames and drives. Then click on a new pathname or drive. To move up in the file tree, click on the double dot (..) entry. The default pathname is <boot-drive>\OS2\SYSTEM\RAS.

Space for FFST Files

Use this field to specify the disk storage space for FFST files. Note that the size is in kilobytes (KB). The default size is 1024 (1 MB). The number of files the system keeps depends on each file size, and on the total space that is available for FFST files. If an FFST dump exceeds the specified size, the system stores only part of the dump. The dump file information contains the reason for the partial dump and the stored parts of the dump. You will see this information when you display the dump file.

File Wrap

Select the ON value to overwrite old dumps when the specified dump file is full. Note: if this option is ON, it will not overwrite dump files that are saved by the Save Output choice from the PM Dump Facility dump formatter Files menu.

Keep Duplicate Dumps

When this option is ON, the system keeps each dump that the call to FFSTProbe creates, even when the system previously stored a dump.

If this option is not used (OFF), the system requires FFST to check all the dump files. FFST checks to ensure that a dump file does not exist for this call to FFSTProbe. When you use this option, processing is slower than normal processing. Use this option to control runaway probes that create unneeded dumps that take up disk space.

Even though the snapshot trace files are separate physical files, they are part of the FFST dump file so this option also affects them. This option works in conjunction with file wrap option.

Probe-Suppression Entry Summary Area

This area displays the DMI triplet of each product for which calls to FFSTProbe are to be suppressed. To start suppressing calls for your product, click on the Add push button at the bottom of the window. The Probe Suppression Entry window appears so that you can specify your product information.

Probe Suppression Entry Window (Add or Change Functions)

The Probe Suppression Entry window (Probe Suppression Entry - Add Window) appears when you select the Add or Change push buttons from the FFST Setup window. This window uses the DMI triplet for your product to control an entire group of calls to FFSTProbe within your product. Specifically, FFST uses the following DMI information:

• Vendor Tag
• Tag
• Revision

ProbeSuppressionEntry-AddWindow

The differences among the Add, Change, and Delete screens are:

Add

Title bar reads "FFST - Probe Suppression - Add", and all fields are empty. You can add required information.

Change

Title bar reads "FFST - Probe Suppression - Change", and all fields contain information about the selected entry. You can change required information.

You can click the list box selector that is located on the right side of each entry area or enter the information directly. When you click on the list box selector, all values currently stored in the PCT will be displayed. You can select the desired item from the list.

Delete

Used to delete a group of probes from Probe Suppression. This will enable information logging when calling FFSTProbe for these probes. The system will request a confirmation that you want to delete suppression.

Probe Control Table

When your code calls FFSTProbe, FFST generates the requested outputs such as dumps or log entries. These outputs can be dynamically controlled by defining an entry in the Probe Control Table (PCT). Options that are specified in a PCT entry override all other options. You can use PCT entries to do the following:

• Control the individual calls to FFSTProbe by enabling or disabling them
• Specify whether FFST and System Dump information is to be collected
• Specify whether system process information is to be collected
• Specify whether system environment information is to be collected
• Dynamically request additional system information that is not requested in the call to FFSTProbe.

Each PCT entry consists of five identifiers:

• DMI_vendor_tag
• DMI_tag
• DMI_revision
• Module identifier name
• Probe ID

The entries in the PCT describe what is to be done on the call to FFSTProbe:

• You cannot use duplicate entries in PCT
• You cannot use wildcards for identifiers

The PCT mechanism looks for specific entries that match all five identifiers. If the system cannot find a match for the entry, it ignores the probe control entry. The PCT entry makes the final decision about what to do. The entry can overwrite parameters that are specified in the configuration and change the actual call to FFSTProbe.

FFST provides no default PCT entries.

Note: It is important to understand that the Probe Control Table is used to control individual calls to FFSTProbe and that Probe Suppression is used for an entire group of calls within a product.

Probe Control Table (PCT) User Interface

Probe Control Table Summary Window

Use the Probe Control Table to control individual calls to the FFSTProbe function.

Access the Probe Control Table by entering the FFSTCONF command, or by clicking on the FFST Setup icon in the Problem Determination Tools folder. When the FFST Setup window appears, select the Actions option and choose PCT.

You can use the following window to view all the defined PCT entries.

After you select an entry on the window, use the following action-bar items.

File

uses the Printer Setup, Print, and Exit functions.

View

displays the details of the entry.

Edit

lets you add an entry; change details of an entry; or delete an entry.

Probe Control Table (PCT) Entry Add or Change Summary Window

Use the Probe Control Table Entry Summary window (FFST Probe Control Table Entry Summary Window) to either add or change individual calls to the FFSTProbe function in a product.

Use the options on the Probe Control Table window to capture information that was not requested in the original call to the FFSTProbe function. Use the PCT options to specify system process information (PSTAT) or process environment information not in the parameters of the original call. You can also capture trace information, capture a system dump, and capture a process dump through the PCT for a specific FFSTProbe call. The system uses PCT values if the parameters on the FFSTProbe call and PCT are different.

For the PCT values to be used, the Enable Probe box must be "checked." The Enable FFST Dump box can be "checked" to have a FFST dump generated by the probe. The Enable FFST Dump box must be "checked" before the Capture Trace Snapshot, Capture Process Dump, Capture System Processes, or Capture Process Environment data will be captured. To capture a system dump you only need to "check" the Enable Probe and the Capture System Dump boxes.

FFST Probe Control Table Entry Summary Window

The following list defines the fields on the FFST Probe Control Entry Summary window:

Vendor Tag, Tag, and Revision

This is the VPD information for your product that is stored in DMI.

Module and Probe ID

Parameters on the call to the FFSTProbe function that identify the individual call.

Enable Probe

Used to enable or disable (turn on or turn off) the individual call to FFSTProbe.

Enable FFST Dump

Used to specify whether to save FFST Dump information for the individual call.

Capture Trace Snapshot

Used to collect trace data if your code did not specify trace in the original call to FFSTProbe.

Capture System Dump

Use this option to perform a system dump for calls to the FFSTProbe function. Note that the system restarts after storing the system dump information.

Capture Process Dump

Use this option to allow the system to capture process dump data. You can view the process dump data when you format the FFST dump associated with this probe ID.

Capture System Processes

Used to capture information about all the processes and threads that are running on the system. This information is similar to the PSTAT information that is viewed by using the PSTAT command. For more information about the PSTAT command, refer to the OS/2 Warp Version 4 Command Reference.

Capture Process Environment

Used to capture the values of environment variables for the process.

You access this window by using the following:

• From the PCT summary window, select an entry and click on either the Details or Change push button.
  • Details - Displays the details about the selected entry. You can only view the information.
  • Change - Displays the selected entry and allows information to be changed.
• From the PCT summary window, select Add, or Change from the Edit options.

All fields are empty, and you add information as required.

• From the SYSLOG utility, use the Tools menu-bar option from any details window and select the Modify Entry Collection option.

All fields contain information about the selected entry. You can change the information. If an entry is not in the PCT file, the system displays the default settings.

You cannot use wild card characters for Vendor Tag, Tag, Revision, module name, or probe ID. When you add a new entry, the system checks the PCT for duplicate entries.