Click above to get retro games delivered to your door ever month!

 critical()          Install function as the DOS critical error handler
------------------------------------------------------------------------------
 Declaration
   system.hdr

 Syntax
   proc critical extern
   param untyped xFunction

 Arguments
   xFunction is the function to install as the critical error
   handler.

 Return
   None.

 Description
   This procedure installs xFunction as the critical error handler for DOS.
   Whenever a critical error occurs, such as when a diskette drive door opens
   during a copy, DOS calls xFunction to manage the error. This procedure
   allows a program to install its own critical error handler.

   xFunction must be an int function. DOS expects one of the return
   values from xFunction listed in the critical error return values table.

   critical() redirects the DOS interrupt vector 24h to xFunction. Always
   terminate a program through the quit command and not through the _quit
   command when using a critical error handler. The Force runtime shut down
   code removes the int 24h vector when a program is terminated through
   quit.

   Do not install a critical error handler for subprocesses executed through
   the run command. The run command uses command.com to execute any subproces
   and command.com installs its own critical error procedure.

   The declaration for a user-defined critical error handler function must
   conform with the following prototype:

   func int CriticalProc
   param value int     iErrorCode, ;
         value int     iDeviceType, ;
         value logical lChrDevice, ;
         value logical lIgnore, ;
         value logical lRetry, ;
         value logical lFail, ;
         value int     iDiskArea, ;
         value logical lWrite, ;
         value int     iDriveId, ;
         value logical lDrive

   xFunction is called from DOS with the parameters list outlined above. Any
   critical error routine must have the same parameter list. The parameter
   variable names may be changed to suit your needs.

   The parameter variables are initialized by values that originate from DOS.
   Refer to the following table for the meaning of each parameter:

   -----------------------------------------------------------------------
   Parameter        Meaning
   -----------------------------------------------------------------------
   iErrorCode       If lChrDevice is .f., then this contains the error code
                    for the block device

   iDeviceType      This specifies which character device failed.

   lChrDevice       This parameter is .t. if the error occurred on a
                    character device (e.g., printer) versus a block device
                    (e. g. a disk drive).

   lIgnore          If .t. then an ignore return value is allowed.

   lRetry           If .t. then a retry return value is allowed.

   lFail            If .t. then a fail return value is allowed.

   iDiskArea        If lChrDevice is .f., this contains the area of the disk
                    that failed.

   lWrite           If this is .t., the error occurred during a write
                    operation else it occurred during a read operation.

   iDriveId         Contains the failing drive id ( 0 = A:, 1 = B:, etc.).
   -----------------------------------------------------------------------

   Depending on the device type (block device or character device) various
   error codes may be passed to the routine. See the Critical error table
   for available codes.

 Example
   #define EXAMPLE_SYSTEM
   #include example.hdr

   // This example installs a critical error handler that prints out
   // information about the critical errors occurred.
   
   vardef
      char(20) aDevices[4]   := "Standard input", ;
                                "Standard output", ;
                                "NULL device", ;
                                "Clock device"
      char(20) aDiskAreas[4] := "MS-DOS","FAT","Dir", "Data area"
   enddef
   
   func int CriticalHandler
   param value int     iErrorCode, ;
         value int     iDeviceType, ;
         value logical lChrDevice, ;
         value logical lIgnore, ;
         value logical lRetry, ;
         value logical lFail, ;
         value int     iDiskArea, ;
         value logical lWrite, ;
         value int     iDriveId, ;
         value logical lDrive
   vardef
      char cId based iDriveId
      uint uKey
      int  iRet
   enddef
   ? "Critical error occurred"
   if lChrDevice                          // see if a block error or not
      ? "Error on " + aDevices[ iDeviceType ]
   else
      ? "Block device error. Code: ", istr( iErrorCode )
      if lDrive
         iDriveId += 'A'                          // add bias
         ? "Error on drive " + cId + ;
         " in area " + aDiskAreas[ iDiskArea ] + ;
         iifc( lWrite, ;
             " during a write operation.", ;
             " during a read operation." )
      endif
   endif
   repeat
      ? "Ignore, Retry, Abort, Fail? "
      uKey := getkey()
      ?? chr( uKey )
   until lower( chr( uKey ) ) $ "iraf"
   iRet := at( lower( chr( uKey ) ), "iraf" ) - 1
   return( iRet )
   endproc
   
   proc Test_critical
   // install critical error routine at the beginning of the program
   critical( CriticalHandler )
   // trap critical errors during subsequent operations
   type "b:nonsense.txt" // this results in a critical error if no B: drive
   set printer to "LPT1"
   set print on
   ? "hello"       // this results in a critical error if printer is off
   set print off
   ? "End of program"
   endproc

   proc main
   Test_critical()
   endproc