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.

      ---

      [Back: OS2_PM_DRV_DEVMODE - Parameters]
      [Next: OS2_PM_DRV_DEVMODE - Topics]