The following chart provides a broad outline of the problem diagnosis procedure for the graPHIGS API Bypass this chapter if you know your problem is within the graPHIGS API, and if you have isolated the symptoms of your program failure.
Figure 4-1. Outline of Problem Diagnosis Procedure
--------------------
| Examine |
| problem |
| symptoms |
--------------------
|
|
v
-------------------- --------------------
| graPHIGS API | No | Isolate problem |
| problem? |------> | to |
| (See Chs. 4 & 5) | | system component |
-------------------- -------------------
|
| Yes
v
--------------------
| Gather |
| data |
| (see Chapter 6) |
--------------------
|
|
v
--------------------
| Report |
| problem |
| (see Chapter 7) |
--------------------
This chapter contains the basic procedures used to identify problems in the hardware and operating systems that the graPHIGS API uses. First, examine the following areas to determine whether they function properly. Programs using the graPHIGS API can fail because of problems with any of the following:
After reviewing these problems, gather as much supporting data as possible to help you isolate the symptoms of the failure. You will include this information in your report to IBM.
Programming problems create symptoms in many ways. Messages on the display or in the error file, abnormal termination, or improper operation are general categories of program failures that are discussed in this section.
Diagnosis begins by observing the symptoms of the suspected problem. These symptoms include:
The flowchart in Figure 4-2 is a quick reference for the diagnosis process. The brief descriptions provided in the chart are discussed in detail in the sections that follow.
Figure 4-2. Problem Diagnosis Flowchart
----------------------
| Observe |
| problem symptoms |
----------------------
|
|
v
---------------------- Yes ---------------------- ----------------------
| Diagnostic |------>| Investigate and |------>| See Messages and |
| messages? | | correct | | Codes |
---------------------- ---------------------- ----------------------
|
| No
v
---------------------- Yes ---------------------- Yes ----------------------
| Abnormal ending |------>| Issued by |------>|See Abort Codes |
| (abort)? | | graPHIGS API? | | in Appendix A |
---------------------- ---------------------- ----------------------
| |
| No | No
v v
---------------------- Yes ---------------------- Yes ----------------------
| Loop or wait? |------>| graPHIGS API |----->| Gather data |
| | | itself? | | and report |
---------------------- ---------------------- ----------------------
| |
| No | No
v v
---------------------- Yes ---------------------- ----------------------
| Installation |------>| IVP program |----->| Check hardware and |
| problem? | | fail? | | operating system |
---------------------- ---------------------- ----------------------
|
| No
v
--------------------
| Investigate for |
|application error |
--------------------
---------------------- Yes ---------------------- Yes ----------------------
| Loop or wait? |------>| graPHIGS API |----->| Gather data |
| | | itself? | | and report |
---------------------- ---------------------- ----------------------
| |
| No | No
v v
---------------------- Yes ---------------------- ----------------------
| Installation |------>| IVP program |----->| Check hardware and |
| problem? | | fail? | | operating system |
---------------------- ---------------------- ----------------------
|
| No
v
--------------------
| Investigate for |
|application error |
--------------------
The graPHIGS API ordinarily defaults to logging diagnostic messages in a designated error file. The graPHIGS API designated error file is found in the current working directory at the time of the error. Investigate all diagnostic messages logged in this file to determine whether they point to your observed symptoms.
The name of the error file is chosen by the application with the Open graPHIGS (GPOPPH) subroutine. If no error file is specified (e.g., if your application specified blanks for the file name), or if the error file is not usable (e.g., if the user does not have write authority in the current directory), messages are written to stderr, which defaults to the console (AIX)
Diagnostic messages are displayed in the error file as follows:
Figure 4-3. Example of the graPHIGS API Error File Entry
1 2 3 4 Fri Jul 10 11:17:49 1992 GPLT AFM0063 LINETYPE VALUE < ONE
These messages contain the following information:
The graPHIGS API subroutine name is provided to help identify a graPHIGS API subroutine call that may have caused the error. For most errors, this name is the graPHIGS API subroutine that your application called.
The subroutine name field contains asterisks if the error is not directly related to any API subroutine call (such as an asynchronous hardware error)
An asterisk follows the subroutine name to indicate that the identified subroutine name may not be the actual subroutine call issued by your application that may have caused the error. For example, the error may be detected long after the invoked graPHIGS API subroutine has returned to your application and other subroutines have been called. The graPHIGS API provides the name of the subroutine that was most likely invoked when the error occurred. The related subroutine name (followed by an asterisk) is provided in the error message. Refer to The graPHIGS Programming Interface: Messages and Codes for a table of related subroutines.
Note:
To isolate the sequence of the graPHIGS API subroutine calls that generated the error, it may be necessary to rerun the application with the graPHIGS API trace active.
The following is a general outline of diagnostic messages and error numbers. See The graPHIGS Programming Interface: Messages and Codes , for further error information and for help in debugging problems reported in the error file.
The message number provided in each message identifies each unique error message text, and identifies the additional information in the error message descriptions that is provided in The graPHIGS Programming Interface: Messages and Codes The message numbers are arranged in groups of related messages. Pertinent message groups are defined as shown in Figure 3-2:
One of the parameters provided to your first level error handling routine is an error number. See the GPEHND subroutine in The graPHIGS Programming Interface: Subroutine Reference for a complete description of the interface and parameters passed to your error handling routine. The error number identifies the error that has occurred and reveals the severity of the error. This can assist you in determining how your error handling routine should react to the error.
The error number provided to your error handling routine is related to, but is separate from, the message number of the error message text associated with the error. For most errors, the error number and the message number are the same number. Only for the Device Support errors (900-999) are the error numbers different from the message numbers. For the Device Support errors, the error numbers are in groups that indicate the severity of the error. See the section on Errors 900-999 DEVICE SUPPORT or, for more information, The graPHIGS Programming Interface: Messages and Codes ) Using this grouping, your application's error handling routine can process workstation errors in general categories without having to deal with each workstation-specific error that can occur across many different workstations. The message number associated with each Device Support error is unique. It identifies the unique message text associated with the reported error.
The graPHIGS API error numbers are divided into the following ranges:
The errors in this range are device independent; they are common to all devices. Most errors are found in this category, including errors generated by parameter validation. Note that for errors in this range, the message number is the same as the error number. There are two types of system actions in this category; warning and ignoring function:
The errors in this range are detected during processing for a specific workstation. The types of errors detected include I/O errors, workstation capacity exceeded errors, and device or host service errors. Note that for errors in this range, the message number is different from the error number. The device support errors are subdivided into the following error classes:
The application may attempt to return the workstation to a determinate state by closing and reopening the workstation.
These messages are generated by the graPHIGS API service utilities. Examples of these errors include initialization, incorrect number of parameters passed on a subroutine, storage request failures, and file I/O errors. Note that for errors in this range, the message number is the same as the error number.
The state of the system after the error, is dependent on the error conditions. Some errors have no effect on the system; other errors may be unrecoverable, causing the application to terminate.
If an error is detected during the processing of an inquire subroutine call, a diagnostic message is not returned to the error file; rather, an error number is returned as the error indicator errind parameter.
Your application may be relying on information assumed to have been returned by a graPHIGS API inquiry subroutine. If the information requested by an inquiry is unavailable for any reason, the errind parameter is returned as a non-zero value. Make sure that the application always checks for zero value before using the requested information.
Error numbers are listed with the errind parameter description of each inquiry subroutine in The graPHIGS Programming Interface: Subroutine Reference (Note that in addition to the errors listed with each subroutine description, it is possible to get additional errors reported when the error occurs within an internal service of the graPHIGS API See The graPHIGS Programming Interface: Messages and Codes for a description of the error numbers provided by the graPHIGS API in the errind parameter.
If an input method (IM) error is detected during the processing of a graPHIGS API string device, a system service diagnostic message is returned to the error file. Refer to Calls and Subroutine Reference: Base Operating System and General Programming Concepts to find the cause of the error.
See The graPHIGS Programming Interface: Technical Reference for more information on ensuring that font files have been correctly installed.
It is possible that graPHIGS API is attempting to send error messages to you, but your application is suppressing them. Your application (and the user) can control where error messages are displayed, or whether they are displayed at all. Your application can provide recovery routines invoked as error handling routines for processing the error.
Using Specify an Error Exit and Error Threshold (GPEXIT), you can define a level 1 error handler in your system. However, the graPHIGS API will log the error only upon your request, which is done by issuing Error Logging (GPELOG). When an error condition occurs, the level 1 error handler is invoked. An error number indicating the severity of the error is passed to the error handler. You can request that the message be logged.
You can have your application handle errors in its own way. Instead of logging the error, it can take other actions. See The graPHIGS Programming Interface: Writing Applications for a detailed description of error processing and handling.
If an error is severe enough, the graPHIGS API terminates processing. Termination occurs using the ABORT service of AIX. ABORT completion codes indicate that an abnormal condition, generally one that is unrecoverable, has occurred. An ABORT completion code may also indicate an error in the way the application is using the graPHIGS API
When the graPHIGS API issues an abort, the message AFM1204 graPHIGS API ABORT CODE=xxx is written to stderr, that provides the ABORT code for the error that occurred. See Appendix A to determine the issuing module and the reason for the abort.
A core file results when various errors occur in a terminated process. Common errors are memory violations and illegal instructions The core file is written in the process's working directory if there is sufficient space and the user has write authority.
The use of a separate shell and nucleus has made it more difficult to determine which subroutine call caused a loop or wait. Synchronize (GPSYNC) should be used in conjunction with the graPHIGS API trace facility to show which subroutine has caused the loop or wait. To avoid having to place calls toGPSYNC after every graPHIGS API subroutine in your application, refer to The graPHIGS Programming Interface: Writing Applications for a method of using GPSYNC in a second-level error handling routine to force requests to the nucleus after every graPHIGS API subroutine.
When the graPHIGS API is installed, files are put in the AIX file system as listed in Figure 2-1 Check to be sure that these files exist in each of the specified directories.
To help rule out system and hardware problems, run a program that you know works correctly. Review your application program to make sure that all subroutines are used correctly. Verify that all values that are not explicitly set by your application have an acceptable default. See The graPHIGS Programming Interface: Writing Applications for possible programming pitfalls.