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.