View source for DEVESC STARTDOC

{{DISPLAYTITLE: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 [[PDRREF:Design Considerations for Hardcopy Drivers#Dynamic Job Properties|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:
<pre>

#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);
</pre>


[[Category:DEVESC]]