DosErrClass

Description

Provides more information about return values that have been received from other control-program functions.

Syntax

#define INCL_DOSMISC
#include <os2.h>

ULONG     code;    /* A nonzero return value returned by a control-program function. */
PULONG    pClass;  /* A pointer to the ULONG in which the classification for the error
                      is returned. */
PULONG    pAction; /* A pointer to the ULONG in which the recommended corrective action
                      for the error is returned. */
PULONG    pLocus;  /* A pointer to the ULONG in which the error origination is returned. */
APIRET    ulrc;    /* Return Code. */

ulrc = DosErrClass(code, pClass, pAction, pLocus);

Parameters

code (ULONG) - input

A nonzero return value returned by a control-program function.

A nonzero return value indicates that an error has occurred.

pClass (PULONG) - output

A pointer to the ULONG in which the classification for the error is returned.

The following values are possible:

1 ERRCLASS_OUTRES Out of resources

2 ERRCLASS_TEMPSIT Temporary situation

3 ERRCLASS_AUTH Authorization failed

4 ERRCLASS_INTRN Internal error

5 ERRCLASS_HRDFAIL Device hardware failure

6 ERRCLASS_SYSFAIL System failure

7 ERRCLASS_APPERR Probable application error

8 ERRCLASS_NOTFND Item not located

9 ERRCLASS_BADFMT Bad format for function or data

10 ERRCLASS_LOCKED Resource or data locked

11 ERRCLASS_MEDIA Incorrect media, cyclic redundancy check (CRC) error

12 ERRCLASS_ALREADY Action already taken or done, or resource already exists

13 ERRCLASS_UNK Unclassified

14 ERRCLASS_CANT Cannot perform requested action

15 ERRCLASS_TIME Timeout

pAction (PULONG) - output

A pointer to the ULONG in which the recommended corrective action for the error is returned.

The following values are possible:

1 ERRACT_RETRY Retry immediately

2 ERRACT_DLYRET Delay and retry

3 ERRACT_USER Bad user input - get new values

4 ERRACT_ABORT Terminate in an orderly manner

5 ERRACT_PANIC Terminate immediately

6 ERRACT_IGNORE Ignore error

7 ERRACT_INTRET Retry after user intervention

pLocus (PULONG) - output

A pointer to the ULONG in which the error origination is returned.

The following values are possible:

1 ERRLOC_UNK Unknown

2 ERRLOC_DISK Random-access device such as a disk

3 ERRLOC_NET Network

4 ERRLOC_SERDEV Serial device

5 ERRLOC_MEM Memory

Return Code

ulrc (APIRET) - returns

DosErrClass returns one of the following value:

• 0 NO_ERROR

Remarks

DosErrClass receives a nonzero 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.

When called by a family-mode application, DosErrClass 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.

Example Code

This example shows how DosError and DosErrClass handle errors. Run this program without a diskette in drive A: so that the DosOpen call fails with a "device not ready" condition, or run it with a disk there for a "file not found" condition.

 #define INCL_DOSFILEMGR   /* File Manager values */
 #define INCL_DOSERRORS    /* DOS error values    */
 #define INCL_DOSMISC      /* DOS miscellaneous   */
 #include <os2.h>
 #include <stdio.h>

 int main(VOID) {
 UCHAR        uchFileName[80] = "A:\\NONEXIST.ZQX"; /* File to fail on      */
 HFILE        hfConfig      = 0;             /* Handle for Config file      */
 ULONG        ulOpenAction  = 0,             /* Action taken by DosOpen     */
              ulErrorClass  = 0,             /* Type of error encountered   */
              ulErrorAction = 0,             /* Action warranted by error   */
              ulErrorLoc    = 0;             /* Where error occurred        */
 APIRET       rc            = NO_ERROR,      /* Return code                 */
              DosOpenRc     = NO_ERROR;      /* Return code from DosOpen    */

  rc = DosError(FERR_DISABLEHARDERR); /* Suppress error window.  If this is
                                         omitted, OS/2 will put up an error
                                         window asking the user to intervene */
  if (rc != NO_ERROR) {
     printf("DosError error: return code = %u\n", rc);
     return 1;
  }
  DosOpenRc = DosOpen(uchFileName,          /* File to open (path and name) */
               &hfConfig,                   /* File handle returned         */
               &ulOpenAction,               /* Action taken by DosOpen      */
               0L,0L,        /* Primary allocation and attributes (ignored) */
               OPEN_ACTION_FAIL_IF_NEW |
               OPEN_ACTION_OPEN_IF_EXISTS,  /* Open an existing file only   */
               OPEN_SHARE_DENYNONE   |
               OPEN_ACCESS_READWRITE,       /* Read and write access        */
               0L);                         /* Extended attributes(ignored) */

    if (DosOpenRc == NO_ERROR) {
        printf("DosOpen successful... but it should have failed.\n");
        return 1;
    } else {
      rc = DosErrClass(DosOpenRc,           /* Return code from failing API */
                       &ulErrorClass,       /* Class of error               */
                       &ulErrorAction,      /* Action to take for error     */
                       &ulErrorLoc);        /* Where did the error occur?   */

      if (rc != NO_ERROR) {
          printf("DosErrClass error: return code = %u\n", rc);
          return 1;
      } else {
          printf("rc= %u  ErrorClass= %u  ErrorLoc= %u\n",
                  DosOpenRc, ulErrorClass, ulErrorLoc);

          printf("ErrorAction= %u means: ", ulErrorAction);
          switch (ulErrorAction) {
           case(ERRACT_RETRY):  printf("Retry immediately");    break;
           case(ERRACT_DLYRET): printf("Retry after a delay");  break;
           case(ERRACT_USER):   printf("Incorrect user input"); break;
           case(ERRACT_ABORT):  printf("Terminate in an orderly fashion");
                                                                break;
           case(ERRACT_PANIC):  printf("Terminate NOW");        break;
           case(ERRACT_IGNORE): printf("Ignore this error");    break;
           case(ERRACT_INTRET): printf("Retry after user intervenes");
                                                                break;
           default:             printf("Unknown error action"); break;
          } /* switch */
          printf("\n");
      }
   }  /* DosOpen failure */

  rc = DosError(FERR_ENABLEHARDERR);        /* Re-enable error window */
  if (rc != NO_ERROR) {
     printf("DosError error: return code = %u\n", rc);
     return 1;
  }

  return NO_ERROR;
}

Related Functions

• DosError