We have been handling the return value from the Escape function in a relatively simple manner: If Escape returns a negative value, then an error has occurred, and the printing operation is aborted. You can report more precise errors to the user by checking the Escape return value against five identifiers defined in WINDOWS.H. WINDOWS.H also includes an identifier called SP_NOTREPORTED, which is equal to 0x4000. If a bitwise AND of the return value from Escape with SP_NOTREPORTED is 0, then the error has already been reported to the user. A bitwise OR of the return value of Escape with SP_NOTREPORTED can be used to compare with the five error-code identifiers whether the error has been reported or not.
The following function shows one method of obtaining a text string identifying the error. The function returns NULL if no error has occurred or if the error has already been reported to the user:
char *GetErrorText (short nEscapeReturn)
{
static char *szErrorText [] = { "General Error",
"Canceled from Program",
"Canceled from Print Manager",
"Out of disk space",
"Out of memory space" } ;
if (nEscapeReturn >= 0)
return NULL ;
if ((nEscapeReturn & SP_NOTREPORTED) == 0)
return NULL ;
return szErrorText [~nEscapeReturn] ;
}
The five error codes (with some likely causes) are as follows:
SP_ERROR (0xFFFF, or -1)—Defined as indicating a ”general error,“ this is the only error code that can be returned from STARTDOC. It can occur if the GDI module or the printer device driver can't begin a document. If the Print Manager isn't loaded, you can also get this error from STARTDOC if another program is currently printing or if the printer is off line or has no paper.
SP_APPABORT (0xFFFE, or -2)—This code is documented as indicating that the program's abort procedure has returned a FALSE value. However, this is the case only if the Print Manager isn't loaded. If the Print Manager is loaded and if the abort procedure is passed an nCode parameter of 0 and then returns a FALSE, the NEWFRAME Escape call will return a positive value, not an SP_APPABORT error.
SP_USERABORT (0xFFFD, or -3)—This code indicates that the user canceled the printing job from the Print Manager.
SP_OUTOFDISK (0xFFFC, or -4)—This code indicates that no more disk space is available. You'll encounter this error code if the disk drive containing the TEMP subdirectory can't accommodate any temporary metafiles or spooler files. If the TEMP subdirectory has some existing temporary spooler files, then the abort procedure is called during a NEWFRAME or NEXTBAND Escape call with an nCode parameter of SP_OUTOFDISK. If the abort procedure then returns FALSE, the Escape call returns SP_OUTOFDISK.
SP_OUTOFMEMORY (0xFFFB, or -5)—This code indicates that insufficient memory is available for printing.