DEVESC_STARTDOC_WPROP

GreEscape DEVESC_STARTDOC_WPROP will reset the device context information and presentation space information to be based on the new job properties that are passed in. This should be equivalent to the result of a new DevOpenDC with the new job properties.

Simulation support

This function is mandatory for hardcopy drivers and must be implemented in order to have a valid OS/2 hardcopy driver.

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_WPROP escape code.

cInCount (LONG) - input

Number of bytes pointed to by pInData.

pInData (PBYTE) - input

The title of the document (same as GreEscape DEVESC_STARTDOC).

pcOutCount (PLONG) - input

Pointer to the number of bytes pointed to by pOutData.

pOutData (PLONG) - input

Pointer to the printer driver's job properties as returned by SplQueryQueue.

These job properties may also have been modified by GreEscape DEVESC_SETJOBPROPERTIES.

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_ERROR

Error

Remarks

DEVESC_STARTDOC_WPROP is used to change the job properties at the beginning of a document. Since this function is new, applications will call GreEscape DEVESC_QUERYESCSUPPORT to determine if you support this DevEscape.

The DevEscape path has a handle to a device context (HDC) that should already have printer property information associated with the HDC. Job property information may change or may be dependent upon the printer property information in the HDC. In that case, if an application passes job properties for a different device or for a different spooler printer name, then misleading information will be returned.

This function will change all characteristics of the HDC and PS. An application must query again information such as DevQueryCaps, DevQueryHardcopyCaps, the list of device fonts, and so on. In addition, all previously opened memory DCs are no longer considered compatible with the DC.

You also should check the version level of the graphics engine, since GreResetDC2 is a new API and only exists on engine levels 0x0234 and above. If you are using an older version level, then treat DEVESC_STARTDOC_WPROP as a DEVESC_STARTDOC.

This function also performs the same actions as calling DEVESC_STARTDOC.

LONG ENGENTRY Escape (HDC       hdc,
                      LONG      lEscape,
                      LONG      cInCount,
                      PBYTE     pInData,
                      PLONG     pcOutCount,
                      PBYTE     pOutData,
                      PDDC      pddc,
                      ULONG     ulFunction)
{
   switch (lEscape)
   {
   case DEVESC_STARTDOC:
   case DEVESC_STARTDOC_WPROP:
   {
      if (GRE_234 > globals.ulGreVersion)
      {
         /* Switch DEVESC_STARTDOC_WPROP to DEVESC_STARTDOC
         ** on back level versions of the engine.
         */
         lEscape = DEVESC_STARTDOC;
         break;
      }

      if (DEVESC_STARTDOC_WPROP == lEscape)
      {
         /* This does a number of things such as:
         **   1) Sanity check input driver data
         **   2) Walk through new job properties and set up
         **      DC information (papersize, orientation, color depth, etc)
         **   3) Set up device surface structure
         */
         ReinitializeWithJobProps (pddc, (PDRIVDATA)pOutData);
      }

      // For Raw Data only jobs do not need to reset device surface
      if (!pddc->pdb->fRawOnly)
         /* This does a number of things such as:
         **   1) Allocate the device surface memory
         **   2) Call engine's SetDeviceSurface function.
         */
         CreateAndSetDeviceSurface (pddc);

      if (DEVESC_STARTDOC_WPROP == lEscape)
      {
         /* Inform the engine that your characteristics have changed
         ** and it should requery the information.
         */
         GreResetDC2 (pddc->pdb->hdc, 0);
      }

      // Normal STARTDOC processing follows...
      break;
   }
   }

   return lrc;
}

Source Code Sample

Declaration:

#define INCL_DEV
#define INCL_DEVDJP
#include <os2.h>

HDC      hdc;         /*  Device context handle. */
LONG     lEscape;     /*  DEVESC_STARTDOC_WPROP escape code. */
LONG     cInCount;    /*  Number of bytes pointed to by pInData. */
PBYTE    pInData;     /*  The title of the document (same as GreEscape DEVESC_STARTDOC). */
PLONG    pcOutCount;  /*  Pointer to the number of bytes pointed to by pOutData. */
PLONG    pOutData;    /*  Pointer to the printer driver's job properties as returned by SplQueryQueue. */
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);