During the processing of your graPHIGS API subroutine calls, errors may occur. For example, an invalid parameter value may be passed or a hardware error may occur at the workstation. These errors are most commonly reported to your application in an error message that describes the error situation. Your application has several facilities for dealing with errors. For example, it can cause the error message to be displayed on a user's terminal, or it can require additional information from the graPHIGS API This chapter describes how the errors are reported, the information provided with the error, and options available to your application in processing the error and its message.
Note: See "Distributed Application Program Error Processing" for a description of restrictions on error processing by a DAP.
Most errors are reported to your application for further processing. However, some errors, such as errors encountered during a traversal, result in a default action being taken, and no error is reported. If the error did not occur during the processing of an inquiry subroutine, the error and the associated message are processed by the error facilities of the graPHIGS API
The remainder of this chapter presents the errors and messages, as well as the graPHIGS API error processing performed. If the error is detected during the processing of an inquiry subroutine, an error number is returned as the error indicator errind parameter. These error numbers are listed with the errind parameter description of each inquiry subroutine listed in The graPHIGS Programming Interface: Subroutine Reference In addition to the errors listed with each subroutine description, it is possible that additional errors will be reported when the error occurs within an internal service of the graPHIGS API See "Error Numbers" for a description of the error numbers by the graPHIGS API in the errind parameter.
A few errors are so severe that the graPHIGS API will terminate processing. This termination will be done using the ABORT service of AIX and the ABEND service of MVS and VM. For the ABORT service, a 1204 message is displayed on 'stderr' that provides the ABORT code for the error that occurred. These ABORT codes and a brief explanation of the error are listed in Appendix B. For the ABEND service, the ABEND code identifies the error that occurred. These ABEND codes and a brief explanation of the error are listed in Appendix A.
For most errors detected by the graPHIGS API, the error is reported by using a message that briefly explains the problem that has been detected. This is performed by the graPHIGS API error processing facilities. You and your application can control whether this message is displayed or whether it is to be suppressed. In addition, your application can provide recovery routines to be invoked as error handling routines for processing the error.
The graPHIGS API error processing defaults to logging the error messages in a designated error file. See "Application Error Processing" for a description of replacing this default error processing with your own application error processing. This error file is specified as a parameter of the GPOPPH subroutine.
If you specify blanks for the file name, or if the error file is not usable, the error message is written to 'stderr,' which defaults to the console (AIX), to the job log (MVS batch processing), or to the user's terminal (VM and MVS).
Each error message provided by the graPHIGS API consists of the following parts. See Example of an error file entry.
Example of a graPHIGS API Error File Entry
GPCR AFM0049 COLOR INDEX EXCEEDS WORKSTATION TABLE CAPACITY |
Note: Specific errors detected by the subroutines are listed with the corresponding subroutine description in The graPHIGS Programming Interface: Subroutine Reference
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 called by your application. In the case where the error is not directly related to any graPHIGS API subroutine call (such as an asynchronous hardware error), the subroutine name field contains asterisks. In addition, it is not possible to always identify the 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 graPHIGS API subroutines have been called. The graPHIGS API provides the name of a graPHIGS API subroutine that is most likely to have been invoked when the error occurred. In the case where such a related subroutine name is provided in the error message, an asterisk follows the subroutine name to indicate that the identified subroutine may not be the actual subroutine called. See Appendix C for more information on errors not directly related to any API subroutine calls.
The message number provided in each message identifies each unique error message text, and identifies the additional information in the error message descriptions in the remaining chapters of this manual. The message numbers are arranged in groups of related messages. Message groups are defined as follows:
The remaining chapters of this manual provide additional information for each of the error messages provided by the graPHIGS API The description of each error contains the following information. See Error Description Example.
There are two types of system actions, warning and ignoring subroutine.
| 1 FUNCTION REQUIRES STATE PHCL |
Explanation: A second call to GPOPPH was made using the System Action: The subroutine call in error is ignored. Programmer Response: Correct the program so that GPOPPH Error Number: 1 |
Your application can provide error handling routines that are called by the graPHIGS API whenever an error occurs. See The graPHIGS Programming Interface: Subroutine Reference and The graPHIGS Programming Interface: Technical Reference for a complete description of error processing. The routine identified on the GPEHND subroutine is invoked in place of the graPHIGS API error processing. When invoked, this error exit routine can perform the processing required to deal with the error for the application. The error handling routine can cause the error message associated with the error to be written to the error file by using the GPELOG subroutine. The error exit can also obtain the text of the error message by issuing the GPQEMS subroutine call. Note that these two functions can only be invoked by a first-level error exit, since the graPHIGS API must be in an error state for an error message to be available.
One of the parameters provided to your first-level error handling routine is an error number. See the GPEHND subroutine call 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 Errors 900-999 DEVICE SUPPORT). 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, and 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 (common to all devices). Most errors will be 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 subroutine.
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 will have no effect on the system; other errors may be unrecoverable, causing the application to terminate.
These errors are generated while trying to process a distributed application. The state of the system and the distributed application after the error is dependent on the error. Note that for errors in this range, the message number is the same as the error number.
The execution environment of a Distributed Application Program (DAP) is more restrictive than that of the other graPHIGS API environments. Since there is no general purpose file I/O facility, messages and error file facilities are not available as part of the graPHIGS API error processing. Your application will have to provide explicit error processing in order to deal with errors that occur.
Following are the restrictions on error processing in the DAP environment:
Since the DAP error processing will not produce an error message, your application will need to use error handling routines to obtain the desired error information. A first-level error handling routine (defined using GPEHND) can pass the error number and message number parameter values to the application mainline or to a second-level error handling routine (defined using GPEXIT). From there, the information can be sent to the cooperating host application (using GPSPMS) for further processing.