Problem Determination Programmer's Guide: Difference between revisions
| (3 intermediate revisions by 2 users not shown) | |||
| Line 9: | Line 9: | ||
This book first provides conceptual and introductory information about OS/2 Warp Version 4 [[First Failure Support Technology/2]] (FFST). This sophisticated and powerful tool requires thoughtful planning and code instrumentation. These topics present planning, setup, and examples that are used for collecting and managing problem determination data. | This book first provides conceptual and introductory information about OS/2 Warp Version 4 [[First Failure Support Technology/2]] (FFST). This sophisticated and powerful tool requires thoughtful planning and code instrumentation. These topics present planning, setup, and examples that are used for collecting and managing problem determination data. | ||
Separate sections are devoted to understanding the aids that are provided for tracking, collecting, storing, and | Separate sections are devoted to understanding the aids that are provided for tracking, collecting, storing, and formatting problem determination data, such as traces, dumps, and error logs. | ||
After reading this book you should understand the benefits of FFST and know how to instrument your code. This allows you to take advantage of the technology and tools that are associated with problem determination data. You should also know how to use the APIs, trace, error logging, and dump functions. These functions retrieve, format, and analyze problem determination data. | After reading this book you should understand the benefits of FFST and know how to instrument your code. This allows you to take advantage of the technology and tools that are associated with problem determination data. You should also know how to use the APIs, trace, error logging, and dump functions. These functions retrieve, format, and analyze problem determination data. | ||
| Line 17: | Line 17: | ||
==Links== | ==Links== | ||
* [https://archive.org/download/IBMOS2Warp4ToolkitDocuments2/pdguide.inf pdguide.inf] (Sep 1996) | * [https://archive.org/download/IBMOS2Warp4ToolkitDocuments2/pdguide.inf pdguide.inf] (Sep 1996) | ||
* [https://komh.github.io/os2books/os2tk45/pdguide Web Book] (Sep 1996) | |||
==About This Book== | ==About This Book== | ||
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. | 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: | 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 | * collect problem determination data | ||
* define the types of data collected | * define the types of data collected | ||
* specify where to store the collected error data | * specify where to store the collected error data | ||
* override parameters on calls to the FFSTProbe function. | * 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. | 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. | 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. | ||
===Related Publications=== | ===Related Publications=== | ||
| Line 64: | Line 63: | ||
===Disclaimers=== | ===Disclaimers=== | ||
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user. | |||
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: | IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: | ||
IBM Director of Licensing | |||
IBM Corporation | |||
500 Columbus Avenue | |||
Thornwood, NY 10594 | |||
U.S.A. | |||
Asia-Pacific users can inquire, in writing, to the IBM Director of Intellectual Property and Licensing, IBM World Trade Asia Corporation, 2-31 Roppongi 3-chome, Minato-ku, Tokyo 106, Japan. | |||
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. | |||
===Trademarks=== | ===Trademarks=== | ||
The following terms are trademarks of the IBM Corporation in the United States or other countries or both: | The following terms are trademarks of the IBM Corporation in the United States or other countries or both: | ||
Latest revision as of 00:02, 8 May 2024
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
OS/2 Warp 4 consists of various products including OS/2 Warp Version 4, BonusPak, IBM's OS/2 implementation of Sun Microsystems, Inc.'s Java technology, VoiceType for OS/2 Warp, and networking products.
This book provides programmers with guide and reference information for collecting and managing problem determination data using OS/2 Warp Version 4.
This book first provides conceptual and introductory information about OS/2 Warp Version 4 First Failure Support Technology/2 (FFST). This sophisticated and powerful tool requires thoughtful planning and code instrumentation. These topics present planning, setup, and examples that are used for collecting and managing problem determination data.
Separate sections are devoted to understanding the aids that are provided for tracking, collecting, storing, and formatting problem determination data, such as traces, dumps, and error logs.
After reading this book you should understand the benefits of FFST and know how to instrument your code. This allows you to take advantage of the technology and tools that are associated with problem determination data. You should also know how to use the APIs, trace, error logging, and dump functions. These functions retrieve, format, and analyze problem determination data.
This book assumes that you have the IBM Developer's Toolkit for OS/2 Warp Version 4 installed and you are developing application programs. In the chapters of this book refer to the IBM Developers Toolkit simply as the Toolkit.
Links
- pdguide.inf (Sep 1996)
- Web Book (Sep 1996)
About This Book
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.
Related Publications
The following publications contain additional information about the OS/2 Warp Version 4 product:
- OS/2 Warp Version 4 CP Reference in the Toolkit
- OS/2 Warp Version 4 Command Reference in the Toolkit
- Trace document in the Serviceability and Diagnostic Aids folder if the folder is installed
- Trace Customizer in the Toolkit
- DMI Programmer's Guide in the Toolkit
- SystemView Agent Client Guide in the Tasks folder
Notices
September 1996
The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.
Copyright Notices
COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.
Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved."
(C)Copyright International Business Machines Corporation 1996. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
Disclaimers
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user.
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing IBM Corporation 500 Columbus Avenue Thornwood, NY 10594 U.S.A.
Asia-Pacific users can inquire, in writing, to the IBM Director of Intellectual Property and Licensing, IBM World Trade Asia Corporation, 2-31 Roppongi 3-chome, Minato-ku, Tokyo 106, Japan.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
Trademarks
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
- FFST
- First Failure Support Technology
- IBM
- OS/2
- OS/2 Warp
- OS/2 Warp Connect
The following terms are trademarks of other companies:
Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.