This chapter describes the error handling facilities of the graPHIGS API These facilities give your application the ability to perform the following:
The figures, "Error Handling Flow of Control (Part 1 of 2)" and "(Part 2 of 2)," depict the sequence of events that occur when the graPHIGS API detects an error. Error detection and the processing of errors is discussed in detail in the following sections.
During the processing of a subroutine call, there are two categories of errors: (1) validation errors, and (2) processing errors.
Before processing any subroutine call, the graPHIGS API shell checks the validity of the subroutine call based on the current state of the graPHIGS API system. For example, when a first-level error handler is given control the graPHIGS API system is put into an error state which prohibits most non-inquiry subroutines from being called. Therefore, if you write a first-level error handler that calls a non-inquiry subroutine such as Open Structure (GPOPST), the graPHIGS API
Validating a subroutine call includes checking the validity of the parameters supplied by your application. For example, if your application calls the Set Polyline Color Index (GPPLCI) subroutine with a color index which is less than zero, the graPHIGS API shell will generate an error because color index values must be greater than or equal to zero.
After a subroutine call to the graPHIGS API is validated, the information generated by the subroutine call may be further processed by a graPHIGS API nucleus. Due to the buffering of data between a shell and nucleus, the actual processing of the information generated by a subroutine call to the graPHIGS API may occur at any time before or after the graPHIGS API shell has returned control to your application. While attempting to process the information, the nucleus may detect errors which are sent back to the graPHIGS API shell to be processed after the next subroutine call to the graPHIGS API
During the processing of a graPHIGS API subroutine call, all errors detected by the graPHIGS API shell and nucleus are put onto the shell's error queue to be processed before control is returned to your application. Asynchronous errors generated by the graPHIGS API nucleus are also put on the shell's error queue but will not be processed until the next API call has been completed. The graPHIGS API system can detect and queue multiple errors, each of which are processed in the order they are queued.
In order to prevent the graPHIGS API from queueing errors, your application can turn off the API's error handling mode using the Set Error Handling Mode (GPEMO) subroutine. With the error handling mode set to OFF , errors are still detected and processed internally but are not queued and therefore not reported in any way. By default, the error handling mode is set to ON meaning that all errors are put on the error queue to be processed.
To boost the performance of a stable application, you can disable some of the parameter checking performed by the graPHIGS API shell. Parameter checking is disabled through the External Defaults File (EDF) or the Application Defaults Interface Block (ADIB) parameter of the Open graPHIGS (GPOPPH) subroutine. The use of EDF and ADIB options are discussed in detail in The graPHIGS Programming Interface: Technical Reference When parameter checking is disabled, the graPHIGS API shell will only check the validity of the parameters necessary to build the data stream between the shell and the nucleus. The data stream itself will not be validated and could potentially cause the nucleus to abend if the data stream does contain an error. Therefore, turning off parameter checking will boost the performance of your application but also increases the risk that your application will cause an abend.
The graPHIGS API does not explicitly notify your application of errors by way of parameters or return codes. Instead, after processing a subroutine call to the graPHIGS API, the shell will check the error queue. If the queue is empty, the shell returns control to your application. If the queue is not empty, the shell invokes the error processing facility of the graPHIGS API By default, the error processing facility will log each error in the error file specified by the first parameter of the Open graPHIGS (GPOPPH) subroutine. For example, if your application calls the Set Interior Color Direct (GPICD) subroutine with a color parameter which is invalid, the following error will be logged in the error file:
GPICD AFM0096 COLOR PARAMETER OUT OF RANGE FOR CURRENT COLOR MODEL
Your application can change the way errors are processed by specifying first- and second-level error handlers as discussed in the following sections.
To override the default handling of errors your application must define a first-level error handler using the Define Error Handler (GPEHND) subroutine. GPEHND takes one parameter which is the address of your application's first-level error handler. To restore default error handling, your application must call the GPEHND subroutine with a parameter of zero.
With a first-level error handler defined, the graPHIGS API will perform the following actions for each error on the error queue:
To determine the cause of an error, your application's first-level error handler may call any inquiry subroutine to obtain information from state lists and description tables. For example, the error message text associated with the error being processed may be obtained through the Inquire Error Message (GPQEMS) subroutine. Inquiry subroutines do not generate errors; rather, they return error indicators describing the success or failure of the inquiry.
A first-level error handler may log the current error and its associated message text using the Error Logging (GPELOG) subroutine. GPELOG lets your application specify the name of the file into which the error is logged. Note that GPELOG is the only valid non-inquiry subroutine that can be called by the first-level error handler. Any other non-inquiry subroutine called by a first-level error handler will cause the error handler to be removed (undefined) resulting in the default processing of subsequent errors.
The major purpose of a first-level error handler is to assign a severity value between 0 and 16. The severity value controls whether the API calls the second-level error handler which has more freedom to modify the state of the graPHIGS API system as discussed in the following section.
The graPHIGS API provides a default second-level error handler which displays an informational message only. You may choose to have your application provide a more sophisticated second-level error handler which can call non-inquiry subroutines unlike a first-level error handler.
For your second-level error handler to be called, it must have been previously defined by a call to the Specify Error Exit and Error Threshold (GPEXIT) subroutine and your first-level error handler must have set an error severity value greater than or equal to the severity threshold set using GPEXIT Calls that complete normally are assigned a severity of zero by the API. If you want your second-level error handler to receive control after every API call then you must set the severity threshold level to zero.
Using a second-level error handler which calls the Synchronize (GPSYNC) subroutine can be helpful while debugging a program. GPSYNC forces the contents of the shell'communication buffer to be sent to the nucleus to be processes and will optionally wait for the nucleus to finish processing the buffer before returning control to your application. By waiting for the nucleus to finish processing, all errors contained in the buffered data will be detected by the nucleus and put on the shell's error queue before GPSYNC returns control to your application. With the severity threshold set to zero, your second-level error handler can call GPSYNC to force the contents of the shell to nucleus buffer to be sent and processed before your application receives control to make the next call to the graPHIGS API This technique is recommended for debugging purposes, only because it will greatly degrade the performance of your application.