en:docs:fapi:doserrclass

This is part of Family API which allow to create dual-os version of program runs under OS/2 and DOS

Note: This is legacy API call. It is recommended to use 32-bit equivalent

2021/09/17 06:47 · prokushev
2021/08/20 05:18 · prokushev

This call helps OS/2 applications respond to error codes (return codes) received from OS/2.

Syntax

DosErrClass (Code, Class, Action, Locus)

Parameters

  • Code (USHORT) - input : Error code returned by an OS/2 function.
  • Class (PUSHORT) - output : Address of the classification of an error.
  • Action (PUSHORT) - output : Address of the action for an error.
  • Locus (PUSHORT) - output : Address of the origin of an error.

Return Code

rc (USHORT) - return:Return code descriptions are:

  • 0 NO_ERROR

Remarks

The input is a return code returned from another function call, and the output is a classification of the return and recommended action. Depending on the application, the recommended action could be followed, or a more specific application recovery could be performed.

The following values are returned in Class, Action, and Locus:

VALUE MNEMONIC DESCRIPTION
1OUTRESOut of resources
2TEMPSITTemporary situation
3AUTHAuthorization failed
4INTRNInternal error
5HRDFAILDevice hardware failure
6SYSFAILSystem failure
7APPERRProbable application error
8NOTFNDItem not located
9BADFMTBad format for call/data
10LOCKEDResource/data locked
11MEDIAIncorrect media, CRC error
12ALREADYResource/action already taken/done/exists
13UNKUnclassified
14CANTCan't perform requested action
15TIMETimeout
VALUE MNEMONIC DESCRIPTION
1RETRYRetry immediately
2DLYRETDelay and retry
3USERBad user input - get new values
4ABORTTerminate in an orderly manner
5PANICTerminate immediately
6IGNOREIgnore error
7INTRETRetry after user intervention
VALUEMNEMONICDESCRIPTION
1UNKUnknown
2DISKRandom access device such as a disk
3NETNetwork
4SERDEVSerial device
5MEMMemory

Family API Considerations

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following considerations apply to DosErrClass when coding for the DOS mode:

When DosErrClass is called by a family application, it returns a valid error classification for returns that have occurred. The classifications of a given return code may not be the same for the Family API and the OS/2 mode applications.

Bindings

C

#define INCL_DOSMISC
 
USHORT  rc = DosErrClass(Code, Class, Action, Locus);
 
USHORT  Code;          /* Error code for analysis */
PUSHORT Class;         /* Error classification (returned) */
PUSHORT Action;        /* Recommended action (returned) */
PUSHORT Locus;         /* Error locus (returned) */
 
USHORT  rc;            /* return code */

MASM

EXTRN  DosErrClass:FAR
INCL_DOSMISC      EQU 1
 
PUSH   WORD    Code      ;Error code for analysis
PUSH@  WORD    Class     ;Error classification (returned)
PUSH@  WORD    Action    ;Recommended action (returned)
PUSH@  WORD    Locus     ;Error locus (returned)
CALL   DosErrClass

Returns WORD

Example Code

This example attempts to delete a non-existent file. The error returned is then plugged into DosErrClass for more information about the error and what actions should be taken.

#define INCL_DOSQUEUES
 
#define RESERVED 0L
#define FILE_DELETE "adlkjf.dkf"
 
USHORT Error;
USHORT Class;
USHORT Action;
USHORT Locus;
USHORT rc;
 
   Error = DosDelete(FILE_DELETE,  /* File name path */
                     RESERVED);    /* Reserved (must be zero) */
   rc = DosErrClass(Error,         /* Error code for analysis */
                    &Class,        /* Error classification */
                    &Action,       /* Recommended action */
                    &Locus);       /* Error locus */

en/docs/fapi/doserrclass.txt · Last modified: 2021/09/17 13:05 by prokushev