FillPhysicalDeviceBlock

OS2_PM_DRV_ENABLE: FillPhysicalDeviceBlock is always called in the initial set of calls to the enable function for a specific application or process.

Syntax

FillPhysicalDeviceBlock(ulSubfunction, pParam1, pParam2)

Parameters

ulSubfunction (ULONG) - input

02h.

pParam1 (PULONG) - input

A pointer to an extended DEVOPENSTRUC structure (the structure is extended by adding a DENPARAMS structure to give three additional fields: ulStateInfo, ulType, and ulHDC).

pszLogAddress: Pointer to the logical address of the device, such as "LPT1Q".
pszDriverName: Pointer to name of the presentation driver, such as 'LaserJet'.
pdriv: Pointer to DRIVDATA structure. This structure contains data generated by the presentation driver during the dialog that sets device modes. See OS2_PM_DRV_DEVMODE.

cb: Number of bytes in the structure
lVersion: Version number
szDeviceName[32]: Device name
abGeneralData: Driver-specific data

pszDataType Pointer to the name of the queue file data type

PM_Q_STD

PM_Q_RAW

pszComment: Pointer to a file description that the spooler could use in messages displayed to the user; usually the name of the application by convention.

pszQueueProcName: Pointer to name of queue driver (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.

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

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

pszNetworkParams: Pointer to a string of networking parameters.

ulStateInfo: Reserved. This field does not contain meaningful information at this time.
ulType: DC type (for example, OD_QUEUED).
ulHDC: :DC handle.

pParam2 (PLONG) - input: Pointer to the dispatch table; Pointer to the dispatch table if Bit 7 was set in FillLogicalDeviceBlock and the Graphics Engine version is 0x202 or later.

Return Code

rc (LONG) - returns

Return codes.

The handling routine should return a LONG integer. Valid values are:

-1 Error.
Other Handle or pointer, ulStateInfo, to the physical device block. This pointer is passed back to the presentation driver in subsequent calls to the OS2_PM_DRV_ENABLE subfunctions 04h and 05h.

Note: The name, pDCI, is used in place of ulStateInfo in some source code.

Remarks

This subfunction is called multiple times only when additional device contexts are enabled if the value of flag bit 0, as set in the initial call to FillLogicalDeviceBlock, shows that each device context requires its own physical device block. However, the graphics engine can call this subfunction at other times. If it is called more than once when the individual DCs do not require separate physical device blocks, the handling routine does nothing and returns the existing ulStateInfo handle or pointer from the DC instance data.

If the param2 (the pointer to the dispatch table) is not null, then the engine version you are running supports rehooking the dispatch table. You would want to change the hooked functions in the dispatch table if your driver supports multiple devices and the device you will be using supports different functions than were hooked in FillLogicalDeviceBlock.

Print jobs must be spooled using the data type given on the call to enable FillLogicalDeviceBlock. Therefore, print jobs queued PM_Q_STD can be printed with queue processor options applied to the job.

The physical device block is located in the driver's global heap. To initialize the block, the presentation driver uses:

Default values set by the presentation driver
Values read from the initialization file
Values from the DEVOPENSTRUC structure

Physical device blocks hold information about the presentation driver and the device that is the same for every instance of a device context. The design of the presentation driver determines what information is held in the physical device block. The following example shows a typical printer physical device block.

typedef struct
{
  Dptr                 PDBDriverName;              /* String for driver name       */
  Dptr                 PDBOutputName;              /* String for output name       */
  unsigned             PDBHandle;                  /* Handle for DOS device        */
  WORD                 PDBOutputType;              /* Type of output; STD/ESC/RAW  */
  DeviceSemaphoreTable PDBDevice;                  /* Pointer to device table      */
  Byte                 PDBScratch[DCT_MAX_SIMPLE]; /* Scratch pad for printer      */
  DDTType              DDT;                        /* Copy of the DDT to be used   */
  WORD                 RasterMode;                 /* Raster type used             */
  WORD                 PrintQuality;               /* Draft or LQ printing         */
  WORD                 Orientation;                /* Portrait or landscape        */
  DWORD                Version;                    /* Driver version number        */
  DevRect              FormClipRegion;             /* Clip region for current form */
  Byte                 DeviceName[32];             /* Model number, and so forth   */
} PDBIType;

Hardcopy drivers must be able to accept a UNC queue name as a logical address on FillPhysicalDeviceBlock. The UNC queue name is passed to the SplQmOpen API that handles rerouting the spool job across the LAN.

Some applications use the SpoolerParams to submit form names. However, the forms can also be supplied in the driver data. SpoolerParams take precedence over the driver data. At FillPhysicalDeviceBlock time, any SpoolerParams are integrated with the pdriv field of the DEVOPENSTRUC.

If pdriv is NULL, it is created by obtaining the data from the system. The hardcopy driver attempts to find a printer in the .INI file that uses this port name, and derives job properties from the device defaults and printer properties.

To find the printer properties in the OS/2 SYS.INI file, the presentation driver should use the APPNAME format:

PM_DD_<printername>,<hardcopydriver>.<devicename>

To get the printername, call SplQueryQueue with the DEVOPENSTRUC pszLogAddress for OD_Queued jobs.

Call SplEnumDevice for OD_Direct jobs.

Search through the structures returned by SplEnumDevice or SplEnumQueue to find the one with the matching pszLogAddress. Use the printername field from the matching structure.

If you do not find your device, look for the pszLogAddress with the name "file".

Note: Hardcopy drivers process all fields except pszQeueProcName, pszQueueProcParams, and pszNetworkParams.