CPGuide - Error Management

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Control Program Programming Guide and Reference

Introduction to the Control Program Control Program Functions Keyboard Functions Mouse Functions Video Functions Data Types Errors Debugging Kernel Debugger Communications Protocol Device I/O Dynamic Linking Error Management Exception Management Extended Attributes File Management File Names File Systems Generic IOCtl Commands Memory Management Message Management National Language Support Pipes Program Execution Control Queues Semaphores Timers Notices Glossary

Error checking and error handling is extremely important in a multitasking operating system. The conditions in which an application is executing can change at any time due to the activity of other programs executing concurrently with the application. This section describes the functions that an application can use to manage errors that occur during processing.

The following topic is related to the information in this scetion:

• Exception management

About Error Management

Successful completion of most Control Program functions is indicated by an error return code of 0. In the event of an error, Control Program functions usually return an error code that has a non-zero integer value. The non-zero value equates to a symbolic error identifier in the include file, BSEERR.H. The symbolic identifiers indicate the cause of the error. For example, a return code of 2 from DosOpen equates to the symbolic identifier ERROR_FILE_NOT_FOUND; the cause of the error is that the file being opened cannot be found.

DosErrClass and DosError are supplied to assist in error processing.

• DosErrClass takes as input a non-zero return value that was received from any control-program function. (Any return value other than 0 indicates that an error occurred.) The output is a classification of the error and a recommended action. Depending on the application, the recommended action could be followed, or a specific recovery action could be performed.

• DosError enables an application to prevent OS/2 from displaying a default error message in a pop-up window when either a hard error or a software exception occurs.

Classifying Return Values

When a control-program function has been successfully completed, a return value of 0 is returned to the calling thread. A non-zero return value indicates that an error has occurred.

Each non-zero value corresponds to a symbolic error identifier that indicates the cause of the error. For example, a return value of 2 from DosOpen (indicating that the file was not found) corresponds to the symbolic identifier ERROR_FILE_NOT_FOUND.

DosErrClass helps applications deal with non-zero return values by taking a return value as input and returning both an error classification and a recommended action. Depending on the application, the recommended action could be followed, or a more specific recovery routine could be executed.

Disabling Error Notifications

A hard error is typically an error (such as the opening of a disk-drive door while a diskette is being read, or any similar kind of device error) that cannot be resolved by software. When a hard error occurs, the system default action is to prompt for user input by displaying a message in a pop-up window.

DosError disables the default action, foregoing the displayed message and causing an appropriate return value to be returned to whichever control-program function was running when the hard error occurred. The application must determine the appropriate response by referring to the return value.

DosError also enables the application to disable end-user notification if either a program exception or an untrapped numeric-processor exception occurs. However, if one of these exceptions occurs while user notification is disabled, the application will still be ended.

As with hard errors, the system default is that user notification for these exceptions is enabled.

Using Error Management

OS/2 supplies DosErrClass and DosError for error processing. DosErrClass aids in determining the appropriate action that an application should take in response to an error. DosError enables applications to disable the pop-up windows used by OS/2 to inform the user of a hard-error or an exception.

Note

In the example code fragments that follow, error checking was left out to conserve space. Applications should always check the return code that the functions return. Control Program functions return an APIRET value. A return code of 0 indicates success. If a non-zero value is returned, an error occurred.

Classifying Errors

DosErrClass receives a non-zero return value from another control-program function as input. It then classifies the return value, tells where in the system the error occurred, and recommends a corrective action.

In the following example, an attempt is made to delete a nonexistent file. The return value is then passed to DosErrClass so that more information about the error can be obtained, including any corrective actions that can be taken.

    #define INCL_DOSMISC
    #include <os2.h>

    #define FILE_DELETE "JUNK.FIL"

    ULONG   ulError;
    ULONG   ulClass;
    ULONG   ulAction;
    ULONG   ulLocus;
    APIRET  ulrc;

    ulError = DosDelete(FILE_DELETE);           /* File name path                */

    ulrc = DosErrClass(ulError,                 /* Return value to be analyzed   */
                       &ulClass,                /* Error classification          */
                       &ulAction,               /* Recommended corrective action */
                       &ulLocus);               /* Where the error occurred      */

When called by a family-mode application, this function can return a valid error classification only for errors that have actually occurred. Also, the classifications of a given return value might not be the same for family-mode and OS/2-mode applications.

Disabling Hard-Error and Exception Messages

DosError disables or enables end-user notification of hard errors, program exceptions, or untrapped, numeric-processor exceptions.

In the following example, pop-up windows for hard errors and exceptions are disabled, then enabled again.

    #define INCL_DOSMISC   /* Error and exception values */
    #include <os2.h>


    /*************************************************/
    /* use pre-defined constants                     */
    /* FERR_DISABLEHARDERR   (0x00000000)            */
    /* FERR_ENABLEHARDERR    (0x00000001)            */
    /* FERR_ENABLEEXCEPTION  (0x00000000)            */
    /* FERR_DISABLEEXCEPTION (0x00000002)            */
    /* to create constants needed for DosError calls */
    /*************************************************/

    #define ENABLE_ERRORPOPUPS  FERR_ENABLEEXCEPTION | FERR_ENABLEHARDERR
    #define DISABLE_ERRORPOPUPS FERR_DISABLEEXCEPTION | FERR_DISABLEHARDERR

    APIRET ulrc;    /* Return code */

    ulrc = DosError(DISABLE_ERRORPOPUPS);   /* Action flag for disable */
    ulrc = DosError(ENABLE_ERRORPOPUPS);    /* Action flag for enable  */

The action to take is encoded as a binary flag. The following table shows the bit-values and their meanings.

Bit Values to Enable and Disable Hard-Error and Exception Pop-up Messages

┌─────┬─────┬──────────────────────────────────────────────────┐
│Bit  │Value│Meaning                                           │
├─────┼─────┼──────────────────────────────────────────────────┤
│0    │1    │Enables hard-error pop-up messages.               │
├─────┼─────┼──────────────────────────────────────────────────┤
│0    │0    │Disables hard-error pop-up messages.              │
├─────┼─────┼──────────────────────────────────────────────────┤
│1    │0    │Enables exception pop-up messages.                │
├─────┼─────┼──────────────────────────────────────────────────┤
│1    │1    │Disables exception pop-up messages.               │
└─────┴─────┴──────────────────────────────────────────────────┘

If DosError is not called, user notification for hard errors and exceptions is enabled by default.