DevEscape

This function allows applications to access facilities of a device not otherwise available through the API. Escapes are, in general, sent to the presentation driver and must be understood by it.

Syntax

DevEscape (hdc, lCode, lInCount, pbInData, plOutCount, pbOutData)

Parameter

hdc (HDC) - input

Device-context handle.

lCode (LONG) - input

Escape code.

If the device context is of type OD_QUEUED with a PM_Q_STD spool file, some escapes are sent to the presentation driver and others are recorded in the spool file (depending on the escape code). If the device context is of type OD_METAFILE, all escapes are metafiled. If the device context is of any type other than OD_QUEUED (with a PM_Q_STD spool file) or OD_METAFILE, all escapes are sent to the presentation driver.

The description for each standard escape specifies which of these categories the escape falls into.

Devices can define additional escape functions using user lCode values, that have the following ranges:

• 32 768 through 40 959 Not metafiled and not recorded (sent to presentation driver for PM_Q_STD)
• 40 960 through 49 151 Metafiled only (sent to presentation driver for PM_Q_STD)
• 49 152 through 57 343 Metafiled and recorded (not sent to presentation driver) for PM_Q_STD
• 57 344 through 65 535 Recorded only (not sent to presentation driver for PM_Q_STD).

The following escapes are defined:

DEVESC_QUERYESCSUPPORT

DEVESC_GETSCALINGFACTOR

DEVESC_STARTDOC

DEVESC_ENDDOC

DEVESC_ABORTDOC

DEVESC_NEWFRAME

DEVESC_RAWDATA

DEVESC_QUERYVIOCELLSIZES

DEVESC_SETMODE

lInCount (LONG) - input

Input data count.

Number of bytes of data in the pbInData buffer.

pbInData (PBYTE) - input

The input data required for this escape.

plOutCount (PLONG) - in/out

Output data count.

plOutCount is the number of bytes of data in the pbOutData buffer.

If data is returned in pbOutData, plOutCount is updated to the number of bytes of data returned.

pbOutData (PBYTE) - output

Output data.

pbOutData is a buffer that receives the output from this escape. If plOutCount is null, no data is returned.

lResult (LONG) - returns

Implementation error indicator:

DEVESC_ERROR Error

DEVESC_NOTIMPLEMENTED Escape not implemented for specified code

DEV_OK OK.

Remarks

The data fields for standard escapes are:

DEVESC_QUERYESCSUPPORT

Queries whether a particular escape is implemented by the presentation driver. The return value gives the result. This escape is not metafiled or recorded.

lInCount

Number of bytes pointed to by pbInData.

pbInData

The buffer contains an escape code value specifying the escape function to be checked.

plOutCount

Not used; can be set to 0.

pbOutData

Not used; can be set to null.

DEVESC_GETSCALINGFACTOR

Returns the scaling factors for the x and y axes of a printing device. For each scaling factor, an exponent of two is put in pbOutData. Thus, the value 3 is used if the scaling factor is 8.

Scaling factors are used by devices that cannot support graphics at the same resolution as the device resolution.

This escape is not metafiled or recorded.

lInCount

Not used; can be set to 0.

pbInData

Not used; can be set to null.

plOutCount

The number of bytes of data pointed to by pbOutData. On return, this is updated to the number of bytes returned.

pbOutData

The address of a SFACTORS structure, which on return contains the scaling factors for the x and y axes.

DEVESC_STARTDOC

Indicates that a new print job is starting. All subsequent output to the device context is spooled under the same job identifier until a DEVESC_ENDDOC occurs.

GpiAssociate must be issued to associate the presentation space with the device context before issuing this escape.

This escape is metafiled but not recorded.

lInCount

Number of bytes pointed to by pbInData.

pbInData

The buffer contains a null-terminated string, specifying the name of the document.

plOutCount

Not used; can be set to 0.

pbOutData

Not used; can be set to null.

DEVESC_ENDDOC

Ends a print job started by DEVESC_STARTDOC. This escape is metafiled but not recorded.

lInCount

Not used; can be set to 0.

pbInData

Not used; can be set to null.

plOutCount

Set equal to 2.

pbOutData

The buffer contains a USHORT specifying the job identifier if a spooler print job is created.

DEVESC_ABORTDOC

Aborts the current job, erasing everything the application has written to the device since the last DEVESC_STARTDOC, including the DEVESC_STARTDOC. This escape is metafiled but not recorded.

lInCount

Not used; can be set to 0

pbInData

Not used; can be set to null

plOutCount

Not used; can be set to 0

pbOutData

Not used; can be set to null.

DEVESC_NEWFRAME

