DosErrClass: Difference between revisions
No edit summary |
m Ak120 moved page OS2 API:CPI:DosErrClass to DosErrClass |
(No difference)
| |
Revision as of 15:58, 6 December 2016
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;
}