View source for DEVESC NEWFRAME WPROP

{{DISPLAYTITLE: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
<pre>
#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);
</pre>
<pre>
#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;
}
</pre>

[[Category:DEVESC]]