Although GDI and the spooler attempt to report all printing errors to the user, your application must be prepared to report out-of-disk and out-of-memory conditions. When there is an error in processing a particular escape, such as STARTDOC or NEWFRAME, the Escape function returns a value less than zero. Out-of-disk and out-of-memory errors usually occur on a NEWFRAME escape. In this case, the return value includes an SP_NOTREPORTED bit. If the bit is clear, GDI has already notified the user. If the bit is set, the application needs to notify the user. The bit is typically set for general-failure, out-of-disk-space, and out-of-memory errors.
The following example shows how to process unreported errors during printing:
int status;
.
.
.
status = Escape(hPrDC, NEWFRAME, 0, 0L, 0L);
1 if (status < 0) { /* Any unreported errors? */
if(status & SP_NOTREPORTED) { /* Yes */
2 switch (status) {
case SP_OUTOFDISK:
/* inform user of situation
and perform any necessary processing */
break;
case SP_OUTOFMEMORY:
/* inform user of situation
and perform any necessary processing */
break;
default:
/* inform user of situation
and perform any necessary processing */
break;
}
}
3 else /* Reported, but may need further action */
switch(status|SP_NOTREPORTED) {
case SP_OUTOFDISK:
/* perform any necessary processing */
break;
case SP_OUTOFMEMORY:
/* perform any necessary processing */
break;
}
}
In this example:
| 1 | The first if statement checks to see if the value that the Escape function returns, status, is less than zero and the SP_NOTREPORTED bit is set. (When Windows sets the SP_NOTREPORTED bit, it indicates that this error has not been reported to the user.) If these two conditions are met, then the application must process the unreported error. |
| 2 | In this example, the application uses a switch to provide special responses to the SP_OUTOFDISK error and the SP_OUTOFMEMORY error. For all other unreported errors, the application simply provides a general failure alert. |
| 3 | If the status variable is less than zero but SP_NOTREPORTED is not set, then Windows has already reported the error to the user. However, the application can still process these reported errors. |
In most cases, the correct response to an unreported error is to display a message box explaining the error and to terminate the print request. If the error has already been reported, you can terminate the request, then restart it after additional disk or memory space has been made available.