DosErrClass

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

Syntax
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 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.

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. 
 * 1) define INCL_DOSFILEMGR  /* File Manager values */
 * 2) define INCL_DOSERRORS   /* DOS error values    */
 * 3) define INCL_DOSMISC     /* DOS miscellaneous   */
 * 4) include 
 * 5) include 

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