DEVESC_STARTDOC

GreEscape DEVESC_STARTDOC starts a new document. The handling routine in the presentation driver does whatever initialization is required to spool or print the document.

Note: DEVESC_STARTDOC is mandatory at the API for an OD_QUEUED device with PM_Q_STD data.

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.

Refer to Dynamic Job Properties for related information.

Syntax

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

Parameters

hdc (HDC) - input

Device context handle.

lEscape (LONG) - input

DEVESC_STARTDOC escape code.

cInCount (LONG) - input

Number of bytes pointed to by pInData.

pInData (PBYTE) - input

Pointer to a string containing the name of the document.

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 not implemented for specified code

DEVESC_ERROR

Error

Remarks

The driver continues to spool or print data until it receives DEVESC_ENDDOC. This ensures that documents longer than one page are not interspersed with other jobs.

Because DEVESC_STARTDOC is not mandatory at the API, it cannot be assumed that an application (when opening a DC for printing) will pass DEVESC_STARTDOC to the presentation driver. In this case, the presentation driver must initialize a spool file with no name or a journal file in the CompleteOpenDC handling routine. If this is done, the presentation driver should set a flag so that initialization is not repeated if DEVESC_STARTDOC is received. Notice that a handling routine is required for DEVESC_STARTDOC to save the specified document name in the DC instance data.

When this function call is issued for an OD_QUEUED device, the presentation driver must start the recording of data into the spool file by calling SplStdStart. It should also call SplQmStartDoc to pass the name of the spool file to the visual spooler. See SplStdStart and SplQmStartDoc.

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_STARTDOC escape code. */
LONG     cInCount;    /*  Number of bytes pointed to by pInData. */
PBYTE    pInData;     /*  Pointer to a string containing the name of the document. */
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);