PDGuide - Guide to Instrumenting Your Code

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

Code instrumentation improves problem analysis. Instrumented components of OS/2 Warp Version 4 use First Failure Support Technology (FFST) and trace. This chapter defines the required steps for instrumentation, and things you should consider before you instrument your code. This chapter also tells you what to expect when you use the FFSTProbe API and trace utility.

Introduction to FFST Instrumentation

FFST is a programming concept that uses a set of software tools and services to capture error information at the time of a code failure. You view the error information using system error log or PM Dump Facility dump formatter to determine the cause of the problem. You capture error information by placing a call to the FFSTProbe API in your code. You instrument your code by calling FFSTProbe and specifying which data to collect.

When your properly instrumented code encounters an unsuspected or unrecoverable error, the code immediately calls the FFSTProbe API to capture failure related information. Your code specifies the parameters to capture data when calling the FFSTProbe function. The system creates an error log entry each time your code calls the FFSTProbe function. The log entry will contain the information your code specifies in the call to FFSTProbe. After the call, the system returns control to your code unless the system triggered a system dump. System dumps automatically restart the system. Additional error information can be collected by using a Probe Control Table (PCT) entry. System dumps are triggered by using PCT entries. The captured information that is contained in the error log entry can include event trace data, program error information, or user-defined data.

Therefore, FFST consists of a collection of functions, commands, and utilities within the Problem Determination Tools folder. Use the utilities to do the following:

• collect problem determination data
• define the types of data collected
• specify where to store the collected error data
• override parameters on calls to the FFSTProbe function.

Summary of Functions and Interfaces, provides an overview of the interfaces to FFST. Problem Determination APIs, provides descriptions of the API functions.

This chapter provides the information you need to instrument your code. It may be helpful to have the OS/2 Warp Version 4 Tools Reference document available for reference while using this book. The associated references are available on the Toolkit CD ROM.

Benefits of Instrumenting for FFST

Instrumentation is key to providing adequate code serviceability. If problems occur, instrumented code allows you or service personnel to take full advantage of the FFST technology in OS/2 Warp Version 4. The system records problem determination data with no user or additional programmer intervention. Instrumentation decreases the need for reproducing user failures. System dumps and process dumps however do require intervention and problem reproduction.

The captured information that is recorded in the error log is essential to problem solving. An error log entry contains information that indicates the failing product, and the time the error occurred. By analyzing the captured information, you can determine the failing components, diagnose the causes of the error, and correct the problems.

Planning for Instrumenting Your Code

       Defining Vital Product Data (VPD)
       Deciding How and Where to Place Calls to FFSTProbe API
           Places to Instrument 
       Deciding What Data You Want to Collect
           Error Types to Consider 
       Ways to Collect Data
           FFST Dump Data
               Process Environment Data
               System Process Status Data
               Trace Data
               User Storage Data
               Additional Error Log User Data
               FFST Dump Process Errors
               Process Dumps
               System Dumps 

Coding the FFSTProbe Functions

       Direct Calls
       Using Macros to Call the FFSTProbe Function
       Using Subroutines to Call the FFSTProbe Function 

Creating Template Files

       Why Template Files Are Important 

Defining Trace Information Format

       Creating Trace Entry Formatting Directives 

Creating DMI MIF Files

       How to Install Your Software Product 

Examples of Code when Instrumenting for FFST and Trace

       Example of an Application Program Using a Subroutine
       Creating an Error Record Template Input File
           Template File Tips 
       Message Input File Example
       MIF File Example