[ Previous |
The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis
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.
If obtained through one of the IBM Authorized Personal
Computer Dealers or IBM Authorized Industry Remarketers,
requests for program service should be made through
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
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.
Programming System General Information
information that will help you in completing the form.
Once the APAR form is complete, send it and all supporting
11400 Burnet Road
Austin, TX 78758 U.S.A.
Attention: IBM graPHIGS API Programming Interface APAR Coordinator
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
Component or Program in Error/Suspected,
identifies the graPHIGS API product that you are using.
The three areas are entered as follows:
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
"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
for additional information.
Select the type-of-failure keyword and symptom code for
fields "R" and "S" of the APAR form from the
Figure 7-1. Symptoms and Failure Keywords
Type of Failure|
||The graPHIGS API detected an unrecoverable error or
experienced an abnormal program termination.|
||The graPHIGS API documentation is in error.|
||The graPHIGS API generated unexpected results.|
||The graPHIGS API entered an infinite loop.|
||The problem is identified in the graPHIGS API error message.|
||The problem relates to the graPHIGS API performance.|
||The graPHIGS API has entered a permanent WAIT state.|
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.
xxxUse this keyword if the graPHIGS API terminates abnormally.
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
DOCThis 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
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
- SC33-8130 - The Personal graPHIGS Programming Interface: Customization and Problem Diagnosis
- SC33-8190 -
The graPHIGS Programming Interface: Introducing
- SC33-8119 -
The graPHIGS Programming Interface: Tutorial User' Guide
- SC33-8120 -
The graPHIGS Programming Interface: Demonstration Guide
- SC33-8198 - The Personal graPHIGS Programming Interface: Getting Started
- SC33-8191 - The graPHIGS Programming Interface: Understanding Concepts
- SC33-8192 -
The graPHIGS Programming Interface: Writing Applications
- SC33-8193 - The graPHIGS Programming Interface: Technical Reference
- SC33-8194 - The graPHIGS Programming Interface: Subroutine Reference
- SC33-8195 -
The graPHIGS Programming Interface: Quick Reference
- SC33-8196 - The graPHIGS Programming Interface: Messages and Codes
- SC33-8140 - The graPHIGS Programming Interface: ISO PHIGS Subroutine Reference
- SC28-2705 -
The graPHIGS Programming Interface: ISO PHIGS Quick Reference
- SC33-8111 -
The Personal graPHIGS Programming Interface: User's Guide for the Graphical Kernel System-Compatibility Option
- SC33-8112 -
The Personal graPHIGS Programming Interface: Subroutine Reference for the Graphical Kernel System-Compatibility Option
- SC33-8113 -
The Personal graPHIGS Programming Interface: Quick Reference for the Graphical Kernel System-Compatibility Option
xxxxxx for missing or incorrect error
DO NOT USE DOC
INCORROUTUse 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
LOSTDATASome data is visible, but some expected data is missing.
MOREDATASome application data has been displayed that should
not be displayed.
EXTRADATASpurious data is displayed (for example, lines or text
that is not defined by the application).
DISTORTIONThe data displayed is distorted (for example,
compressed or expanded along an axis).
NOUPDATEDisplay was not updated as specified.
PARMERRA returned parameter had an incorrect or invalid value
(other than an inquiry parameter).
INQUIRYIncorrect output values from an inquiry routine.
OVERLAYReturned data has overlaid another data area.
LOOPStandard host system/subsystem techniques or the
graPHIGS API trace function can be used to diagnose loop and wait
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"
xxxxxxxUse this keyword when a graPHIGS API message:
- Contains incorrect information
- Is not documented or is incorrectly documented in The graPHIGS Programming Interface: Messages and Codes
- Is generated by a set of conditions that should not
cause it to appear
- Describes an error condition that should be reported
(such as certain I/O error messages).
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.
PERFMSometimes poor performance can be attributed to the
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.
NOCHANGEIf no recent changes have been made, or the problem
occurs in a version of the program which previously ran
CHANGEIf the problem occurs only after service or a new
release was applied.
WAITThe 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"
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.
Use field "V" of the APAR form to provide the
details of the failure.
Include the following items:
- Sequence of actions and observations at the device,
including expected results
- The graPHIGS API subroutine calls made prior to the failure
- Description of the processing of the application.
Some of the information needed to describe a problem is
generic, while some information depends on the problem you are
- Application program - a copy of the application program
so that the operations of the application can be reviewed .
- Maintenance list - a list of all service that has been
In general, the following items might be required to solve
- A copy of the application program in which the failure
This may be in the form of an executable module or the
source code to an application.
- A core file.
If one is sent in as supporting documentation, then the
failing executable module must also be sent in.
- A synchronized graPHIGS API component trace.
- For incorrect output, a description of the calls, the
data values used, and the expected output must be given.
- For a graPHIGS API message that does not result in
termination, a full description of the calls used and
the expected output must be given.
[ Previous |