Places to Instrument

The following list contains situations and places in your code you should consider for instrumentation:

• When your code generates an error return, create an error log entry for the error condition that caused the error.

• Some programmers use Print Debug and Print File for testing code. These instructions print certain variables and messages at various code failure points. Convert the Print Debug and Print File instructions to calls to the FFSTProbe API. The system disables the Print Debug and Print File functions after you install your code.

• When you expect return codes, create an error log entry when you receive unexpected return codes.

• In environment situations (circumstances that are not necessarily program errors but are worthy of creating an error log entry). For example, resource shortages, time-out conditions, system-hang conditions, or lost physical connections.

• In cleanup functions, your code may be tolerant of potential errors and may do some error recovery. The cleanup functions in your code are candidates for logging if the recovery signifies an important event.

Consider that the number of log entries and the size of entries you log could cause too much information to be logged. Creating excessive error log entries can cause the error log to wrap. This causes previously logged information to be overwritten. One of the most frequent questions that are asked about FFST is where and when to use it. When instrumenting your product, you should consider several places:

• Exception Paths

  Many programmers already take some actions in various exception conditions. These actions often include cleaning up execution environments, closing files, and ending the program. Your code should call the FFSTProbe API to create an error log entry that contains the following information:

  • the program or module that failed -
    why the failure occurred
    -
    what corrective actions to take.
    
    Incorrect Conditionals (for example, switch case)

    As developers write programs, they make assumptions of what can or cannot happen, and add various conditionals and execution blocks to programs.

    Conditionals that are not valid are ideal candidates for a call to the FFSTProbe API to log these failures. By calling the FFSTProbe function at these points, you can quickly and accurately pinpoint the failure and capture the associated data at the time of failure.

    
    External Calls

    OS/2 Warp Version 4 does not expect calls to external programs to fail. However, unexpected return codes, when not handled, can result in program failure. Your code should call FFSTProbe after each external call that results in an unexpected return code.

    Some development groups use someone other than the developer instrument all calls. Other groups spend more time anticipating the potential problem areas and placing probes only in those areas. Your code should do what is achievable for the current circumstances. You should then evaluate how well your calls to FFSTProbe work before you begin the next development cycle.

    For FFSTProbe API calls to be useful in debugging a problem, the calls must specify:

    • A unique probe ID 
      Descriptive text explaining the problem
      
      Data that is relevant to the failure
      
      Instructions on how to resolve the problem if appropriate.

      With well-instrumented code, several benefits of using the FFSTProbe function are evident. You can use FFST to capture error information. You can also identify areas in your code that did not cause the problem. If instrumented code made no calls to FFSTProbe, you can focus on code without calls to FFSTProbe.

      Your code should not call the FFSTProbe function inside a loop. Call FFSTProbe only once per error situation. Repeated calls may cause system performance problems and cause wrapping of FFST data by storing unnecessary data.

      Problem-prone components in products are good candidates for the FFSTProbe function.

      Your decision about using instrumentation depends on the possible errors and the cost of solving an error.

      ---

      [Back: Deciding How and Where to Place Calls to FFSTProbe API]
      [Next: Deciding What Data You Want to Collect]