The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis

Chapter 6. Collecting Supporting Documentation

This chapter documents product implementation information provided by the graPHIGS API for collecting support documentation. See "Notices" for information on the use of product implementation information

If you decide that your problem is caused by the graPHIGS API, you need to gather supporting documentation so that IBM can correct your problem. This chapter focuses on collecting the necessary information. For more information on tracing the graPHIGS API gateway daemon see "Using the Trace Facility"

The graPHIGS API Trace Facility

Facilities

The graPHIGS API provides an internal tracing capability to assist in isolating problems. This facility enables you to track the internal flow at the component level, as well as at key internal processing points. The resulting trace file can be used either to help isolate the routine generating the error, or as part of the data submitted to IBM in your problem report.

Background

A few terms need to be defined before you start to use the trace facility. The term shell refers to the graPHIGS API shell that is linked with your application. The term nucleus refers to the graPHIGS API nucleus, which may or may not be linked with your application. If the nucleus is linked with your application, it is called a private nucleus If the shell is connected to a nucleus that is running as a separate process, it is called a remote nucleus For more information on the graPHIGS API shell/nucleus concept, see The graPHIGS Programming Interface: Understanding Concepts

Specification

Tracing is controlled through the trace control word, a fullword integer that defines the kind of trace produced. If the shell is to connect to a private nucleus, trace control may be specified through:

The Internal Trace Contol (GPTRCE) subroutine (see The graPHIGS Programming Interface: Subroutine Reference for more information)

A default specification in the External Defaults File (EDF) or Application Default Interface Block (ADIB) (see "Setting Trace Defaults")

If the shell is to connect to a remote nucleus, trace control for the shell is specified the same way as listed above. Trace control for the remote nucleus may be specified as follows:

Through a default in the External Defaults File (EDF) in the working directory of the remote nucleus (the current directory of the user who starts the nucleus).

Note: The default specification must be set up before starting the remote nucleus.

By specifying a parameter on the command to start the remote nucleus that will override what may have been set in the EDF file. See The graPHIGS Programming Interface: Technical Reference for a complete discussion on remote nuclei.

Trace Control Word

By default, the trace control word is set to 0 , which means that tracing is turned off. The trace control word has the following format:

Byte 0

Flags

1... ....

Set to 1 to make the trace word unchangeable. If this bit is set, any further changes to the trace word is ignored, including subsequent subroutine calls to GPTRCE

This bit can be used to "force" a setting of trace (typically using a default specification) This may be of use if an application already contains GPTRCE subroutine calls and if the source of the application is not readily available.

A trace word with this bit set in the user-defined External Defaults File (EDF) takes priority over any trace word set in the Application Default Interface Block (ADIB) This allows the user control over the application setting of trace. See "Setting Trace Defaults" for more information.

Specifying a parameter to initiate trace on the command to start a remote nucleus will override the trace word set in the External Defaults File (EDF).

Reserved

Byte 1

Reserved

Byte 2

Trace Qualifier - reserved

Byte 3

Trace Level

0000 0000

Stop component and data entry

Start trace of component entry and exit

Start trace of data entry and exit

Note: Large quantities of trace output may be generated when the trace facility is used.

Format of Trace File Output

The trace file output for a remote graPHIGS API nucleus does not provide you with meaningful data. It is provided only to supply additional information for reporting a problem to IBM.

The beginning of each trace file for a shell contains a number of standard entries including the trace control word, the graPHIGS API defaults table contents, and additional information. The following example illustrates the format for standard data:

Figure 6-1. Format of Standard Data for Trace File Output

+--------------------------------------------------------------------------------+
|                                                                                |
| ORIGIN - /u/gus                                                                |
|                                                                                |
| TRACE WORD = '00000001'X   BUILDID = V2R1.0                                    |
|                                                                                |
| AFMTDFT  - GENERAL DEFAULTS TABLE COMMON SECTION                               |
| 20024BF8                        44465420  00000000    *        DFT     *       |
| 20024C00    20025108  41040100  00000064  00000001    *  Q A      d    *       |
| 20024C10    00000064  20025110  00000000  00000000    *   d  Q         *       |
| 20024C20    20025110  00000001  0000FFEC  0000FFEC    *  Q             *       |
| 20024C30    00004000  00000020  00000001  00000000    *  @             *       |
| 20024C40    00000000  00000000                        *                *       |
|          - SUBSYSTEM SPECIFIC DEFAULTS                                         |
| 20024C48                        00000000  20202020    *                *       |
| 20024C50    41464D54  52414345  41464D44  45465320    *AFMTRACEAFMDEFS *       |
| 20024C60    41464D30  30303031  41464D54  52414345    *AFM00001AFMTRACE*       |
| 20024C70    50524F46  494C4520  41464D44  45465320    *PROFILE AFMDEFS *       |
| 20024C80    41464D55  54312020  20202020  20202020    *AFMUT1          *       |
| 20024C90    20202020  20202020  20202020  20202020    *                *       |
| 20024CA0    20202020  20202020  20202020  20202020    *                *       |
| 20024CB0    20202020  20202020  20202020  41464D54    *            AFMT*       |
| 20024CC0    52414345  20202020  20202020  20202020    *RACE            *       |
| 20024CD0    20202020  20202020  20202020  20202020    *                *       |
| 20024CE0    20202020  20202020  20202020  20202020    *                *       |
| 20024CF0    20202020  20202020  20202020  20202020    *                *       |
| 20024D00    50524F46  494C4520  20202020  20202020    *PROFILE         *       |
+--------------------------------------------------------------------------------+

