DEVESC NEWFRAME WPROP

Based on the new job properties that are passed in, GreEscape DEVESC_NEWFRAME_WPROP, will reset the device context information and presentation space information. This action should be equivalent to the result of a new DevOpenDC with the new job properties. Refer to Dynamic Job Properties for related information.

Simulation support

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

Syntax

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

Parameters

hdc (HDC) - input

Device context handle.

lEscape (LONG) - input

DEVESC_NEWFRAME_WPROP escape code.

cInCount (LONG) - input

Not used-should be 0.

pInData (PBYTE) - input

Not used-should be NULL.

pcOutCount (PLONG) - input

A 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 possibly have been modified by GreEscape DEVESC_SETJOBPROPERTIES.

Note: pOutData is used as an input parameter for this call.

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

GreEscape DEVESC_NEWFRAME_WPROP is used to change the job properties at the beginning of a new page. 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_NEWFRAME_WPROP as a DEVESC_NEWFRAME.

This function also performs the same actions as calling DEVESC_NEWFRAME.

Sample Source Code

Declaration

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

HDC      hdc;         /*  Device context handle. */
LONG     lEscape;     /*  DEVESC_NEWFRAME_WPROP escape code. */
LONG     cInCount;    /*  Not used-should be 0. */
PBYTE    pInData;     /*  Not used-should be NULL. */
PLONG    pcOutCount;  /*  A pointer to the number of bytes pointed to by pOutData. */
PLONG    pOutData;    /*  Pointer to the printer driver's job properties */
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);

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

LONG ENGENTRY Escape (HDC        hdc,
                      LONG       lEscape,
                      LONG       cInCount,
                      PBYTE      pInData,
                      PLONG      pcOutCount,
                      PBYTE      pOutData,
                      PDDC       pddc,
                      ULONG      ulFunction)
{
   switch (lEscape)
   {
   case DEVESC_NEWFRAME:
   case DEVESC_NEWFRAME_WPROP:
   {
      if (GRE_234 > globals.ulGreVersion)
      {
         /* Switch DEVESC_NEWFRAME_WPROP to DEVESC_NEWFRAME
         ** on back level versions of the engine.
         */
         lEscape = DEVESC_NEWFRAME;
         break;
      }
      if (DEVESC_NEWFRAME_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);

         /* This does a number of things such as:
         ** 1) Allocate the device surface memory
         ** 2) Call engine's SetDeviceSurface function.
         */
         CreateAndSetDeviceSurface (pddc);
         /* Inform the engine that your characteristics have changed
         ** and it should requery the information.
         */
         GreResetDC2 (pddc->pdb->hdc, 0);
      }

      // Normal NEWFRAME processing...
      break;
   }
   }

   return lrc;
}