GreOpenDC

GreOpenDC creates an output device context (DC). The new device context inherits the current code page of the process that created it.

This function is supported by the graphics engine.

Syntax

GreOpenDC(hdc, ulType, pszToken, cData, pszData, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

When ulType is OD_ context compatible with bit maps that are used with this device context. If this is NULL, compatibility with the display is assumed.

ulType (ULONG) - input

Type of DC being opened.

Type of device context:

OD_QUEUED: The DC is for a hardcopy device for which output is to be queued by the spooler.

OD_DIRECT: The DC is for a device for which output is not to be queued by the spooler.

OD_INFO: This is similar to OD_DIRECT except that it is only used to retrieve information such as font metrics. Drawing can be done to a presentation space associated with such a DC but no output medium is updated.

OD_MEMORY: The new DC is a memory DC used to contain a bit map. The hdc parameter identifies the device with which the bit map is to be compatible.

pszToken (PSZ) - input

This parameter is ignored by the graphics engine.

cData (LONG) - input

Number of elements in the data structure.

pszData (PDEVOPENDATA) - input

Pointer to data structure.

Pointer to DEVOPENDATA structure:

pszLogAddress: Pointer to logical address, for example, LPT1Q.

pszDriverName: Pointer to presentation driver name, for example, LASERJET.

pdriv: Pointer to a DRIVDATA structure:

cb: Size in bytes of this structure

lVersion: Version number of the data. Version numbers are defined by the presentation driver.

szDeviceName[32]: String identifying the device. Valid values are supplied by the presentation driver.

abGeneralData: General data defined by the presentation driver. This does not contain pointers as they might not be valid when passed to the driver.

pszDataType: Pointer to a data type of the queued file. Supported data types are:

PM_Q_STD

PM_Q_RAW

User-defined data types can also be supported.

pszComment: Pointer to a description of the file that can be displayed by the spooler to the user.

pszQueueProcName: Pointer to name of queue processor.

pszQueueProcParams: Pointer to a string of queue processor parameters.

pszSpoolerParams: Pointer to a string of spooler parameters separated by one or more blanks. Valid parameters are:

FORM=aaa: Identifies the form name for a print job. Multiple names are separated by commas (aaa,bbb,ccc). If this parameter is not present, the current form is used.

Form names are defined by the presentation driver. Valid names are those that would be returned from a call to the GreQueryHardcopyCaps handling routine of the driver.

PRTY=n: Identifies the priority for the print job. The priority can be any value from 1 - 99 (1 is lowest priority). If this parameter is not present, the priority value defaults to 50.

pszNetworkParams: Pointer to a string of networking parameters, which are used only in a network environment. Their nature is defined by the network application.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreOpenDC.

Return Code

rc (HDC) - returns

Return codes.

On completion, the graphics engine returns the handle of the new device context (hdc), or DEV_ERROR if an error occurs.

Possible Errors Detected: When an error is detected, the graphics engine calls WinSetErrorInfo to post the condition. Reasons for failure of this function include:

• PMERR_BASE_ERROR
• PMERR_BITMAP_IS_SELECTED
• PMERR_COORDINATE_OVERFLOW
• PMERR_DEV_FUNC_NOT_INSTALLED
• PMERR_EXCEEDS_MAX_SEG_LENGTH
• PMERR_HBITMAP_BUSY
• PMERR_HDC_BUSY
• PMERR_HUGE_FONTS_NOT_SUPPORTED
• PMERR_INSUFFICIENT_MEMORY
• PMERR_INV_BACKGROUND_COL_ATTR
• PMERR_INV_BACKGROUND_MIX_ATTR
• PMERR_INV_BITMAP_DIMENSION
• PMERR_INV_CHAR_DIRECTION_ATTR
• PMERR_INV_CHAR_MODE_ATTR
• PMERR_INV_CODEPAGE
• PMERR_INV_COLOR_ATTR
• PMERR_INV_COORD_SPACE
• PMERR_INV_COORDINATE
• PMERR_INV_DC_DATA
• PMERR_INV_DC_TYPE
• PMERR_INV_DRIVER_NAME
• PMERR_INV_HBITMAP
• PMERR_INV_HDC
• PMERR_INV_HRGN
• PMERR_INV_ID
• PMERR_INV_IN_AREA
• PMERR_INV_IN_PATH
• PMERR_INV_INFO_TABLE
• PMERR_INV_LENGTH_OR_COUNT
• PMERR_INV_LINE_TYPE_ATTR
• PMERR_INV_MIX_ATTR
• PMERR_INV_PATTERN_REF_PT_ATTR
• PMERR_INV_PATTERN_SET_ATTR
• PMERR_INV_PATTERN_SET_FONT
• PMERR_INV_RECT
• PMERR_INV_REGION_CONTROL
• PMERR_INV_SCAN_START

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Remarks

Subsequent calls to DosSetCp do not alter the code page of an existing DC. Default VIO and KBD code pages are always in the last code page set by any application process.

When this function is called for the first time, the graphics engine performs the following sequence:

DosLoadModule("NEWDRIVER", &hDriver)
                  /****************************************************/
                  /* Load the presentation driver DLL file.           */
                  /****************************************************/

DosGetProcAddr(hDriver, "OS2_PM_DRV_ENABLE", &Enable)
                  /****************************************************/
                  /* Find the presentation driver's Enable function.  */
                  /* See OS2_PM_DRV_ENABLE.         */
                  /****************************************************/

*Enable(FillLogicalDeviceBlock, &DispatchTable)
                  /****************************************************/
                  /* The presentation driver must:                    */
                  /*   Save the addresses of the engine simulations   */
                  /*   Overwrite the dispatch table, as necessary     */
                  /*   Hook the ExitList for the calling process      */
                  /****************************************************/

hPhysDev=*Enable(FillPhysicalDeviceBlock, pDevOpenStructure)
                  /****************************************************/
                  /* Create the physical device block.                */
                  /****************************************************/

pInstance=*Enable(EnableDeviceContext, hdc, Type, hPhysDev)
                  /****************************************************/
                  /* The presentation driver must create an instance  */
                  /* data structure for the DC.                       */
                  /****************************************************/

*Enable(CompleteOpenDC, hdc, pInstance)
                  /****************************************************/
                  /* The presentation driver must inform the system   */
                  /* that the DC is open and ready to receive output. */
                  /****************************************************/

For subsequent calls to GreOpenDC for the same DC, the graphics engine calls Enable (EnableDeviceContext) to create a new instance for the DC and then calls Enable (CompleteOpenDC). When GreOpenDC is called for the same DC by a different process, the graphics engine calls DosLoadModule to load the presentation driver. It then calls Enable (FillLogicalDeviceBlock), Enable (EnableDeviceContext), and Enable (CompleteOpenDC).

Sample Code

#define INCL_GRE_DCS
#include <os2.h>

HDC             hdc;        /*  Device context handle. */
ULONG           ulType;     /*  Type of DC being opened. */
PSZ             pszToken;   /*  This parameter is ignored by the graphics engine. */
LONG            cData;      /*  Number of elements in the data structure. */
PDEVOPENDATA    pszData;    /*  Pointer to data structure. */
PVOID           pInstance;  /*  Pointer to instance data. */
ULONG           lFunction;  /*  High-order WORD=flags; low-order WORD=NGreOpenDC. */
HDC             rc;         /*  Return codes. */

rc = GreOpenDC(hdc, ulType, pszToken, cData, pszData, pInstance, lFunction);