OS2 PM DRV DEVMODE

OS2_PM_DRV_DEVMODE must be compiled to run at Ring 2 Conforming (privilege level 2) or Ring 3 (privilege level 3).

The Device Modes entry point is exported by hardcopy drivers as OS2_PM_DRV_DEVMODE to support the DevPostDeviceModes function at the application programming interface (API). This call is used to display the job and printer properties dialogs.

Syntax

OS2_PM_DRV_DEVMODE(pDriverData, pszDriverName, pszDeviceName, pszPrinterName, lOptions)

Parameters

pDriverData (PDRIVDATA) - input

NULL or pointer to memory location for DRIVDATA structure.

pszDriverName (PSZ) - input

A pointer to a string containing the name of the hardcopy driver.

pszDeviceName (PSZ) - input

A pointer to a string containing the device name, such as HP LASERJET II P, as defined by the presentation driver.

pszPrinterName (PSZ) - input

A NULL or pointer to a string containing the printer name, such as PRINTER1. A NULL pointer or NULL string are both valid conditions for this parameter.

lOptions (ULONG) - input

Identifies the action that should be taken by the presentation driver:

DPDM_POSTJOBPROP

Display a dialog for job properties and return the DRIVDATA structure. Do not update OS2SYS.INI. The abGeneralData field contains the job properties.

DPDM_CHANGEPROP

Display a dialog for printer properties and device defaults, update the OS2SYS.INI file, and return the DRIVDATA structure. The abGeneralData field contains the printer properties.

DPDM_QUERYJOBPROP

Return the DRIVDATA structure with device default job properties. Do not display a dialog. The abGeneralData field contains the device default job properties.

All other values are reserved.

Return Code

rc (ULONG) - returns

Return codes.

The handling routine in the presentation driver returns a LONG integer. Valid values are:

DPDM_ERROR

Error.

DPDM_NONE

There are no settable options.

>0

The number of bytes for the required DRIVDATA structure when the input pointer pDriverData is equal to NULL.

DEV_OK

The data block pointed to by the input parameter pDriverData was initialized when the pDriverData input pointer is not equal to NULL.

Remarks

In the hardcopy driver, the handling routine generates a DRIVDATA structure that defines the current setting of printer properties or job properties. These properties identify the options that are set when the job is printed. All hardcopy drivers must contain a handling routine for OS2_PM_DRV_DEVMODE.

Applications such as the Presentation Manager Print Object call DevPostDeviceModes to configure the device. Notice that such applications usually call this function twice, first with a NULL value for pDriverData to query the length of the driver's DRIVDATA structure, and then with a valid pointer to get the data.

Note

LONG, APIENTRY, PDRIVDATA (DRIVDATA *), and PSZ (char *) are defined in OS2DEF.H, which is included through the header file OS2.H.

The details about printer properties and job properties are stored as a set of flags or values in the array abGeneralData. Do not store pointers in this array because they might not be valid when they return. This array is driver-specific. The flags needed and the location of those flags in the array must be determined to fully exploit the capabilities of the device.

A list of related terms and their definitions follows.

Properties

This is a descriptive term for software and hardware characteristics of hardcopy devices, such as printers, plotters, and cameras. For a particular property, there is a list of possible values from which the user can select one or more values. This list can be extended by adding user-defined values, but can never be reduced by removing predefined values. For example, predefined forms, Letter and A4, can never be deleted. However, the user can add a form named "Blue Letter" to describe colored separator paper.

Job Properties

These are properties that can be changed from job to job. Typically, job property values are set in the printer by sending software commands. Some job properties can be derived from printer properties. Examples of typical job properties are:

• Paper orientation
• Forms required
• Device resolution
• Simplex (one-sided) or duplex (double-sided) printing

Printer Properties

These are properties that describe the physical characteristics of a printer. Printer properties are mutually exclusive of job properties (see the previous description). Examples of typical printer properties are:

• Number of paper bins
• Form size in each paper bin
• Hardware fonts installed
• Font cartridges installed (cartridge slots download fonts during system startup)
• Availability of optional add-on hardware, such as an envelope feeder or SCSI hard disk

User-Definable Values

For each individual property, there is a list of possible values that can be extended by making use of user-definable values (such as user-defined forms). User-definable values can only be defined or changed in the printer property dialogs, that is, when OS2_PM_DRV_DEVMODE is called with the DPDM_CHANGEPROP flag.

Selected Values

Given a particular property and its set of values, the user can choose one or more to be "selected" values. For example, Paper Bin 1 contains Letter paper, and the envelope bin accepts Com10, DL, or B5 envelopes.

Device Default Properties

Device defaults can be set in the printer properties dialog. These defaults do not usually contain user-defined values. The selectable values are chosen according to country code and the most common delivery configuration of the device. In a hardcopy driver that supports multiple devices, it is possible that the device default properties are different for different devices.

Option Flags

• DPDM_POSTJOBPROP
• DPDM_CHANGEPROP
• DPDM_QUERYJOBPROP

