DEVESC_NEXTBAND

GreEscape DEVESC_NEXTBAND indicates that there is no more data for the current band, and gets the coordinates of the next band. If there is no current band, the handling routine returns the coordinates of the first band.

Simulation support

This function is mandatory for hardcopy drivers, but may simply return a DEVESC_NOTIMPLEMENTED code. For other drivers, it is simulated by a handling routine in the graphics engine.

Syntax

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

Parameters

hdc (HDC) - input: Device context handle.

lEscape (LONG) - input: DEVESC_NEXTBAND escape code.

cInCount (LONG) - input: The handling routine ignores this parameter.

pInData (PBYTE) - input: The handling routine ignores this parameter.

pcOutCount (PLONG) - input: Number of bytes of data pointed to by pOutData.; On return, this is updated to the number of bytes actually returned.

pOutData (PLONG) - input: Pointer to BANDRECT structure.; Points to where the device coordinates of the next band are returned:; xLeft X-coordinate of the lower-left corner of the rectangular band; yBottom Y-coordinate of the lower-left corner of the rectangular band; xRight X-coordinate of the top-right corner of the rectangular band; yTop Y-coordinate of the top-right corner of the rectangular band; An empty rectangle (xLeft=xRight or yTop=yBottom) marks the end of the banding operation.

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

DEVESC_NEXTBAND is used by programs that do their own banding. It is not necessary to support this escape code in hardcopy drivers for devices that cannot use banded output. See Banding. Notice that DEVESC_NEWFRAME is issued to start a new page.

Note: This escape code is implemented by old hardcopy drivers that support banding and is being phased out.

This escape code is metafiled but not recorded.

Sample Source Code

Declaration:

#define INCL_GRE_DEVICE
#include <os2.h>

HDC       hdc;           /* Device context handle. */
LONG      lEscape;       /* DEVESC_NEXTBAND escape code. */
LONG      cInCount;      /* The handling routine ignores this parameter. */
PBYTE     pInData;       /* The handling routine ignores this parameter. */
PLONG     pcOutCount;    /* Number of bytes of data pointed to by pOutData. */
PLONG     pOutData;      /* Pointer to BANDRECT structure. */
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);