[ Previous | Next | Contents | Glossary | Home | Search ]
The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis

Chapter 7. Reporting graPHIGS API Program Failures

This chapter describes the steps involved in reporting a suspected graPHIGS API failure to IBM.

Central Service is available for the graPHIGS API until discontinued by IBM upon six months notice. However, IBM does not guarantee that all errors or program defects will be corrected.

Each licensee's access to program service is determined by the marketing channel through which the product was obtained.

In the United States and Puerto Rico

If obtained through one of the IBM Authorized Personal Computer Dealers or IBM Authorized Industry Remarketers, requests for program service should be made through your dealer/remarketer.

If obtained through the U.S. Marketing and Services (M) -- Market Operations, requests for program service should be made to IBM Central Service. Your IBM Representative can assist you in completing the request.

Outside the United States and Puerto Rico

Contact your local IBM Representative or your Authorized IBM Supplier for information on program services.

In all cases, the licensee may report problems directly to IBM by sending appropriate information to the address given below.

Obtain an Authorized Problem Analysis Report (APAR) form and complete it. See the Programming System General Information Manual for additional information that will help you in completing the form.

Once the APAR form is complete, send it and all supporting documentation to:

      IBM Corporation
      11400 Burnet Road
      Austin, TX 78758 U.S.A.
      Attention:  IBM graPHIGS API Programming Interface APAR Coordinator
                  Department 997

Filling Out the APAR Form

The APAR form enables you to provide IBM with a description of your problem and your system environment. It must be completed and sent, with accompanying documentation, to the address shown above. The information requirements are explained further in the Programming System General Information Manual

graPHIGS API Product Information

Field "N": Component or Program in Error/Suspected, identifies the graPHIGS API product that you are using. The three areas are entered as follows:

Problem Symptom Reporting

Use the following information to describe the symptoms of your problem. Use this information when completing fields "R," "S," "T," and "V" of the APAR form. Be sure to include ALL available supporting documentation for the problem you are describing. For fields "R" and "S," refer to the keyword chart, "Symptoms and Failure Keywords"

Record the following information:

The symptom code that corresponds to the Failure Keyword.
A Failure Keyword that best describes the failure.
A problem abstract that summarizes the failure.
A description of the details and circumstances surrounding the failure.


Refer to the Programming System General Information Manual for additional information.

Symptoms and Failure Keywords

Select the type-of-failure keyword and symptom code for fields "R" and "S" of the APAR form from the following list:

Figure 7-1. Symptoms and Failure Keywords

Symptom Code Failure Keyword   Type of Failure
AB ABORT The graPHIGS API detected an unrecoverable error or experienced an abnormal program termination.
DD DOC The graPHIGS API documentation is in error.
IN INCORROUT The graPHIGS API generated unexpected results.
LP LOOP The graPHIGS API entered an infinite loop.
MS MSGXXX The problem is identified in the graPHIGS API error message.
PR PERFM The problem relates to the graPHIGS API performance.
WS WAIT The graPHIGS API has entered a permanent WAIT state.
Descriptions of Type-of-Failure Keywords

The following descriptions will help you narrow down your choice of keywords. Select the word that describes your problem most accurately.

Some keywords also require qualifiers. If a qualifier is required, select it from the list that accompanies the keyword. The qualifier should be entered in "T", the abstract field, along with the summary of the problem.

Use this keyword if the graPHIGS API terminates abnormally. Replace xxx in the keyword with the abort code, if one was issued.

If you select this failure keyword, you must supply the name of the graPHIGS API routine that was in control at the time of the abort. This can be determined from the trace file or the abort dump.

This keyword applies only to graPHIGS API manuals and refers to wrong, missing, or ambiguous information. The best way to deal with erroneous documentation is to fill out and submit a Reader's Comment Form. All IBM manuals include this form in the back of the book.

If you decide to submit an APAR, use the DOC keyword. In this case, you must also supply an additional failure qualifier keyword. The failure qualifier consists of the order number and level number of the manual and the numbers of any Technical Newsletters (TNLs) that update it. Choose the appropriate failure qualifier keyword from the following list.


Use MSG xxxxxx for missing or incorrect error messages. DO NOT USE DOC

Use this keyword to show that the program produced wrong output, or that the expected output did not appear. In conjunction with this word, use one or more of the following failure qualifier keywords in the failure abstract.


Blank display.

Some data is visible, but some expected data is missing.

Some application data has been displayed that should not be displayed.

Spurious data is displayed (for example, lines or text that is not defined by the application).

The data displayed is distorted (for example, compressed or expanded along an axis).

Display was not updated as specified.

A returned parameter had an incorrect or invalid value (other than an inquiry parameter).

Incorrect output values from an inquiry routine.

Returned data has overlaid another data area.

Standard host system/subsystem techniques or the graPHIGS API trace function can be used to diagnose loop and wait states. Use this keyword if you can determine that the loop was within the graPHIGS API If you are not certain, use the trace facility described in "The graPHIGS API Trace Facility"

MSG xxxxxxx
Use this keyword when a graPHIGS API message:

Replace xxxxxxx in the keyword with the identifier of the message in error. For example, suppose message AFM0310 is in error; the MSG keyword would be MSGAFM0310.

Sometimes poor performance can be attributed to the host system/subsystem. Use this keyword only if you can determine that the graPHIGS API is responsible, or if the performance problem occurs as the result of service or a new release.

A failure qualifier keyword is required with PERFM.


If no recent changes have been made, or the problem occurs in a version of the program which previously ran acceptably.

If the problem occurs only after service or a new release was applied.

The graPHIGS API contains a small number of calls to system or subsystem wait services. It also issues requests for system services. These tasks may produce wait states. If you don't know why you are in the wait state, verify the cause by using the trace facility described in "The graPHIGS API Trace Facility"

Problem Abstract

Use field "T" of the APAR form to provide a summary of the failure. Where failures involve messages or ABORTs, use the format shown for field "S," Failure Keyword (e.g. ABORT806). Where a failure keyword has a qualifier list, include the qualifier in the abstract.

Problem Description

Use field "V" of the APAR form to provide the details of the failure. Include the following items:

Supporting Information

Some of the information needed to describe a problem is generic, while some information depends on the problem you are experiencing.

General information required

Specific problems

In general, the following items might be required to solve a problem:

[ Previous | Next | Contents | Glossary | Home | Search ]