DPDM_POSTJOBPROP

Any application can call the OS2_PM_DRV_DEVMODE handling routine by using the flag option, DPDM_POSTJOBPROP. The calling program requires the user to select properties for a specific job such as draft or letter quality and size, style, and color of the default font. The source for the default value of the properties and device defaults is determined by the pszPrinterName parameter:

• If pszPrinterName points to a valid string, the handling routine searches the PM_PrinterName,Driver.DeviceName section of OS2SYS.INI for the printer properties associated with the name.
• If pszPrinterName is NULL or points to a NULL string, the handling routine uses the values from abGeneralData in the DRIVDATA structure addressed by pDriverData.

In both cases, the initial default values are used if the handling routine cannot find a valid abGeneralData array.

When called with the DPDM_POSTJOBPROP flag option, hardcopy drivers:

• Examine the pDriverData parameter. If the pDriverData is valid, use these values as a basis of the values to be displayed in the user dialog. If the pDriverData is NULL , the driver version number is 0, or the pDriverData is not meaningful, use a set of device default job properties. There are two cases:
  • If the printer name is given, use the job properties.
  • If the printer name is NULL or not a valid printer name, use the job properties derived from the device defaults.
• Update the job property values before displaying the user dialog. If the printer name is given, the printer properties stored by that printer are examined and compared with the job properties. There are two cases:
  • Add extra values. If extra printer property values are defined, those that are applicable are added to the user dialog. For example, if a new user-defined form was added to the printer properties, it appears on the list of selectable forms.
  • Remove values. If printer property values are deleted, the deleted values do not appear in the user dialog. If all the selected values are deleted from the printer properties, the device default becomes the selected value. For example, if a user-defined form is removed from the printer properties, it is replaced by a device default such as Letter (for the United States) or A4 (for France).
• Display the user dialog (the user makes selections). Note that if the user selects the Cancel push button on the dialog, the hardcopy driver returns pDriverData unmodified. If pDriverData contains zeros or is not understood by the hardcopy driver, the driver should return the default job properties for the device.
• Return the data to the caller. Any updates in the user dialog must be reflected in an updated pDriverData parameter, which is passed back to the caller of OS2_PM_DRV_DEVMODE. This update must occur regardless of whether an actual printer name or NULL printer name was passed in.

DPDM_CHANGEPROP

Only the Workplace Shell calls DevPostDeviceModes using this flag option. Applications that must change options for a particular job use DPDM_POSTJOBPROP.

The calling program requires the user to identify the current settings of the device defaults and select the device default properties. This usually requires two dialogs, one to identify options (such as the paper size currently in the device and details of any memory or font cartridges that are installed), and the other to establish a set of device default properties.

An error is returned if a NULL printer name is used. The pDriverData parameter is ignored. Given that a printer name is passed in, the hardcopy driver needs to retrieve the printer properties for that printer and the individual device for that driver. This means the hardcopy driver must store these properties separately from properties for other printers, in order to prevent properties and selected values of one printer from interacting with another. An example of printer property interaction might be if one printer has a user-defined form in Bin 1, and the other has no extra forms. It would be possible to send a job to the second printer that uses a form that is only available in the first printer.

The hardcopy driver builds a complex keyname containing the printer name, hardcopy driver and device name. For ease of use, store the printer properties under individual property keynames.

The format is easily extended for new printer properties. The format of the appname is:

PM_DD_<printer name>,<hardcopy driver>.<device name>

Two examples might be:

appname = PM_DD_PRINTER1, LASERJET.HP LaserJet II
keyname = BINFORMS
value = Assignment of forms to paper bins
keyname = FORMSDATA
value = Definition of forms

appname = PM_DD_PRINTER2, LASERJET.HP LaserJet II
keyname = BINFORMS
value = Assignment of forms to paper bins.

The advantage of this method is that the appname is standardized. Therefore:

• When a printer is renamed, the Workplace Shell can automatically move the data to a new appname without the hardcopy driver involved.
• The initialization file can be cleaned up by the Workplace Shell when a printer is deleted, or when the default hardcopy driver for a printer is changed.

DPDM_QUERYJOBPROP

Any application can call OS2_PM_DRV_DEVMODE by using the DPDM_QUERYJOBPROP flag option to find out the device default job properties. These defaults are derived from the printer properties. There are two cases:

• The printer name is given so the properties can be retrieved from OS2SYS.INI under the PM_DD_Printerxxx application name.
• The printer name is not given and the hardcopy driver uses the device default printer properties for that device.

Note

Information concerning the design of dialogs and menus is given in the Common User Access Interface Design Guide.

Example Code

#include <os2.h>

PDRIVDATA    pDriverData;
PSZ          pszDriverName;
PSZ          pszDeviceName;
PSZ          pszPrinterName;
ULONG        lOptions;
ULONG        rc;             /* Return codes. */

rc = OS2_PM_DRV_DEVMODE(pDriverData, pszDriverName, pszDeviceName, pszPrinterName, lOptions);