DEVESC ABORTDOC

GreEscape DEVESC_ABORTDOC ends the current document.

Simulation support

This function is mandatory for hardcopy drivers and must be implemented in order to have a valid OS/2 hardcopy driver. For other drivers, it is simulated by a handling routine in the graphics engine.

Syntax

GreEscape(hdc, lEscape, cInCount, pInData, pcOutCount, pOutData, pInstance, lFunction);

Parameters

hdc (HDC) - input

Device context handle.

lEscape (LONG) - input

DEVESC_ABORTDOC escape code.

cInCount (LONG) - input

The handling routine ignores this parameter.

pInData (PBYTE) - input

The handling routine ignores this parameter.

pcOutCount (PLONG) - input

The handling routine ignores this parameter.

pOutData (PLONG) - input

The handling routine ignores this parameter.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreEscape.

Returns

rc (LONG) - returns

Return Code.

The handling routine returns:

DEV_OK

Successful

DEVESC_NOTIMPLEMENTED

Escape is not implemented for the specified code

DEVESC_ERROR

Error

Remarks

The handling routine in the presentation driver discards all data (such as data in a spooler buffer or journal file) received for the current document and closes any files associated with it. The current document is defined as any data back to, and including, the DEVESC_STARTDOC statement.

This function applies to hardcopy drivers only.

The following are three scenarios for ending a job and the steps to be taken by a hardcopy driver:

1. The user ends a job:

a. The spooler calls SplQpControl(SPLC_ABORT).

b. The queue driver calls DevEscape(DEVESC_ABORTDOC).

c. The hardcopy driver sets a flag indicating that the job was aborted and returns the DevEscape(DEVESC_ABORTDOC) thread. The next time PrtWrite returns, the hardcopy driver completes the current page, for example, by sending a form feed and some null data to make sure the printer is not in graphics mode.

d. The hardcopy driver calls PrtClose. Note: The hardcopy driver must be able to accept DEVESC_ABORT while processing data or DEVESC_ENDDOC.

2. The printer runs out of paper or is offline:

a. The spooler function PrtWrite fails and returns an error to the hardcopy driver.

b. If the job ended, the hardcopy driver calls PrtClose. Otherwise, it calls SplMessageBox.

c. The spooler brings up a message box or sends a message to the user, holds the job, and waits on a semaphore until the job is released (possibly across the network), in which case it will return RETRY. If the user selects ABORT, the hardcopy driver calls PrtAbort and PrtClose. If the user selects RETRY, the hardcopy driver will try PrtWrite again (see above). Note: The spooler will ignore all PrtWrite operations after PrtAbort is called. After the hardcopy driver has called PrtClose, it should return errors until the DC is closed.

3. The application ends the job while spooling:

a. The application calls DevEscape(DEVESC_ABORTDOC).

b. The hardcopy driver calls SplQmAbortDoc.

c. The hardcopy driver flags the DC as being aborted.

d. The application calls either DevCloseDC or DevEscape(DEVESC_STARTDOC) to start another job on the same DC.

Note: This escape code is metafiled but not recorded.

Source Code Sample

Declaration:

#define INCL_GRE_DEVICE
#include <os2.h>

HDC      hdc;         /*  Device context handle. */
LONG     lEscape;     /*  DEVESC_ABORTDOC escape code. */
LONG     cInCount;    /*  The handling routine ignores this parameter. */
PBYTE    pInData;     /*  The handling routine ignores this parameter. */
PLONG    pcOutCount;  /*  The handling routine ignores this parameter. */
PLONG    pOutData;    /*  The handling routine ignores this parameter. */
PVOID    pInstance;   /*  Pointer to instance data. */
ULONG    lFunction;   /*  High-order WORD=flags; low-order WORD=NGreEscape. */
LONG     rc;          /*  Return Code. */

rc = GreEscape(hdc, lEscape, cInCount, pInData,
       pcOutCount, pOutData, pInstance, lFunction);

[Category:DEVESC]]