Trace output begins with the origin, the trace control word, and the graPHIGS API level identification. The origin is the path in which the process is currently running. The file also produces a formatted listing of the graPHIGS API defaults table.

When the appropriate level of tracing is enabled, one or more trace records are created for each entry and exit at the specified level(s)

Format of the Trace Record

Each trace record contains the following information:

Event Sequence Number

While trace is active (that is, while the trace control word is not 0), each module entry and exit is counted as a "trace event" Each event is assigned a sequence number (starting at 1) which is listed in the trace output.

Trace Record Type

A mnemonic is used to indicate the type of trace record, as follows:

CPNIN: shows that a graPHIGS API component has been entered to perform the function listed.
CPNOUT: shows that a graPHIGS API component has exited after performing the function listed.
TRDIN: shows the input parameters being traced within a graPHIGS API component.
TRDOUT: shows the return parameters being traced within a graPHIGS API component.

Trace Explanation

The contents of the trace explanation vary according to the trace record types, as follows:

CPNIN, CPNOUT

Trace explanation contains:

The Request Control Parameter (RCP) in mnemonic and hexadecimal format

An interpretation of the RCP.

Setting Trace Defaults

The user may specify trace default values through an external file containing the User Default Specifications (UDS) or by the application programmer in an Application Default Interface Block (ADIB) Priorities of the trace word are discussed under "Trace Control Word"

User Default Specifications (UDS) Processing

User Default Specifications (UDS) are accessed through a file called the External Defaults File (EDF). These default specifications appear at the top of the trace file, and can be specified without compiling or rebuilding the application.

The External Defaults File (EDF), which contains records consisting of the User Defined Specifications, must be named PROFILE or must be specified in the gPPROFILE environment variable. When the Open graPHIGS (GPOPPH) subroutine is called, or when a remote graPHIGS API nucleus is started, the graPHIGS API searches for a PROFILE in this order:

gPPROFILE environmental variable

The gPPROFILE environment variable allows you to use as the External Defaults File (EDF) an alternate PROFILE or a PROFILE not in your current directory.

If the gPPROFILE environmental variable is defined as a valid file name, then that file is used as the External Defaults File (EDF). If the gPPROFILE environmental variable is defined as a valid directory name, then that directory is searched for a PROFILE. If a PROFILE is found, then it is used as the External Defaults File (EDF).

If the gPPROFILE environmental variable is not defined, is defined with an invalid file name or directory name, or there is no PROFILE in the defined valid directory name, the search continues.

For more information on setting environment variables, see the AIX Commands Reference for IBM RISC System/6000

Current directory

The current directory is searched for a PROFILE. If there is no PROFILE in the current directory, the search continues.

/usr/lpp/graPHIGS/etc directory

The graPHIGS API provides a default PROFILE in the /usr/lpp/graPHIGS/etc directory.

For more information on setting User Default Specifications, see The graPHIGS Programming Interface: Technical Reference

AIX Defaults

Figure 6-2 shows the graPHIGS API defaults that can be changed within the AIX environment, and the format of the user default specifications.

The following default descriptions for the AIX environment are listed in alphabetical order by the user default specification parameter:

AIXTRCE=(aaaaaaaa...,bbbbbbbb,cccccccc)

A string of up to 50 characters and two strings of up to 8 characters, which are the filepath, filename, and file extension used by the graPHIGS API for trace output under AIX.

COMMENT=(cccccccc,cccccccc,........)

A comment in the form of a list of strings of 8 or less non-blank characters, which is ignored by the graPHIGS API default processing. The list must not contain more than 8000 such strings.

TRACE={0|n}

An integer that is the default value of the trace control word at initialization. The value may be specified either as a decimal integer or as an Assembler language hexadecimal constant. The format of the trace control word is described in "Trace Control Word"

Figure 6-2. AIX External Defaults

Meaning of Default	Syntax of the AFMMDFT Options	graPHIGS API Default
Comments for module identification	COMMENT=(cccccccc, cccccccc,	N/A
Trace output (for graPHIGS shell) filepath filename file extension	AIXTRCE=(aaaaaaaa..., bbbbbbbb, cccccccc)	Current working path 'AFMTRACE' N/A
Trace output (for graPHIGS remote nucleus) filepath filename file extension	AIXTRCE=(aaaaaaaa..., bbbbbbbb, cccccccc)	Current working path 'AFMTRACE' 'NUC'
Trace word value	TRACE={0\|n}	0

For a complete description of all entries in the External Defaults File (EDF), see The graPHIGS Programming Interface: Technical Reference

Application Default Interface Block (ADIB) Processing

Application Default Specifications (ADS) are accessed through the Application Default Interface Block (ADIB) during Open graPHIGS processing. The ADIB must be specified on the Open graPHIGS (GPOPPH) subroutine call as the second parameter. If no ADIB options are specified, this parameter should be 0

For a complete description of all entries in the ADIB, see The graPHIGS Programming Interface: Technical Reference

Documenting Your graPHIGS API Problem

Reviewing the following questions before contacting IBM can aid the preparation of your written report.

Exactly what were you doing when the problem occurred? What sequence of calls to the graPHIGS API led to the problem?

Does the problem occur repeatedly or does it seem to be a one-time occurrence?

Does the problem occur predictably or unexpectedly?

Can you re-create the problem?

What are the effects of the problem on your overall system operation?