Preface

Debugging problems is essentially an iterative process of hypothesis, test and conclusion that aims to eliminate the irrelevant and therefore focus on the probable causal area.

To engage this process successfully one needs to be equipped with an innate ability to think laterally coupled with sufficient knowledge of the environment in which the problem persists and above all else to be able to use the tools that extract information from the system under diagnosis.

This scenario applies as much to first level problem determination (PD) as it does to the software developer who is engaged in detailed analysis of his programs' behaviour.

Information and tools to aid first level problem determination is relatively accessible. Technical literature is available from IBM and books stores that will fulfil the needs of the first level PD analyst. For example, the reader is invited to consult the following IBM Red-book publications to achieve an all-round high-level technical appreciation of the OS/2 environment:

The Technical Compendium Volume 1 - Control Program

The Technical Compendium Volume 2 - DOS and Windows Environment

The Technical Compendium Volume 3 - Presentation Manager and Workplace Shell

The Technical Compendium Volume 4 - Application Development

The Technical Compendium Volume 5 - The Print Sub-system

The problem analysis level that is less well provided for is that which involves internal knowledge of the OS/2 operating system and its diagnostic tools. This is the level at which Service personnel, System Programmers and Software Developers work. It is this audience to which the OS/2 Debugging Handbooks are directed.

An inevitable consequence of working at a deep technical level is that the amount of information one could amass is vast. Given time constraints and the need to publish useable material before it became obsolete we had to make certain compromises for the first edition. The following principles guided us in making decisions about which material to include:

Material that is adequately documented elsewhere is referenced but not included.

Accurate reference documentation for the diagnostic tools and facilities available for OS/2 has been given priority over worked examples and OS/2 Internals reference material.

Internals information has centred around the base operating system - that is, the kernel.

We hope to remedy some of these short-comings in future revisions of this book and in companion volumes. Updates to the on-line version of this book will be made available via the Developer Connection CDROM.

The current printed edition contains full reference material for the following OS/2 System diagnostic facilities:

System Trace

System Dump

Kernel Debugger

In addition to these topics we have included an introductory guide to problem determination. This provides a resumé of the hardware and software environment and an introduction to using the dump formatter and kernel debugger.

Throughout this book we assume the availability of and familiarity with two co-requisite publications:

The Intel Pentium Family User's Manual, Volume 3: Architecture and programming manual, ISBN 1-55512-227-2, Intel order number 241430-003.

This should be consulted as the authoritative source for hardware architectural information.

This should be consulted for an overview of the internal operation and architecture of OS/2.

This book is supplied with a CDROM whose contents are:

• Sample exercises to accompany Volume 1, Introduction to Debugging. These take the form of system dumps of typical problems in application programs.

• On-line version of this book. This is slightly more up-to-date than the printed version and includes more worked examples. This is an .INF file and should be viewed using the OS/2 VIEW.EXE program. Much use has been made of hypertext links, which direct the user to the glossary. From the glossary it is possible to link to related material in other sections of the book.

• The OS/2 Problem Determination Package (OS2PDP), which includes the dump formatter, symbol files, and trace customiser (TRCUST).

Unless otherwise stated the material in this book may be assumed to be applicable to OS/2 Warp version 3.0 (ALLSTRICT Kernel).

As indicated above, work on this subject matter can never be complete. We intend build on and update the material in this edition. In order to address the areas in most need of attention we invite the reader to fill in the Reader's Comment Form with their suggestions.