Signals when an application has finished writing to a page and wants to start a new page. It is similar to GpiErase processing for a screen device context, and causes a reset of the attributes. This escape is used with a printer device to advance to a new page. This escape is metafiled and recorded.

lInCount

Not used; can be set to 0

pbInData

Not used; can be set to null

plOutCount

Not used; can be set to 0

pbOutData

Not used; can be set to null.

DEVESC_RAWDATA

Allows an application to send data directly to a presentation driver. For example, in the case of a printer driver, this could be a printer data stream. If DEVESC_RAWDATA is mixed with other data (such as GPI data) being sent to the same page of a device context, the results are unpredictable and depend upon the action taken by the presentation driver. For example, a presentation driver might ignore GPI data if DEVESC_RAWDATA is mixed with it on the same page. In general, DEVESC_RAWDATA should be sent either to a separate page (using the DEVESC_NEWFRAME escape to obtain a new page) or to a separate document (using the DEVESC_STARTDOC and DEVESC_ENDDOC escapes to create a new document). This escape is metafiled and recorded.

lInCount

Number of bytes pointed to by pbInData pbInData Pointer to the raw data plOutCount Not used; can be set to 0 pbOutData Not used; can be set to null.

DEVESC_QUERYVIOCELLSIZES

Returns the VIO cell sizes supported by the presentation driver.

This escape is not metafiled or recorded.

lInCount

Not used; can be set to 0

pbInData

Not used; can be set to null.

plOutCount

The number of bytes of data pointed to by pbOutData. It must be an even multiple of the size in bytes of the LONG data type. On return, this is updated to the number of bytes

returned.

pbOutData

The address of a buffer, which on return contains a VIOSIZECOUNT structure, immediately followed by count copies of a VIOFONTCELLSIZE structure.

If plOutCount is less than the size of a LONG data type, plOutCount is updated to zero,

and nothing is returned in the buffer pointed to by pbOutData.

If plOutCount is equal to the size of a LONG data type, pbOutData returns the number of

VIO cell sizes that can be returned by this escape. The buffer pointed to by pbOutData is updated so that maxcount is the number of VIO cell sizes that can be returned.

If plOutCount is greater than the size of a LONG data type, pbOutData returns the VIO cell

sizes that are supported. The buffer pointed to by pbOutData is updated so that:

• maxcount is the number of VIO cell sizes that can be returned
• count is the number of VIO cell sizes returned (may be zero if plOutCount is equal to twice the size of a LONG data type)
• count copies of a VIOFONTCELLSIZE structure are returned.

DEVESC_SETMODE

Sets the printer into a particular mode. It is optional for printer drivers to support this escape, but those that do support it need to be aware of the code page of any built-in fonts. For example, if only code page 437 is built in, it is used if 437 is requested by DEVESC_SETMODE; however, if code page 865 is requested, a suitable code page/font could be downloaded. This escape is metafiled and recorded.

lInCount

Number of bytes pointed to by pbInData

pbInData

Buffer contains an ESCSETMODE structure

plOutCount

Not used; can be set to 0

pbOutData

Not used; can be set to null.

Errors

Possible returns from WinGetLastError

• PMERR_INV_ESC_CODE (0x206D) - An invalid escape code was used in a call to DevEscape.
• PMERR_INV_HDC (0x207C) - An invalid device-context handle or (micro presentation space) presentation-space handle was specified.
• PMERR_INV_LENGTH_OR_COUNT (0x2092) - An invalid length or count parameter was specified.
• PMERR_ESC_CODE_NOT_SUPPORTED (0x202B) - The code specified with DevEscape is not supported by the target device driver.
• PMERR_INV_ESCAPE_DATA (0x206E) - An invalid data parameter was specified with DevEscape.

Related Functions

• Prerequisite Functions: DevOpenDC

• GpiAssociate (for DEVESC_STARTDOC)
• GpiErase (for DEVESC_NEWFRAME)

Graphic Elements and Orders

DevEscape functions generate orders only when metafiling. Order: GEESCP

Example Code

This example uses DevEscape to access facilities of a device that would otherwise be unavailable through the normal Device API set. Here, a new page in a print job is started.

#define INCL_DEV  /* Device Function definitions  */
#include <os2.h>

LONG  lResult;    /* Error code or not implemented warning code */
HDC   hdc;        /* Device-context handle                */
LONG  plOutCount; /* length of output buffer(input), number of bytes returned(output) */
PBYTE pbOutData;  /* output buffer                        */

/* for the NEWFRAME, input and output buffers are not used, so set the buffer lengths
   to zero(0) and set the buffers to NULL */
plOutCount = 0;
pbOutData = NULL;

lResult = DevEscape(hdc, DEVESC_NEWFRAME, 0L, NULL, &plOutCount,pbOutData);