Pen for OS/2 Device Driver Reference

By IBM

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Notices

OS/2 Developer Connection Device Driver Kit, Version 4 Edition (June 1996)

Copyright Notices

COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.

Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved."

(C) Copyright International Business Machines Corporation 1996. All rights reserved.
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Disclaimers

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products , except those expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594
U.S.A.

Trademarks

The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

IBM
OS/2
Presentation Manager 
Workplace Shell

About This Book

The Pen for OS/2 Device Driver Reference is a reference to be used with the IBM Developer Connection Device Driver Kit for OS/2. This book provides information on how to develop the device drivers that act as an interface between the Pen for OS/2 system extension and pen hardware products.

The examples in this book are written in assembly language to show detail. The definitions and data structures are given in C language for clarity.

Who Should Read This Book

This book is intended for professional programmers who are interested in developing pen device drivers on their hardware product with a Pen for OS/2 system extension. Prior experience developing device drivers would be helpful.

How This Book Is Organized

This book is organized as follows:

• Architecture contains a description of the pen device driver component structure, logical device types, and driver data.
• Initialization contains a description of device driver initialization and logical device registration.
• Operations contains a description of the operations that handle the processing of logical devices.
• Pen Device Objects contains a description of the new device objects created by Pen for OS/2, instance methods, and class methods.
• Installation Control Files contains a description of the pen device driver installation process.
• Programming Interface contains the format for programming interfaces, including request packet interface, generic IOCtl interface, and extended Pen for OS/2 interface.
• Pen for OS/2 Component of IBM Developer Connection Device Driver Kit for OS/2 contains a description of the sample code in the IBM Developer Connection Device Driver Kit for OS/2.
• Operational Considerations contains additional information pertaining to device driver development, including configuration limitations and video mode changes.

Related Publications

The following publications are available:

• Pen for OS/2 Developer's Toolkit: Getting Started, 71G2123
• Pen for OS/2 Programming Guide and Reference, 71G2124
• Pen for OS/2 User's Guide, 71G2122

What's New

The Pen for OS/2 Device Driver Reference has not been updated for this version of the DDK.

Assistance

Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS) known as the "DUDE". You are encouraged to use the DUDE to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.

To access the DUDE, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512-838-9493.

Additional assistance is available through the IBM Solution Developer Program. For membership information:

Internet: ibmsdp@vnet.ibm.com

US/Canada: 800-627-8363

International: 770-835-9902

International Fax: 770-835-9444

Ordering Information

For an illustration of OS/2 Technical Publications and other related product documents, see the figure labeled "OS/2 Technical Publications". The documents represented in this illustration are available only in English.

In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, this CD-ROM also includes the following DDK reference books in online format.

• The Physical Device Driver Reference
• The Storage Device Driver Reference
• The Input/Output Device Driver Reference
• The Pen for OS/2 Device Driver Reference
• The Virtual Device Driver Reference
• The Presentation Device Driver Reference
• The Display Device Driver Reference
• The Printer Device Driver Reference
• The Graphics Adapter Device Driver Reference
• The MMPM/2 Device Driver Reference (Multimedia)

To order the DDK call:

/----------------------------------------------------------------\
|U.S.A.:             |1-800-633-8266       |                     |
|--------------------+---------------------+---------------------|
|Canada:             |1-800-561-5293       |                     |
|--------------------+---------------------+---------------------|
|When calling from   |� English            |(+45) 48101500       |
|Europe, the Middle  |� French             |(+45) 48101200       |
|East, or Africa, the|� Italian            |(+45) 48101600       |
|number depends on   |� German             |(+45) 48101000       |
|the language you use|� Spanish            |(+45) 48101100       |
|to place the order: |� Dutch              |(+45) 48101400       |
|                    |� Danish             |(+45) 48101300       |
|                    |� Finish             |(+45) 48101650       |
|                    |� Swedish            |(+45) 48101150       |
|                    |� Norwegian          |(+45) 48101250       |
|                    |� FAX                |(+45) 48142207       |
|--------------------+---------------------+---------------------|
|When ordering from  |� Bolivia            |    02-35 1840       |
|Latin America or    |� Columbia           |   01-257-0111       |
|South America, the  |� Dominican Republic |      566-5161       |
|number depends on   |� El Salvador        |    02-98 5011       |
|the country from    |� Honduras           |       32-2319       |
|which you are       |� Paraguay           |   021-444 094       |
|calling:            |� Urugruay           |    02-923 617       |
|                    |� Chile              |   02-633-4400       |
|                    |� Costa Rica         |      223-6222       |
|                    |� Ecuador            |    02-56 5100       |
|                    |� Guatemala          |    02-31 5859       |
|                    |� Panama             |    02-639 977       |
|                    |� Peru               |   014-36 6345       |
|                    |� Venezuela          |   02-908-8901       |
|                    |� Argentina          |   01-313-0014       |
|--------------------+---------------------+---------------------|
|To order from Asia/ |� All except Japan   |(61) 2-354-7684      |
|Pacific:            |� Japan              |(81) 3-3495-2045(Fax)|
|                    |                     |Fax request to:      |
|                    |                     |DAP-J, IBM Japan     |
|--------------------+---------------------+---------------------|
|To order from SE    |(021) 800-6120(Voice)|                     |
|Brazil:             |(021) 800-6936(Fax)  |                     |
|--------------------+---------------------+---------------------|
|To order from       |� Mexico City        |627-2444             |
|Mexico:             |� Country            |91-800-00639         |
\----------------------------------------------------------------/

Architecture

The IBM OS/2 operating system is an advanced multitasking, single-user operating system for personal computers. The OS/2 operating system provides an application programming interface (API) that supports multitasking, multiple threads, dynamic linking, interprocess communication, a graphical user interface, and a graphics programming interface.

Pen for OS/2 is a series of software extensions to the OS/2 operating system and the Presentation Manager* (PM) graphical user interface that enable pen-based input and recognition. The Pen for OS/2 extensions support a variety of computers and peripherals designed for use with a pen as their primary input device.

Because many of the functions of an OS/2 physical device driver are related to system operations in addition to hardware operations, OS/2 services are available through the Device Helper (DevHlp) interface. Refer to the Physical Device Driver Reference for a complete description of OS/2 Device Helper services and responsibilities. The Pen for OS/2 system has extended the OS/2 device driver services providing Pen for OS/2 Device Driver Services unique to pen hardware devices. The Pen for OS/2 Device Driver Service internal structure provides the logical device types and device driver data. The following figure shows the major components of the pen device driver model and how they fit into the Pen for OS/2 design. The developer supplies the items shown in the boxes marked with ÛÛ.

                                     Pen Device-Driver-
    OS/2 Applications                Specific Applications
/----------------------\          /-------------------------\
|                      |          |        /--------------\ |
|     /--------------\ |--\    /--+--------|Device     ÛÛ | |
|     |           ÛÛ | |  |    |  |  |  /--|Objects       | |
| /--------------\   | |  |    |  |  |  |  \--------------/ |
| |           ÛÛ |   | |  |    |  |  |  |  /--------------\ |
| |              |---/ |  |    |  |  |--+--|CalibrationÛÛ | |
| |              |     |  |    |  |  |  |  |Program       | |
| \--------------/     |  |    |  |  |  |--|(Optional)    | |
|                      |  |    |  |  |  |  \--------------/ |
|                      |  |    |  |  |  |  /--------------\ |
|                      |  |    |  |  |--+--|Delayed-   ÛÛ | |
|                      |  |    |  |  |  |  |Initialization| |
|                      |  |    |  |  |  |  |Program       | |
|     /--------------\ |  |    |  |  |  |--|(Optional)    | |
|     |           ÛÛ | |  |    |  |  |  |  \--------------/ |
| /--------------\   | |  |    |  |  |  |  /--------------\ |
| |           ÛÛ |   | |  |    |  |  |--+--|Auxilliary ÛÛ | |
| |              |---/ |  |    |  |  |  |  |Program       | |
| |              |     |  |    |  |  |  |--|(Optional)    | |
| \--------------/     |  |    |  |  |  |  \--------------/ |
|                      |  |    |  |  |  |  /--------------\ |
|                      |  |    |  |  |  |  |Pen Device-   | |
|                      |  |    |  |  |  \--|Driver Tool   | |
|                      |  |for |  |  |     \--------------/ |
\----------------------/  |OS/2|  \--+----------------------/
  OS/2                    |API |     |
  /-----------------------+----+-----+--------------------\
  | /---------------------+----+--\  |                    |
  | | Pen for OS/2 /---------- -\|-  |                    |
  | |              |Pen for OS/2 ||                       |
  | |              |Device-Driver||  |Ioctl Interface     |
  | |              |Services     ||  |                    |
  | |              \-------------/|  |  /---------------\ |
  | \-----------------+-------+---/  |  |OS/2 Device-   | |
  |                  IDC    Services |  |Helper Services| |
  |               Interface  Calls   |  \-------�-------/ |
  \-------------------+-------+------+----------+---------/
                      |       |      |    Devhlp|Interface
/--------------------- ------- ------ ----------------------\
|                  Pen Device Driver                    ÛÛ  |
\--------------------------- -------------------------------/
                            |                             
                      Pen Hardware

To develop pen hardware support for the Pen for OS/2 system extension, you provide the following components:

• Pen device driver

The pen device driver is an OS/2 physical device driver that controls the pen hardware. It has access to all the OS/2 Device Helper services and must adhere to all the OS/2 device driver rules.

The pen device driver calls the Pen for OS/2 Device Driver Services to register Pen for OS/2 device-specific capabilities, deliver Pen for OS/2 events, and make queries. Pen for OS/2 Extended Interface provides a complete specification of this direct call interface.

The pen device driver must provide an IOCtl interface to the Pen for OS/2 system to control the pen device driver. Refer to the Control Program Programming Reference for more information on the Generic IOCtl Interface for applications (DosDevIOCtl) and to the OS/2 2.0 Physical Device Driver Reference for information on the existing IOCtl functions. Generic IOCtl Interface provides a complete specification of the IOCtl interface.

The pen device driver can provide private IOCtls to permit device-specific control operations that do not involve Pen for OS/2.

• Device objects

Pen for OS/2 device objects appear as icons in the Devices folder. Device objects provide a means of communication between a computer and another piece of equipment, such as a pen or display. The icons look like the pen hardware they represent. The device objects contain a Settings notebook with Pen for OS/2 variables and device-specific data. The Pen for OS/2 folder contains the Devices folder. These folders are added to the desktop when the Pen for OS/2 system is installed. Device Driver Data describes the types of device driver data. Pen Device Objects describes device objects in more detail.

• Optional calibration program

You can provide a calibration program. The calibration program, provided with the Pen for OS/2 Developer's Toolkit, can be invoked from a device object which can communicate with the pen device driver through IOCtls.

• Optional initialization program

You can provide an initialization program to communicate with the pen device driver during OS/2 system initialization, which is described in the section titled Initialization.

• Optional auxiliary programs

You can add other OS/2 application programs, device drivers, and subsystems to enhance or control the operation of the pen device driver beyond the scope specified in the Pen for OS/2 system. For example, you can subclass the basic video system to provide enhanced display support.

Logical Device Types

The following figure illustrates the relationship between a pen device driver and Pen for OS/2 logical devices.

PENDD.SYS
 /----------------------------------------------------------\
 |                                                          |
 |   Device Driver Header                                   |
 |   /--------\                                             |
 |   |        |                                             |
 |   | PENDD$ |                                             |
 |   |        |                                             |
 |   \--------/                                             |
 | /--------------------------------------\                 |
 | |Device MY_HARDWARE, Device Type DRIVER|                 |
 | |    /-------------------------------------\             |
 | \----|Device LCD Device Type DISPLAY       |             |
 |      |    /------------------------------------\         |
 |      \----|Device BEZEL, Device Type BUTTON    |         |
 |           |    /-----------------------------------\     |
 |           \----|Device FINGER, Device Type LOCATOR |     |
 |                |    /----------------------------------\ |
 |                \----|Device PEN, Device Type LOCATOR   | |
 |                     |                                  | |
 |                     \----------------------------------/ |
 |                                                          |
 \----------------------------------------------------------/

The load module contains the physical device driver. PENDD.SYS is the load module for the sample device driver provided in the Toolkit. The OS/2 operating system recognizes the driver name defined in the device driver header and treats it and its collection of Pen for OS/2 logical devices as one OS/2 character device driver. The driver name in the device driver header must be a unique eight-character name to enable multiple drivers to coexist on a single system. (PENDD$ is the device driver name used for the sample device driver provided in the Toolkit.) Select a name that uniquely identifies your hardware.

The Pen for OS/2 system and Pen for OS/2 Device Driver Services support the following logical device types:

• Locator

Locator devices supply a stream of locator position points and emulated mouse button events. The Pen for OS/2 system has extended the standard OS/2 mouse locator point stream to include:

• Z-axis information
• Sequence number
• High-resolution device time stamp
• State of all physical buttons
• Optional locator data (angle theta, angle phi)
• Optional OEM data area

There are three types of locator devices:

• Pen

Pen devices supply high-resolution position points at a high sample rate. Pens can have buttons and can report orientation data. Pens usually report proximity in terms of height. Ink should flow directly from the tip of the pen.

• Touch

Touch devices provide lower resolution and a lower sample rate. A touch device, such as a finger, does not have buttons. Selection ability of a touch device improves by offsetting the OS/2 pointer from the actual hardware coordinate of contact. Touch devices usually do not report proximity but can report pressure.

• Other

Pen for OS/2 provides an other type for locators that have some or none of the characteristics of the previous types; for example, a relative reporting track ball or a joy stick with a trigger button does not have the characteristics of a pen or touch device.

Locator Device Processing describes locator devices in further detail.

• Button

The button device manages all barrel buttons and bezel buttons. Barrel buttons are found on the side of a pen device. Bezel buttons (or nonbarrel buttons) are built into the case of a pen-based computer or peripheral. A device object assigns actions to buttons. The state of all buttons managed by the driver is reported on all locator event streams.

Button devices can change the way emulated mouse button events are reported . For example, activating a barrel button on a pen can cause the default button 1 down to be reported as button 2 down instead.

Button devices also can produce events independently from the locator position point stream. For example, activating a bezel button can immediately cause the OS/2 Window List to become active. Button Device Processing describes button devices in further detail.

• Display

The display device manages the backlight on a liquid crystal display (LCD). The display device automatically turns off the backlight after the system has not been used for a default time period of 20 minutes. The display device turns the backlight back on when the user accesses the system. Display Device Processing describes display devices in further detail.

The common capabilities packet contains the driver name and logical device name for the logical devices in the pen device driver. See Common Capabilities Packet. Logical device names for the locator, button, and display need not be unique across the system. The names PEN, FINGER, BEZEL, BARREL, MONO, and COLOR are suggested. The logical device name for the driver logical device should identify your hardware device as uniquely as possible. See Configuration Limitations for a complete configuration description.

Each logical device in the driver is assigned a unit number. A unit number is used to select a logical device within the driver and is unique only within the scope of the driver. The logical devices are numbered sequentially starting at 0. Your optional application programs and the test program use unit numbers with the IOCtl interface to select a particular device for an operation. Unit 0 is the device type "DRIVER" that defines the characteristics of the entire driver.

Query Unit Capabilities of unit 0 returns the total number of logical devices in the driver, including itself. Query Unit Capabilities can be used to query each unit's capabilities data to retrieve its device type and description.

Each device also has a device ID. A device ID is an ID number assigned to a logical device by the the Pen for OS/2 Device Driver Services. A device ID is unique across the entire system. Pen for OS/2 uses the device ID to distinguish devices uniquely in the system.

Pen for OS/2 provides API functions to query the device configuration so that an application will not need to use the IOCtl interface.

Device Driver Data

A pen device driver can have data values hard coded when the driver is compiled and linked. Pen for OS/2, or application programs you supply, can generate and store data values that cannot be hard coded and that override the hard-coded values. The pen device driver obtains these values through the IOCtl interface. The pen device driver can also obtain these values directly during initialization using ring 3 OS/2 API functions.

The following figure shows the types of data defined by the Pen for OS/2 system extension.

  /--------------\ /-----------\ /------------------------\
  |Delayed       | |           | |                        |
  |Initialization| |Pen Device | |Pen for OS/2            |
  |Program       | |Driver Tool| |                        |
  | /----------\ | |/---------\| |/--------\ /----------\ |
  | | Device   | | ||Device   || ||Device  | |Pen for   | |
  | | Private  | | ||Private  || ||Specific| |OS/2      | |
  | | Data     | | ||Variables|| ||Data    | |Variables | |
  | \----------/ | |\---------/| |\--------/ \----------/ |
  \------+-------/ \----+------/ \-----+-----------+------/
         |              |              |           |
      Private        Set Unit       Set Unit   Device Type
      IOCtls         Variable       Specific    Specific
         |            IOCtl        Data IOCtl    IOCtls
         |              |              |           |
/--------+--------------+--------------+-----------+--------\
| /------+--------------+----\ /-------+-----------+------\ |
| | /----�----\ /-------�--\ | | /-----�---\ /-----�----\ | |
| | | Device  | |Device    | | | |Device   | |Pen for   | | |
| | | Private | |Private   | | | |Specific | |OS/2      | | |
| | | Data    | |Variables | | | |Data     | |Variables | | |
| | \---------/ \----------/ | | \---------/ \----------/ | |
| | Private Data             | |Pen for OS/2              | |
| |                          | |Managed Data              | |
| \--------------------------/ \--------------------------/ |
|  PEN DEVICE DRIVER                                        |
\-----------------------------------------------------------/

The Pen for OS/2 system defines the following types of data, accessible using IOCtls:

• Private data

The Pen for OS/2 system does not maintain persistent values for this data across system restarts and does not provide Pen for OS/2 API access to this data. There are two types of private data:

• Device-private data

You manage device-private data by storing the data and communicating it to the pen device driver through private IOCtls. There can be any number of private data blocks of any size. An example of device-private data is a microcode load for a pen hardware product.

A delayed initialization program or an auxiliary program can save the data between restarts and pass device-private data to the driver.

• Device-private variables

Device-private variables can be viewed as an array of ULONGs accessed by an index. The pen device driver defines the number of variables available per logical device. They are provided as a convenience and are intended for temporary use, such as debugging; they are not required to be set for the driver to operate. Set Unit Variable and Query Unit Variable IOCtls communicate private variables to and from the pen device driver. The pen device driver tool, described in Pen Device Driver Tool, can set and query device-private variables.

• Pen for OS/2 managed data

The Pen for OS/2 system maintains persistent values for this data and provides API functions to access the following two types of data:

• Device-specific data

Pen for OS/2 will manage up to 512 bytes per pen logical device. You set up this data in a single block through the Pen for OS/2 API, WrtSetInputDeviceVariable. The Pen for OS/2 system will pass the data to the pen device driver with the Set Unit Specific Data IOCtl. Pen for OS/2 saves device-specific data across system restarts and passes the data to the pen device driver when Pen for OS/2 starts up. Pen for OS/2 does not examine the contents of the data.

• Pen for OS/2 variables

The Pen for OS/2 system extension provides API functions to individually manage each Pen for OS/2 variable, and there is an IOCtl to pass the value of the variable to the pen device driver. The Pen for OS/2 system maintains the values of these variables across system restarts and initializes the pen device driver with these values through the IOCtl interface during Pen for OS/2 startup.

The following list contains the Pen for OS/2 variables related to the pen device driver: --Locator Offset
--Locator Pass Rate
--Locator Sample Rate
--Button Assignments
--Backlight Inactivity Period

The IOCtl method used to control data designates the data types. The designation is independent from the way the pen device driver chooses to organize and store the data within the driver.

For example, calibration data can be managed as Pen for OS/2 device- specific data. Pen for OS/2 maintains the device-specific data block across system restarts and passes the data during Pen for OS/2 initialization. If the calibration data is large, it can be managed as private data and communicated to the pen device driver with private IOCtls from a delayed initialization or auxiliary program you supply.

As a second example, a device-specific variable could be used during development to dynamically set a tuning value that later will be fixed as a hard-coded constant. A device-specific variable could also be used to collect error or diagnostic data for service support.

Initialization

For optimum performance, set the device driver to perform all the initialization required for the device driver to be operational. This has the following advantages:

• It is not necessary to invoke an initialization program from CONFIG.SYS as a RUN= statement or a program reference in the Startup folder. This simplifies the installation process.
• The device driver is fully operational with default settings before the startup of the Pen for OS/2 system extension.
• The device driver is more independent to ensure that mouse emulation always works despite error conditions that prevent other areas of the system from working.

Device driver initialization can be performed in one of two ways:

• Initialization at startup
• Delayed initialization

Delayed initialization is designed by the developer depending on the hardware supported. For more information, see Delayed Initialization.

The following figure illustrates the initialization process.

                   /----------------\
INIT Command       | Initialization |
    |    /- - - - -| Request Packet |- - - - CONFIG.SYS
    |    |         \----------------/
/---�----�---\                            /---------------\
|            |                            |               |
| Pen Device |                            | Pen for OS/2  |
| Driver     |                            | Device Driver |
|            |                            | Services      |
|            |                            |               |
\------------/                            \-------�-------/
   |                                              |
   |                            /-------------\   |
   | DevHlp_RegisterDeviceClass | OS/2 Device |   |
   \----------------------------� Helper      |---/
                                | Services    |
                                \-------------/

The initialization request packet has a pointer to a string containing the pen device driver's CONFIG.SYS statement, for example:

device=c:\penpm\pendd.sys load=c:\penpm\pendd.dat type=3

This string includes any optional device-specific parameters. These device -specific parameters can be used to identify data files containing the information needed during initialization and static parameters required for the operation of the device. For example, type=3 can inform the device driver of a device characteristic the device driver cannot determine.

The Pen for OS/2 system will pass device-specific data to the driver when the system starts up. This data can be used to override default values, such as locator coordinate adjustments. Therefore, do not place variables updated by a device object in the DEVICE= statement. Optimum results will be achieved if the driver can function without device-specific data. See Delayed Initialization if additional initialization is required.

If for some reason, the device driver can not take device-specific data from the Pen for OS/2 system, then the common capabilites packet flag entry must be set to CCAP_DEFAULTDATA for each device ( locator, button, display, and so forth) that cannot be customized. A default entry of CCAP_OS2INI must be made to ensure the flag is initialized.

If the sample rate for the locator can not be changed, set the locator-specific capabilities packet entry max_sample_rate to 0, and set the sample_rate entry to the fixed sample rate. For example, if sample_rate is 100, and max_sample_rate is 0, then the sample_rate will be fixed at 100 points per second.

DevHlp_RegisterDeviceClass

A pen device driver is required to identify that it has Pen for OS/2 logical devices during initialization using DevHlp_RegisterDeviceClass. RegisterDeviceClass eliminates the need to modify the CONFIG.SYS statement for other device drivers, such as MOUSE.SYS with TYPE= statements to establish bindings.

The pen device driver registers as DevClass=DEVCLASS_INPUT with DCFlags declaring that extended information will be generated (allowing for the possibility of future uses of DEVCLASS_INPUT) and identifying the method of attaching the pen hardware product. MOUSE.SYS uses the latter to avoid loading built-in mouse support for devices supported by the pen device driver. The OS/2 mouse driver loads mouse support based on a query of likely mouse hardware connected. This support is called built-in mouse support.

ddname db 'PENDD$',0
        .
        .
        .
  mov  cx, DEVCLASS_INPUT            ; Device class
  mov  di, REG_EXT_IF                ; Device class flags
  lea  si, ddname                    ; Device driver name (ASCIIZ)
  mov  ax, cs                        ; Ax:bx ->driver entry point
  lea  bx, Idc_DriverEntryPoint
  mov  dl, DevHlp_RegisterDeviceClass
  call DeviceHelp                    ; Register my driver with Pen for OS/2

The Pen for OS/2 Device Driver Services use the device driver name to perform a DevHlp_AttachDD. The pen device driver's device header must enable AttachDD and declare an AttachDD entry point. Logical Device Registration describes the use of the driver entry point. The Pen for OS/2 Device Driver Services do not use the AttachDD entry point and it is available for other private uses. See Pen for OS/2 Extended Interface for complete details of the DevHlp_RegisterDeviceClass interface.

Logical Device Registration

  /---------------\                      /---------------\
  |               | QUERY_CAPABILITIES   |               |
  | Pen Device    �----------------------| Pen for OS/2  |
  | Driver        |                      | Device Driver |
  |               | START_LOGICAL_DEVICE | Services      |
  |               �----------------------|               |
  |               |                      |               |
  |               | REGISTER_DEVICE      |               |
  |               |----------------------�               |
  |               |                      |               |
  |               | READ_ENABLE          |               |
  |               �----------------------|               |
  |               |                      |               |
  \---------------/                      \---------------/

After the initialization command has completed, the Pen for OS/2 Device Driver Services, using the driver entry point declared with DevHlp_ egisterDeviceClass, will contact the pen device driver in ring 0 kernel mode. The Pen for OS/2 Device Driver Services will query the driver for the number of defined logical devices (see Logical Device Types). A driver with one logical device would return 2; 1 for unit 0, and 1 for the logical device at unit 1.

Then, Pen for OS/2 Device Driver Services will request the level of the driver's interface (see Support Level Control), along with the rest of the capabilities information for each logical device. The capabilities information can be requested more than once.

Next, each Pen for OS/2 Device Driver Service identifies itself by passing its direct call service entry point to the driver with a START_LOGICAL_DEVICE IDC request for each logical device supported by the Pen for OS/2 system. The service entry point is passed in the SINFO data structure as shown in the following figure. Before returning from START_LOGICAL_DEVICE, the logical device registers with the Pen for OS/2 Device Driver Services with a REGISTER_DEVICE call to the service entry point of the Pen for OS/2 Device Driver Services.

Idc_StartDevice Proc                            ; Start logical device
    .
    .
    .
  mov  ax, es:[di].sinfo_service_ds              ; The architecture allows for
  mov  [bx].dcb_service_ds, ax                   ; more than one service entry
  mov  ax, word ptr es:[di].sinfo_service_rtn    ; point.  Currently, there is
  mov  word ptr [bx].dcb_service_rtn, ax         ; only one defined.
  mov  ax, word ptr es:[di].sinfo_service_rtn+2
  mov  word ptr [bx.].dcb_service_rtn+2, ax
    .
    .
    .
  mov  ax, REGISTER_DEVICE
  mov  di, [bx].dcb_@RegCaps
  push ds
  push bx                                        ; bx = device control block
  push ds
  pop  es
  mov  ds,[bx].dcb_service_ds
  call es:[bx].dcb_service_rtn               ; es:di = device capabilities packet
  pop  bx
  pop  ds

Unlike the standard MOUSE.SYS protocol, there is no interrupt packet address to remember and an AttachDD to MOUSE.SYS is not needed to pass the event data. See Pen for OS/2 Extended Interface for complete details.

Calling READ_ENABLE is the final step and is issued once by the Pen for OS/2 Device Driver Services to enable event reporting and capability updates for all successfully registered logical devices. Special capabilities and operation styles are identified by the Pen for OS/2 Device Driver Services. You can change the defaults by resetting the bits and returning the value to Pen for OS/2 Device Driver Services.

Delayed Initialization

/----------------\                 /---------------\
| Initialization |                 | Pen for OS/2  |
| Program        |                 |               |
\----------------/                 \-------�-------/
    |        | Access to                   |
    |        | Device-Specific             |
    |        | Data /---------------\      |
    |        |      | Configuration |      | Updated
    |        \------� Data          |      | Capabilities
    |               |               |      |
    | IOCtl         \---------------/      |
    | Interface                            |
/---�------------\                 /---------------\
| Initialization |   UPDATE_CAPS   | Pen for OS/2  |
| Program        |-----------------� Device Driver |
|                |                 | Services      |
\----------------/                 \---------------/

Setting the driver to perform all its required initialization during device driver initialization results in optimum performance; but if necessary, you can use a program that completes driver initialization depending on your hardware.

One possible purpose for a developer to write a delayed initialization program is to set Pen for OS/2 device variables not exposed on device objects. These variables are:

• PPMID_STABILITY
• PPMID_DIVIDE_RATE

A pen device driver can have a delayed initialization program invoked either as a RUN= statement in CONFIG.SYS or from a program reference in the OS/2 Startup folder. You can pass device-private data to the pen device driver with private IOCtls and do whatever is necessary to initialize the device.

If the registered capabilities are changed, the pen device driver must update the capabilities with the appropriate device-type service.

It is not necessary to pass device-specific data or Pen for OS/2 variables during initialization. As described in Device Driver Data, the Pen for OS/2 system will pass this data when it starts up.

Operations

Pen for OS/2 system extension provides the pen device driver with operations including the processing of locator, button, and display devices. The flow of events is controlled and the device driver configuration can be updated at any time.

Locator Device Processing

/----------------\                    /-----------------\
| Pen Device     |                    | Pen for OS/2    |
| Driver         |                    | Device-Driver   |
|                |  QUERY_DEV_CONFIG  | Services        |
|                �--------------------|                 |
|                |                    | Locator Service |
|                |                    |                 |
|                |                    |                 |
\----------------/                    \-----------------/

In addition to device registration, each locator device receives a call from the QUERY_DEV_CONFIG IDC request. The driver responds by copying its device data back to the Pen for OS/2 Device Driver Services. Unlike the standard MOUSE.SYS protocol, there is no interrupt packet address to remember and an AttachDD to MOUSE.SYS is not needed.

The QUERY_DEV_CONFIG request is defined for all device types, but only the locator device has a data packet defined for return to the Pen for OS/2 Device Driver Services. The other device types do not copy data back to the Pen for OS/2 Device Driver Services.

This process repeats for all registered locator devices.

Interrupt Packet IDC Interface

/----------------\                    /-----------------\
| Pen Device     |                    | Pen for OS/2    |
| Driver         |                    | Device Driver   |
|                |    REPORT_EVENT    | Services        |
| Locator Device |--------------------�                 |
|                |                    |                 |
|                |                    |                 |
|                |                    |                 |
\----------------/                    \-----------------/

The inter-device driver communication (IDC) interface for the locator Pen for OS/2 Device Driver Services is similar to the standard OS/2 mouse device-dependent design. The pen device driver calls the Pen for OS/2 Device Driver Services at the service entry point address passed during service identification instead of the MOUSE.SYS IDC entry point. Locator devices pass an address to an extended information packet instead of filling in the MOUSE.SYS interrupt packet. The REPORT_EVENT service call supports both absolute and relative locator streams.

Along with the locator position, locator devices identify three types of events in the extended information packet: (1) standard mouse button events of button 1, 2, and 3 with and without movement; (2) changes in mouse button position; and (3) devices that support proximity report an event when the proximity zoneis entered and when the proximity zone is exited. The proximity zone is an area where locator action is sensed by a touch-sensitive device without the locator device contacting the touch- sensitive surface.

Event Rate Controls

[Artwork not shown]

The Pen for OS/2 system extension controls the rate of events with IOCtls in two ways. First, the sample rate IOCtl requests that the driver control the total number of sample events. Most pen hardware products support this , but if your hardware product does not, the pen device driver would discard locator events to reduce the sample rate as seen by the Pen for OS/ 2 system. The sample rate is set with the category 91 Set Locator Sample Rate IOCtl.

Second, a pass rate filter is used to control the rate of OS/2 events. Every locator event is passed to the Pen for OS/2 system, but only some of those are passed to the OS/2 operating system as standard mouse events. The pass rate is set with the category 91 Set Locator Pass Rate IOCtl.

The Pen for OS/2 Device Driver Services attempt to set the pass rate automatically based on the device's sample rate as reported during registration. Automatic pass rate is requested by setting the pass rate to 0 in the locator capabilities packet. The pen device driver's pass rate variable is set with the category 91 Set Locator Pass Rate IOCtl.

The automatic pass rate can be overridden by setting the pass rate field in the capabilities packet to a positive value. This value determines how many locator events are passed to the Pen for OS/2 system for every one mouse event passed to the OS/2 operating system. For example, if the pass rate is set to 2, then for every 2 locator events only one is passed as a standard OS/2 mouse event.

Events which contain changes in button events will not be discarded.

Coordinate Adjustments

[Artwork not shown]

This figure shows a typical digitizer system. The inner rectangle represents the liquid crystal display (LCD) surrounded by its display bezel. The digitizer extends beyond the LCD on all sides and is shown by the outer rectangle. The finger in the center of the screen and the dotted slide region are discussed in Finger Offset.

This model assumes that the LCD has fixed dimensions and that the digitizer has a fixed resolution that is constant and uniform. Therefore, the device extents can be calculated. For example, if an LCD dimension is 10 inches and the digitizer has a resolution of 100 units per inch, then the device extents are 1000. Points are reported with values ranging from 0 to 999. The device extents, as reported in locator capabilities, must not be updated from their initial values set during registration other than to adjust for video mode changes as discussed in Video Mode Changes.

The diagram shows the raw device coordinate system and the normalized device coordinate system. The raw device coordinate system can have its origin at any corner and report sample points relative to that point over the entire active region of the digitizer. Typically, the origin is at the upper-left corner. The normalized coordinate system must have its origin at the upper-left corner of the LCD and range from 0 to the reported extents less one.

The locator event packet reports the normalized coordinates to the Pen for OS/2 Device Driver Services. The Pen for OS/2 Device Driver Services convert the normalized coordinates to PM screen coordinates. PM screen coordinates for video graphics array (VGA) are 640 x 480 pixels. Pen-aware applications have access to the PM screen coordinates, the more granular normalized coordinates, and standard coordinates based on a standard digitizer resolution of 1000 points per inch.

The calibration process determines the location of the LCD relative to the digitizer by collecting the raw device coordinates of the LCD corners. In the sample calibration program provided in the Pen for OS/2 Developer's Toolkit, the measured extents are found by calculating the corners of the LCD, as shown by the large arrows in the previous figure. (See Calibration Program for a description of the sample calibration program provided in the Pen for OS/2 Developer's Toolkit.)

Raw device coordinates must be transformed to the normalized coordinate system. First, raw device points must be translated from the raw origin to the normalized origin by adding an origin adjustment offset. Next, the value must be scaled in case the measured extent, as determined by the calibration points, does not exactly match the expected fixed device extent. This is done by multiplying the value by the fixed extent, dividing by the measured extent, and rounding up. Round off this value to ensure that it does not exceed the fixed device extent less one. Finally, the value might need to be inverted if the origin of the raw device coordinates is at a corner other than the upper left.

Xnorm = (Xraw+Xxadj) (Xextent / Xmeasured)

Ynorm = (Yraw+Yyadj) (Yextent / Ymeasured)

Pen for OS/2 Device Driver Services normalize z-coordinates to range from 0 to -4KB (KB equals approximately 1000 bytes) for pressure and 0 to 4KB for height.

[Artwork not shown]

Digitizers located below the LCD exhibit parallax as illustrated in this figure. Parallax is a condition that occurs when a gap exists between the locator position and the displayed ink. When the pen is at position A, the locator position and displayed ink at AL match. When the locator is at position B, the ink appears at BL. A gap exists between the locator position and the ink. The ink would appear at position BL*.

The distance between the display surface and the LCD cell is often about 3. 0 millimeters. In this case, where the eye angle is at 45 degrees, the gap is 3.0 millimeters.

The parallax differs in both the horizontal and vertical views by how a user looks at the display. This makes software correction for parallax unreliable. Parallax can result in a difference between the expected device extents and the measured device extents.

Finger Offset

You can improve the finger selection ability by offsetting the OS/2 pointer so it remains visible and appears to be pointing at the tip of the finger, instead of underneath the finger.

The figure, "Digitizer Coordinate Systems", shows a finger with a y- coordinate offset. If the offset were just added to the locator position, there would be a region on the bottom of the screen that could not be selected. To compensate for this, a slide region is used for this part of the screen. Gradually removing the offset in this region makes the entire region selectable.

Offsets are set through a device object and managed through the Pen for OS/ 2 system extension. The category 91 Set Locator Offset IOCtl informs the pen device driver of the change when the variable changes through the Pen for OS/2 system.

High-Resolution Device Time Stamp

The pen device driver can supply a high-resolution, double word (DWORD) device time stamp. The resolution of the high-resolution timer is specified in the capabilities packet in microseconds. For example, if the timer resolution of a device is 256 microseconds, then dev_timestampRes in the locator capabilities packet would be set to 256 and the pen capabilities PENCAP_TIMESTAMP bit would be set.

If the pen hardware product does not supply a high-resolution timer, then the locator capabilities packet's dev_timestampRes field would be set to 0, and the locator event packet's dev_timestamp field would be set to 0.

The pen device driver need not fill in the event time stamp, cev_timestamp. The Pen for OS/2 Device Driver Services handle this operation.

Fake Points and Proximity Events

The pen device driver must set the LOC_FAKE bit in cntrl field of the locator event packet if the coordinates specified are not valid. The last valid coordinates must be used. The first part of a stroke would generate an enter proximity zone event by setting EV_ENTER_PROX in the devicebits field.

If the device supports proximity but the device does not generate an exit proximity zone event, the pen device driver must time out the stroke and generate an event with LOC_FAKE set using the last valid coordinates. Neither LOC_CONTACT nor LOC_PROX must be set in lev_cntrl, and EV_EXIT_PROX must be set in the cev_devicebits field.

Suppressed Duplicate Proximity Points

By default, the device driver ignores duplicate proximity points if the pen has been left on the surface of the display. The mouse is not frozen in place and automatic backlight timeout processing is possible.

Performance Considerations

The following list describes items that affect the performance of a Pen for OS/2 system extension.

• Locator device performance is critical to the Pen for OS/2 system. Code path lengths would be optimized due to the frequency of execution.
• Locator devices that can control their interrupt rate would attempt a default rate of about 100 samples per second. Too many interrupts overload the system and too few result in poor stroke processing.
• If possible, the locator device would self-detect exiting of the proximity zone. Relying on the locator engine to time out the stroke will delay stroke completion processing in the Pen for OS/2 system.

Button Device Processing

 
                                        | Events Reported
                                        | to Pen for OS/2
/----------------\                    /-----------------\
| Pen Device     |                    | Pen for OS/2    |
| Driver         |                    | Device Driver   |
|                |    REPORT_EVENT    | Services        |
| Button Device  |--------------------                  |
|                |                    |                 |
|                |                    |                 |
|                |                    |                 |
\- --------------/                    \-----------------/
  |
  | External Hardware Events

A device object assigns actions to the pen hardware product's buttons through the Pen for OS/2 system extension API and informs the pen device driver using the category 92 Set Button Assignment IOCtl. The Query Button Assignment IOCtl can query the current assignment. The number of buttons and a summary of their assignment is obtainable by reading the unit capabilities packet with the Query Unit Capabilities IOCtl.

The driver reports all button events to the Pen for OS/2 Device Driver Services. The Pen for OS/2 Device Driver Services filter some of these events and do not pass them to the Pen for OS/2 system. The pen device driver reports all activations and releases, regardless of the state of the other logical devices.

The following assignments are possible:

Null

Buttons assigned to null action generate no action on activation or release. The button states are reported by the locator point stream.

Mouse-emulation buttons

Mouse-emulation buttons modify the normal mouse-button event emulation. Instead of the mouse button 1 emulating the stroke, mouse button 1 can be emulated as mouse button 2, mouse button 3, or a combination of mouse button 1, mouse button 2, and mouse button 3. The modification occurs while holding down a button, or during the next stroke after activating and releasing a button. A second activation and release cancels the modification so that the next stroke is not a modified mouse event.

Note: Pressing pen buttons is not like pressing mouse buttons. Mouse buttons generate a mouse event when activated and released. Pen buttons change the emulated mouse stream during the pen stroke but do not generate locator events directly as a result of activation or release.

Gesture mode

A stroke in gesture mode will force gesture recognition, even though the stroke might be in a drawing mode.

Hot-key buttons

The Pen for OS/2 device driver reports hot-key buttons to the Pen for OS/2 Device Driver Services. The pen device driver takes no action. The Pen for OS/2 Device Driver Services conditionally generate an event to the OS/2 operating system, and then report the event to the Pen for OS/2 system. The Pen for OS/2 Device Driver Services might not generate the event if the system is currently locked up or if the display has been turned off. The pen device driver always reports all activations and releases.

Other

All other assignments result in the buttons being reported to the Pen for OS/2 system by the device driver. The device driver uses the REPORT_EVENT Pen for OS/2 Device Driver Service to report the buttons. Generic IOCtl Interface provides a complete list of these assignments.

The state of all buttons is reported on each locator event in the locator event stream.

Display Device Processing

  | Backlight Control                       Events Reported �
  | IOCtls                                  to Pen for OS/2 |
/-�-----------------\                    /------------------+--\
| Pen Device Driver |                    | Pen for OS/2     |  |
|                   |                    | Device Driver    |  |
|                   |  QUERY_ACTIVITY    | Services         |  |
| Poll for Activity |--------------------�                  |  |
|                   |                    |                  |  |
| Turn Off          |  REPORT_EVENT      |                  |  |
| Backlight +       |--------------------+------------------|  |
|                   |                    |                  |  |
|                   |  REQUEST_CALLBACK  |                  |  |
|                   |--------------------�                  |  |
|                   |                    | Activity Trigger |  |
| Turn On           |  Call Back         |                  |  |
| Backlight +       �--------------------|                  |  |
|                   |                    |                  |  |
|                   |  REPORT_EVENT      |                  |  |
|                   |--------------------+------------------/  |
|                   |                    |                     |
\-------------------/                    \---------------------/

The Pen for OS/2 system extension provides APIs to turn on the display's backlight, turn off the display's backlight, and enable automatic backlight control. The Pen for OS/2 system informs the pen device driver of these activities with the category 93 Set Display State and Set Display Inactivity Period IOCtls. Query Display State queries the state of the backlight.

If the pen device driver chooses to support the automatic inactivity period, a timer routine queries the system's input activity with the QUERY_ACTIVITY Pen for OS/2 Device Driver Service. This call returns a summary activity count from the OS/2 mouse devices, all pen device drivers, and the keyboard device. The pen device driver must turn off the display if the returned count has not changed during the assigned inactivity period. The REPORT_EVENT service call reports an event to the Pen for OS/2 system.

The pen device driver can request notification of input activity with the REQUEST_CALLBACK service call. The Pen for OS/2 Device Driver Services will call the device entry point the next time locator, button, mouse, or keyboard activity occurs. The pen device driver must turn the display back on and report the event with REPORT_EVENT.

By default, the Pen for OS/2 Device Driver Services ignore locator mouse-button emulation and button device hot-key generation while the backlight is off. Points are processed if requested through the Set Display Inactivity Period IOCtl by enabling OPAQUE support. See Function 51h.

QUERY_ACTIVITY and REQUEST_CALLBACK are available to all device types.

A pen device driver can choose to override mouse-button events for a short period of time with the SUPPRESS_STROKE service call and enabling suppress support through the Set Display Inactivity Period IOCtl. For example, the stroke causing an ACTIVITY_CALLBACK which in turn resulted in the display backlight turning on can report to the OS/2 operating system as mouse movement with no mouse-button events to avoid possible unwanted action. The stroke could have originated from any pen device driver. The Pen for OS/2 Device Driver Services control the length of the interval.

Event Flow Control

  /---------------\                      /---------------\
  |               |                      | Pen for OS/2  |
  | Pen Device    |    ENABLE_DEVICE     | Device Driver |
  | Driver        �----------------------| Services      |
  |               |                      |               |
  |               |    DISABLE_DEVICE    |               |
  |               �----------------------|               |
  \---------------/                      \---------------/

The Pen for OS/2 Device Driver Services control the flow of events from the pen device driver with ENABLE_DEVICE and DISABLE_DEVICE. There are brief periods of time, during session switching, for example, when the Pen for OS/2 Device Driver Services will not process events. To stop the flow of events, the Pen for OS/2 Device Driver Services make a call to the pen device driver with the DISABLE_DEVICE IDC request. The pen device driver must mask interrupts from its device when it receives the call from DISABLE_DEVICE to stop the flow of events to the Pen for OS/2 Device Driver Services.

The pen device driver would reenable interrupts, and then resume sending events when it receives the call from the ENABLE_DEVICE IDC request.

The device would start in a disabled state and wait for a call from ENABLE_ DEVICE before sending any events or capability updates. ENABLE_DEVICE and DISABLE_DEVICE are issued once globally to the pen device driver. The driver must enable and disable all logical devices.

Configuration Update

/----------------\                     /---------------\
| Workplace Shell|        APIs         | Pen for OS/2  |
| Configuration  |---------------------�               |
| Object         | Update Pen for OS/2 |               |
\----------------/    Variables and    \--------�------/
    |        |     Device-Specific Data   |  |  |
    |        |                            |  |  |
    |        |      /---------------\     |  |  |
    |        |      | Device-       |     |  |  |
    |        |      | Specific      |     |  |  |Updated
    |        \------� Configuration |     |  |  |Capabilities
    |               | Data          |     |  |  |
    |               \---------------/     |  |  |
    |               /---------------\     |  |  |
    |               | Pen for OS/2  |     |  |  |
    |               | Configuration �-----/  |  |
    | Private       | Data          |        |  |
    | IOCtls        \---------------/        |  |
    |           IOCtls                       |  |
    |        /-------------------------------/  |
    |        |                                  |
/---�--------�---\                     /---------------\
| Pen Device     |     UPDATE_CAPS     | Pen for OS/2  |
| Driver         |---------------------� Device Driver |
|                |                     | Services      |
\----------------/                     \---------------/

The device objects generate device-private data, device-specific data, and Pen for OS/2 system extension variables. The values of this data can be updated at any time.

The previous figure shows the actions taking place during an update. Pen for OS/2 variables change through Pen for OS/2 API functions that inform the pen device driver using the Generic IOCtl Interface.

The Pen for OS/2 system also manages a small amount of device-specific data. This data is changed through WrtSetInputDeviceVariable and the pen device driver is updated with the Set Unit Specific Data IOCtl.

Private IOCtls communicate changes in device-private data to the pen device driver and Pen for OS/2 is not involved. You can define private IOCtls as necessary and save the data as appropriate.

If any field in the registered capabilities changes, the pen device driver must update the capabilities with the appropriate device-type service.

Pen Device Objects

Pen for OS/2 system extension device objects are Workplace objects that provide a means of communication between a computer and another piece of equipment. The Locator object enables the configuration of barrel button settings and hardware that is of the absolute locator device type (LOCTYPE_PEN and LOCTYPE_FINGER). The Display object enables the configuration of LCD display devices and bezel buttons and provides a means for the user to set the timeout for the backlight.

If you supply hardware devices that will interface to the Pen for OS/2 system, you must create a similar object or subclass one of the objects included with Pen for OS/2.

Workplace Object Classes Hierarchy

The following shows the Pen object classes as they fit into the predefined Workplace object class hierarchy. Each branch in the tree represents an immediate descendant (subclass) of a Workplace object class.

     CLASS NAME                                   CLASS FILE NAME

     SOMObject                                      SOMOBJ.SC
        |
        \-WPObject (replaced by PenObject)          PENOBJ.SC
             |
             \-WPAbstract                           WPABS.SC
                  |
                  \-PenButtonDevice                 PENBTNDV.SC
                       |
                       |-PenDisplay                 WPDISPLY.SC
                       |
                       \-PenLocator                 WPLOCATR.SC
                            |
                            |-PenLocatorFinger      WPLOCFGR.SC
                            |
                            \-PenLocatorPen         WPLOCPEN.SC

Subclassing an object class creates a child class that modifies the behavior of the parent class based on the child's new methods, instance data, and overriding parent methods. An object class is subclassed by deriving the new child class from the parent class. The parent's methods can be altered or supplemented by the new class and new instance data can be added and manipulated by the new child class.

The predefined System Object Model (SOM) object class, SOMObject, is the root class for all SOM object classes, including all Workplace object classes. No external programming interfaces exist permitting another OS/2 process to invoke methods. However, some API functions exist, such as WinSetObjectData, enabling other processes limited communication with an object. The interface to the device objects is through Workplace published classes. Information on SOM and Workplace objects can be found in Workplace Shell Programming Reference and in Workplace Shell Programming Guide.

Invocation of the new device objects will work in a manner similar to the current Mouse object. You can alter the system parameters for these devices using the Settings notebook. While in the Settings notebook of a device object, you can set parameters used by a device driver and the Pen for OS/2 system. These parameters control the operational characteristics of a device. Parameters represent items such as tap rates, delay times, function switches, and the functions performed when device buttons are pressed.

Workplace Object Classes

The following sections describe the object classes listed below:

• PenButtonDevice
• PenDisplay
• PenLocator
• PenLocatorFinger
• PenLocatorPen

PenButtonDevice

Class definition file: penbtndv.idl

Class hierarchy:

   SOMObject
      WPObject 
         PenObject
            WPAbstract 
               PenButtonDevice

The following are the PenButtonDevice methods:

• penAddButtonMappingsPage
• penQueryButtonData
• penSetButtonData

The following is the class method for the PenButtonDevice class:

• penclsQueryButtonData

The following are the methods overridden by the PenButtonDevice class:

• wpAddSettingsPages
• wpInitData
• wpRestoreState
• wpSaveState
• wpSetup
• wpUnInitData

The following is the class method overridden by the PenButtonDevice class:

• wpclsInitData

When an instance of the PenButtonDevice object is created, it will parse the setup string and scan for two "keyword=value" combinations.

The following table shows the keyword-value pairs supported by the PenButtonDevice class.

/--------------------------------------------------------------\
|Keyword        |Example Value  |Description                   |
|---------------+---------------+------------------------------|
|PEN_DRIVER     |Your Device    |The device name of the logical|
|               |Name           |device that this instance is  |
|               |               |representing. This determines |
|               |               |which set of Pen for OS/2     |
|               |               |variables will be affected by |
|               |               |the controls in the notebook. |
|---------------+---------------+------------------------------|
|PEN_DEVICE     |Display        |The device name of the driver |
|               |               |logical device that this      |
|               |               |instance is representing. This|
|               |               |determines which set of Pen   |
|               |               |for OS/2 variables will be    |
|               |               |affected by the controls in   |
|               |               |the notebook.                 |
\--------------------------------------------------------------/

Note: PenButtonDevice determines if the instance has button capabilities and, if so, a Buttons page is inserted into the Settings notebook of the instance. Because PenDisplay and PenLocatorPen are subclasses of PenButtonDevice, any pen that has button capabilities will automatically have a Buttons page inserted into its Settings notebook when it is installed.

PenDisplay

Class definition file: wpdisply.idl

Class hierarchy:

   SOMObject
      WPObject 
         PenObject
            WPAbstract 
               PenButtonDevice
                  PenDisplay 

The following is the PenDisplay method:

• penAddDisplayBacklightPage

The following are the methods overridden by the PenDisplay class:

• wpAddObjectWindowPage
• wpAddSettingsPages
• wpFilterPopupMenu
• wpOpen

The following are the class methods overridden by the PenDisplay class:

• wpclsQueryDefaultHelp
• wpclsQueryDefaultView
• wpclsQueryIconData
• wpclsQueryStyle
• wpclsQueryTitle

Note: If you are developing a device driver for a liquid crystal display (LCD), you must either create an instance of this class in the Devices folder with the appropriate setup string or subclass this object class and add it to the Devices folder. Pages can be added and replaced to fully support the required interface to the device settings. For example, you might want to provide a Settings page that enables the user to adjust the gray scaling for a monochrome LCD.

PenLocator

Class definition file: wplocatr.idl

Class hierarchy:

   SOMObject
      WPObject 
         PenObject
            WPAbstract 
               PenButtonDevice
                  PenLocator 

The following is the PenLocator method:

• penAddLocatorTimingPage

The following is the PenLocator class method:

• penclsQueryDefaultPause
• penclsQueryPauseEnableDefault

The following are the methods overridden by the PenLocator class:

• wpAddSettingsPages
• wpAddObjectWindowPage
• wpFilterPopupMenu
• wpInitData
• wpMenuItemSelected
• wpMenuItemHelpSelected
• wpModifyPopupMenu
• wpRestoreState
• wpSaveState
• wpSetup
• wpUnInitData
• wpOpen

The following are the class methods overridden by the PenLocator class:

• wpclsQueryDefaultHelp
• wpclsQueryDefaultView
• wpclsQueryIconData
• wpclsQueryStyle
• wpclsQueryTitle

When an instance of the PenLocator class is created, it will parse the setup string and scan for two "keyword=value" combinations. The following table shows the keyword-value pairs supported by the PenLocator class.

/--------------------------------------------------------------\
|Keyword        |Example Value  |Description                   |
|---------------+---------------+------------------------------|
|CALPROG        |CALIB.EXE      |The executable file name of   |
|               |               |the OS/2 application program  |
|               |               |that will be started when     |
|               |               |Calibrate is selected from the|
|               |               |menu.                         |
|---------------+---------------+------------------------------|
|CALPARMS       |TRUE           |The presence of this keyword  |
|               |               |indicates that the Driver and |
|               |               |Device names are to be passed |
|               |               |to the Calibration program as |
|               |               |arguments. If the Calibration |
|               |               |program has no arguments, then|
|               |               |omit this keyword from the    |
|               |               |setup string.                 |
\--------------------------------------------------------------/

PenLocatorFinger

Class definition file: wplocfgr.idl

Class hierarchy:

   SOMObject
      WPObject 
         PenObject
            WPAbstract 
               PenButtonDevice
                  PenLocator 
                     PenLocatorFinger

The following is the PenLocatorFinger method:

�penAddFingerOffsetPage

The following are the methods overridden by the PenLocatorFinger class:

�wpInitData
�wpRestoreState
�wpSaveState
�wpAddSettingPages

The following are the class methods overridden by the PenLocatorFinger class:

�penclsQueryDefaultPause
�penclsQueryPauseEnableDefault
�wpclsQueryIconData
�wpclsQueryTitle
�wpclsQueryDefaultHelp

PenLocatorFinger is a subclass of the PenLocator class. This class adds an additional page, Offset, to the Settings notebook. The Offset page enables you to set finger offset to the screen pointer. This is accomplished through the penAddLocatorFingerOffsetPage method. If you are developing a device driver for a touch-sensitive display, you must either create an instance of this class in the Devices folder with the appropriate setup string, or subclass this class and add it to the Devices folder. Pages can be added and replaced to fully support the required interface to the device settings.

Note: The Offset page supports only display devices with the origin in the upper-left corner of the device.

PenLocatorPen

Class definition file: wplocpen.idl

Class hierarchy:

   SOMObject
      WPObject 
         PenObject
            WPAbstract 
               PenButtonDevice
                  PenLocator 
                     PenLocatorPen

The following are the class methods overridden by the PenLocatorPen class:

�penclsQueryDefaultPause
�penclsQueryPauseEnableDefault
�wpclsQueryIconData
�wpclsQueryTitle
�wpclsQueryDefaultHelp

Workplace Instance Methods

The following sections describe the Workplace instance methods listed below :

�penAddButtonsMappingsPage
�penQueryButtonData
�penSetButtonData
�penAddLocatorTimingPage
�penAddDisplayBacklightPage
�penAddFingerOffsetPage

penAddButtonsMappingsPage

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

This method enables the object to add the Buttons page to its Settings notebook.

PenButtonDevice     *self;
HWND                 hwndNotebook;
ULONG                rc;

rc = _penAddButtonsMappingsPage(self, hwndNotebook);

penAddButtonsMappingsPage -

This method enables the object to add the Buttons page to its Settings notebook.

PenButtonDevice     *self;
HWND                 hwndNotebook;
ULONG                rc;

rc = _penAddButtonsMappingsPage(self, hwndNotebook);

penAddButtonsMappingsPage Parameter - self

self(PenButtonDevice *) - input The pointer to this object.

penAddButtonsMappingsPage Parameter - hwndNotebook

hwndNotebook(HWND) - input The handle of the notebook in which to insert the page.

penAddButtonsMappingsPage Return Value - rc

rc(ULONG) - returns Page indentifier:

0 Error occurred.
PageId Identifier for the inserted page.

penAddButtonsMappingsPage - Parameters

self(PenButtonDevice *) - input The pointer to this object.

hwndNotebook(HWND) - input The handle of the notebook in which to insert the page.

rc(ULONG) - returns Page indentifier:

0 Error occurred.
PageId Identifier for the inserted page.

penAddButtonsMappingsPage - Usage

This method must be called from within an override of the wpAddSettingsPages method.

penAddButtonsMappingsPage - Override Methods

This method is overridden to replace or remove the Buttons page. To remove the page, return SETTINGS_PAGE_REMOVED without calling the parent.

penAddButtonsMappingsPage - Topics

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

penQueryButtonData

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Related Methods 
Glossary 

This method enables the object to query the button bit maps and names to be used for this object instance.

PenButtonDevice     *self;
PPENEVENTDATA        pPenEventData;
ULONG                ulBufSize;

ulBufSize = _penQueryButtonData(self, pPenEventData);

penQueryButtonData -

This method enables the object to query the button bit maps and names to be used for this object instance.

PenButtonDevice     *self;
PPENEVENTDATA        pPenEventData;
ULONG                ulBufSize;

ulBufSize = _penQueryButtonData(self, pPenEventData);

penQueryButtonData Parameter - self

self(PenButtonDevice *) - input The pointer to this object.

penQueryButtonData Parameter - pPenEventData

pPenEventData(PPENEVENTDATA) - in/out A pointer to a buffer that will receive an array of PENEVENTDATA structures. The structures contain the data to be used for the button list box in the Settings notebook of this object instance. The caller is responsible for ensuring that the buffer is large enough to receive the data. If this parameter is NULL, the size of the buffer needed to hold the data will be returned.

penQueryButtonData Return Value - ulBufSize

ulBufSize(ULONG) - returns The size of the buffer needed to accommodate the array of PENEVENTDATA structures that is returned by this object.

penQueryButtonData - Parameters

self(PenButtonDevice *) - input The pointer to this object.

pPenEventData(PPENEVENTDATA) - in/out A pointer to a buffer that will receive an array of PENEVENTDATA structures. The structures contain the data to be used for the button list box in the Settings notebook of this object instance. The caller is responsible for ensuring that the buffer is large enough to receive the data. If this parameter is NULL, the size of the buffer needed to hold the data will be returned.

ulBufSize(ULONG) - returns The size of the buffer needed to accommodate the array of PENEVENTDATA structures that is returned by this object.

penQueryButtonData - Usage

This method can be called at any time to query the current button bit map and name data for this object.

penQueryButtonData - Override Methods

This method is generally not overridden.

penQueryButtonData - Related Methods

�penclsQueryButtonData
�penSetButtonData

penQueryButtonData - Topics

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Related Methods 
Glossary 

penSetButtonData

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Related Methods 
Glossary 

This method enables the object to set the button bit maps and names to be used for this object instance.

PenButtonDevice     *self;
PPENEVENTDATA        pPenEventData;
BOOL                 rc;

rc = _penSetButtonData(self, pPenEventData);

penSetButtonData -

This method enables the object to set the button bit maps and names to be used for this object instance.

PenButtonDevice     *self;
PPENEVENTDATA        pPenEventData;
BOOL                 rc;

rc = _penSetButtonData(self, pPenEventData);

penSetButtonData Parameter - self

self(PenButtonDevice *) - input The pointer to this object.

penSetButtonData Parameter - pPenEventData

pPenEventData(PPENEVENTDATA) - input A pointer to an array of PENEVENTDATA structures. These structures contain data to be used for the button list box in the Settings notebook of this object instance.

The pPenEventDatabuffer must contain one PENEVENTDATA structure for each button that is registered by the device driver. Also, the order in which these structures are placed within the buffer must match the order in which the buttons are registered by the device driver with the Pen for OS/2 system.

penSetButtonData Return Value - rc

rc(BOOL) - returns Success indicator:

TRUE Successful completion.
FALSE Error occurred.

penSetButtonData - Parameters

self(PenButtonDevice *) - input The pointer to this object.

pPenEventData(PPENEVENTDATA) - input A pointer to an array of PENEVENTDATA structures. These structures contain data to be used for the button list box in the Settings notebook of this object instance.

The pPenEventDatabuffer must contain one PENEVENTDATA structure for each button that is registered by the device driver. Also, the order in which these structures are placed within the buffer must match the order in which the buttons are registered by the device driver with the Pen for OS/2 system.

rc(BOOL) - returns Success indicator:

TRUE Successful completion.
FALSE Error occurred.

penSetButtonData - Usage

This method can be called at any time to change the current button bit map and name data for this object.

penSetButtonData - Override Methods

This method is generally not overridden.

penSetButtonData - Related Methods

�penclsQueryButtonData
�penQueryButtonData

penSetButtonData - Topics

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Related Methods 
Glossary 

penAddLocatorTimingPage

---

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

---

This method enables the object to add the Timing page to its Settings notebook.

PenLocator     *self;
HWND            hwndNotebook;
ULONG           rc;

rc = _penAddLocatorTimingPage(self, hwndNotebook);

penAddLocatorTimingPage -

This method enables the object to add the Timing page to its Settings notebook.

PenLocator     *self;
HWND            hwndNotebook;
ULONG           rc;

rc = _penAddLocatorTimingPage(self, hwndNotebook);

penAddLocatorTimingPage Parameter - self

self(PenLocator *) - input The pointer to this object.

penAddLocatorTimingPage Parameter - hwndNotebook

hwndNotebook(HWND) - input The handle of the notebook in which to insert the page.

penAddLocatorTimingPage Return Value - rc

rc(ULONG) - returns Page identifier:

0 Error occurred.
PageId Identifier for the inserted page.

penAddLocatorTimingPage - Parameters

self(PenLocator *) - input The pointer to this object.

hwndNotebook(HWND) - input The handle of the notebook in which to insert the page.

rc(ULONG) - returns Page identifier:

0 Error occurred.
PageId Identifier for the inserted page.

penAddLocatorTimingPage - Usage

This method must be called from within an override of the wpAddSettingsPages method.

penAddLocatorTimingPage - Override Methods

This method is overridden in order to replace or remove the Timing page. To remove the page, return SETTINGS_PAGE_REMOVED without calling the parent .

penAddLocatorTimingPage - Topics

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

penAddDisplayBacklightPage

---

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

---

This method enables the object to add the Backlight page to its Settings notebook.

PenDisplay     *self;
HWND            hwndNotebook;
ULONG           ulPageId;

ulPageId = _penAddDisplayBacklightPage(self,
             hwndNotebook);

penAddDisplayBacklightPage -

This method enables the object to add the Backlight page to its Settings notebook.

PenDisplay     *self;
HWND            hwndNotebook;
ULONG           ulPageId;

ulPageId = _penAddDisplayBacklightPage(self,
             hwndNotebook);

penAddDisplayBacklightPage Parameter - self

self(PenDisplay *) - input The pointer to this object.

penAddDisplayBacklightPage Parameter - hwndNotebook

hwndNotebook(HWND) - input The handle of the notebook in which to insert the page.

penAddDisplayBacklightPage Return Value - ulPageId

ulPageId(ULONG) - returns Page identifier:

0 Error occurred.
PageId Identifier for the inserted page.

penAddDisplayBacklightPage - Parameters

self(PenDisplay *) - input The pointer to this object.

hwndNotebook(HWND) - input The handle of the notebook in which to insert the page.

ulPageId(ULONG) - returns Page identifier:

0 Error occurred.
PageId Identifier for the inserted page.

penAddDisplayBacklightPage - Usage

This method must be called from within an override of the wpAddSettingsPages method.

penAddDisplayBacklightPage - Override Methods

This method is overridden in order to replace or remove the Backlight page. To remove the page, return SETTINGS_PAGE_REMOVED without calling the parent .

penAddDisplayBacklightPage - Topics

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

penAddFingerOffsetPage

---

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

---

This method enables the object to add the Offset page to its Settings notebook.

PenLocatorFinger     *self;
HWND                  hwndNotebook;
ULONG                 rc;

rc = _penAddFingerOffsetPage(self, hwndNotebook);

penAddFingerOffsetPage -

This method enables the object to add the Offset page to its Settings notebook.

PenLocatorFinger     *self;
HWND                  hwndNotebook;
ULONG                 rc;

rc = _penAddFingerOffsetPage(self, hwndNotebook);

penAddFingerOffsetPage Parameter - self

self(PenLocatorFinger *) - input The pointer to this object.

penAddFingerOffsetPage Parameter - hwndNotebook

hwndNotebook(HWND) - input The handle of the notebook in which to insert the page.

penAddFingerOffsetPage Return Value - rc

rc(ULONG) - returns Page identifier:

0 Error occurred.
PageId Identifier for the inserted page.

penAddFingerOffsetPage - Parameters

self(PenLocatorFinger *) - input The pointer to this object.

hwndNotebook(HWND) - input The handle of the notebook in which to insert the page.

rc(ULONG) - returns Page identifier:

0 Error occurred.
PageId Identifier for the inserted page.

penAddFingerOffsetPage - Usage

This method must be called from within an override of the wpAddSettingsPages method.

penAddFingerOffsetPage - Override Methods

This method is overridden in order to replace or remove the Offset page. To remove the page, return SETTINGS_PAGE_REMOVED without calling the parent .

penAddFingerOffsetPage - Topics

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

Workplace Class Methods

The following sections describe the Workplace Class methods listed below:

�penclsQueryButtonData
�penclsQueryDefaultPause
�penclsQueryPauseEnableDefault

penclsQueryButtonData

---

Select an item:

Parameters
Returns 
Remarks 
Override Methods 
Usage 
Related Methods 
Glossary 

---

This method specifies the default button bit maps and names used by PenButtonDevice instances.

M_PenButtonDevice     *self;           /*  The pointer to the class object. */
PPENEVENTDATA          pPenEventData;
ULONG                  ulSize;

ulSize = _penclsQueryButtonData(self, pPenEventData);

penclsQueryButtonData -

This method specifies the default button bit maps and names used by PenButtonDevice instances.

M_PenButtonDevice     *self;           /*  The pointer to the class object. */
PPENEVENTDATA          pPenEventData;
ULONG                  ulSize;

ulSize = _penclsQueryButtonData(self, pPenEventData);

penclsQueryButtonData Parameter - self

self(M_PenButtonDevice *) - input The pointer to the class object.

penclsQueryButtonData Parameter - pPenEventData

pPenEventData(PPENEVENTDATA) - in/out A pointer to a buffer that will receive the array of PENEVENTDATA structures. These structures contain the data to be used for the button list box in the Settings notebooks of instances of this class. The caller is responsible for ensuring that the buffer is large enough to receive the data. If this parameter is NULL, the size of the buffer needed to hold the data will still be returned. This buffer must always contain one valid PENEVENTDATA structure for each button registered with the Writing subsystem by the device driver.

penclsQueryButtonData Return Value - ulSize

ulSize(ULONG) - returns The size of the buffer needed to accommodate the array of PENEVENTDATA structures that is returned by this particular class object.

penclsQueryButtonData - Parameters

self(M_PenButtonDevice *) - input The pointer to the class object.

pPenEventData(PPENEVENTDATA) - in/out A pointer to a buffer that will receive the array of PENEVENTDATA structures. These structures contain the data to be used for the button list box in the Settings notebooks of instances of this class. The caller is responsible for ensuring that the buffer is large enough to receive the data. If this parameter is NULL, the size of the buffer needed to hold the data will still be returned. This buffer must always contain one valid PENEVENTDATA structure for each button registered with the Writing subsystem by the device driver.

ulSize(ULONG) - returns The size of the buffer needed to accommodate the array of PENEVENTDATA structures that is returned by this particular class object.

penclsQueryButtonData - Remarks

If NULL is passed for the pPenEventDataparameter, the size of the PENEVENTDATA array buffer needed for this class will be returned. This can be used for memory allocation purposes. Otherwise, the pPenEventDataparameter will always be assumed to be large enough to accommodate the array of PENEVENTDATA structures for this class.

penclsQueryButtonData - Usage

This method can be called at any time. Typically, it would not be useful for another object class to call this method.

penclsQueryButtonData - Override Methods

Workplace classes that wish to have unique button bit maps and name text must override this method and fill out the appropriate fields within the array of PENEVENTDATA structures. In addition, the correct size of PENEVENTDATA structures must always be returned.

The pPenEventDatabuffer must contain one PENEVENTDATA structure for each button that is registered by the device driver. Also, the order in which these structures are placed in the buffer must match the order in which the buttons are registered by the device driver with the Pen for OS/2 system.

penclsQueryButtonData - Related Methods

�penQueryButtonData
�penSetButtonData

penclsQueryButtonData - Topics

Select an item:

Parameters
Returns 
Remarks 
Override Methods 
Usage 
Related Methods 
Glossary 

penclsQueryDefaultPause

---

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

---

This method enables the object to query the default pause setting for the Pen for OS/2 system.

M_PenLocator     *self;
ULONG             pause;  /*  The default system setting for pause in milliseconds. */

pause = _penclsQueryDefaultPause(self);

penclsQueryDefaultPause -

This method enables the object to query the default pause setting for the Pen for OS/2 system.

M_PenLocator     *self;
ULONG             pause;  /*  The default system setting for pause in milliseconds. */

pause = _penclsQueryDefaultPause(self);

penclsQueryDefaultPause Parameter - self

self(M_PenLocator *) - input The pointer to the PenLocator class object.

penclsQueryDefaultPause Return Value - pause

pause(ULONG) - returns The default system setting for pause in milliseconds.

penclsQueryDefaultPause - Parameters

self(M_PenLocator *) - input The pointer to the PenLocator class object.

pause(ULONG) - returns The default system setting for pause in milliseconds.

penclsQueryDefaultPause - Usage

This method can be called at any time.

penclsQueryDefaultPause - Override Methods

This method can be overridden to specify a different default pause value.

penclsQueryDefaultPause - Topics

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

penclsQueryPauseEnableDefault

---

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

---

This method enables the object to query the default pause-enable setting for the Pen for OS/2 system.

M_PenLocator     *self;
ULONG             rc;    /*  The default system setting for pause-enable is returned. */

rc = _penclsQueryPauseEnableDefault(self);

penclsQueryPauseEnableDefault -

This method enables the object to query the default pause-enable setting for the Pen for OS/2 system.

M_PenLocator     *self;
ULONG             rc;    /*  The default system setting for pause-enable is returned. */

rc = _penclsQueryPauseEnableDefault(self);

penclsQueryPauseEnableDefault Parameter - self

self(M_PenLocator *) - input The pointer to the class object.

penclsQueryPauseEnableDefault Return Value - rc

rc(ULONG) - returns The default system setting for pause-enable is returned.

Possible values are:

TRUE Pause is enabled.
FALSE Pause is not enabled.

penclsQueryPauseEnableDefault - Parameters

self(M_PenLocator *) - input The pointer to the class object.

rc(ULONG) - returns The default system setting for pause-enable is returned.

Possible values are:

TRUE Pause is enabled.
FALSE Pause is not enabled.

penclsQueryPauseEnableDefault - Usage

This method can be called at any time.

penclsQueryPauseEnableDefault - Override Methods

This method can be overridden to specify a different default pause enable value.

penclsQueryPauseEnableDefault - Topics

Select an item:

Parameters
Returns 
Override Methods 
Usage 
Glossary 

Modifying the Pen for OS/2 Device Objects

The Pen for OS/2 system extension device objects provide a generic set of functions for customizing device settings, such as, pen and finger pause rate, double-tap rate, button mappings, and backlight timeout. You can use the provided classes and create object instances of these classes in your install procedure, or you can modify the classes to further refine their behavior.

Subclassing is the process of modifying the behavior of an existing object class. This section provides information on how to subclass Pen for OS/2 device object classes to modify their behavior. For general information on SOM and Workplace Shell programming, refer to:

• Workplace Shell Programming Guide
• System Object Model Programming Guide
• Workplace Shell Programming Reference
• Pen for OS/2 Programming Guide and Reference

Creating Default Instances of Pen for OS/2 Object Classes

Creating default instances of the Pen for OS/2 object classes is done by setting up an XXXX.WPO file. See Installation Control Files, for a description of how the XXXX.WPO file is set up to create the default Pen for OS/2 device objects.

Slight Modification of a Pen for OS/2 Object Class

If the behavior of the Pen for OS/2 object class meets your requirements, with the exception of the icon and icon title, you can subclass, and with slight modification, customize the object to your liking.

For example, to subclass PenLocatorPen, you will need to create a class definition file (.CSC) to define your class. You also will need files WPLOCPEN.H and WPLOCPEN.IDL from the Pen for OS/2 Developer's Toolkit. In the .IDL file, you will need to define method overrides for the following methods:

�wpclsQueryTitle
�wpclsQueryIconData

An example .CSC file is detailed in the following figure.

--------------------------------------------------------------------------

   #ifndef mypen_idl
   #define mypen_idl

   #include "wplocpen.idl"
   #include.<somcls.idl>

   interface M_MyPenClass;

   interface MyPenClass : PenLocatorPen
   {

   #ifdef __SOMIDL__
     implementation {

      //# Class Modifiers
      local;
      major version  = 1;
      minor version  = 1;
      filestem       = mypen;
      functionprefix = mypenm_;
      metaclass      = M_MyPenClass;
      callstyle      = oidl;

     };
   #endif /* __SOMIDL__ */
   };

   interface M_MyPenClass;
   {

   #ifdef __SOMIDL__
     implementation {

      //# Class Modifiers
      local;
      functionprefix = mypenM_;
      major version  = 1;
      minor version  = 2;
      filestem       = mypen;
      callstyle      = oidl;

      //# Method Modifiers

      wpclsQueryTitle:  override;
      wpclsQueryIconData:  override;

    };
   #endif /* __SOMIDL__ */
   };

   # /* mypen_idl */


--------------------------------------------------------------------------

After creating the .C source file (and other SOM emitted files) by running the SOM compiler (the SOM compiler will create stubs for the methods in the .C source), modify the .C source as follows:

�wpclsQueryTitle would return a pointer to the name of the icon. Do not call the parent. An example follows:

--------------------------------------------------------------------------

 SOM_Scope PSZ   SOMLINK mypenM_wpclsQueryTitle(M_MyPenClass *somSelf)
 {
     return ((PSZ) "MyIconName");
 }


--------------------------------------------------------------------------

�wpclsQueryIconData would fill out the appropriate information in the ICONINFO structure and return the size of the structure. Do not call the parent. An example follows:

--------------------------------------------------------------------------

  SOM_Scope ULONG SOMLINK mypenM_wpclsQueryIconData(M_MyPenClassName *somSelf,
                                                    PICONINFO pIconInfo)
  {
     if (pIconInfo)
     {
        pIconInfo->fFormat = ICON_RESOURCE;
        pIconInfo->hmod    = MyModuleHandle;
        pIconInfo->resid   = ID_MYICON;
     }

     return (sizeof(ICONINFO));
  }


--------------------------------------------------------------------------

Finally, modify your installation procedure to register your new class and create an instance of your class. You will now have an object that has all the behavior of the Pen for OS/2 PenLocatorPen class, except the object will have the icon and title you specified through the method overrides above.

Increased Modification of a Pen for OS/2 Object Class

If your device requires additional settings, then you can accomplish this through subclassing and making more sizable modifications to the behavior. Or, if you do not want a Pen for OS/2 system extension page to be present in a Settings notebook, you might remove it through subclassing. For this example, the PenLocatorFinger class will be used. The Touch Offset Page will be removed from the Settings notebook of the Touch class.

To subclass PenLocatorFinger, you will need to create a class definition file (.IDL) to define your class. You also will need files WPLOCFGR.H and WPLOCFGR.IDL from the Pen for OS/2 Developer's Toolkit. In the .IDL file, you will need to define overrides for the method, penAddFingerOffsetPage.

An example .IDL file follows:

--------------------------------------------------------------------------

   #ifndef mytouch_idl
   #define mytouch_idl

   #include "wplocfgr.idl"
   #include <somcls.idl>

   interface MyTouchClassName : PenLocatorFinger
   {

   #ifdef __SOMIDL__
      implementation {

      //# Class Modifiers
         local;
         functionprefix = mytch_;
         majorversion   = 1;
         minorversion   = 1;
         filestem       = mytouch;
         callstyle      = oidl;

      //# Method Modifiers
      penAddFingerOffsetPage:  override;
    };
   #endif /* __SOMIDL__ */
   };

   # /* mytouch_idl */


--------------------------------------------------------------------------

After creating the .C source file (and other SOM emitted files) by running the SOM compiler, modify the .C source as shown in the following example.

Note:penAddFingerOffsetPage would return SETTINGS_PAGE_REMOVED. Do not call the parent.

--------------------------------------------------------------------------

   SOM_Scope ULONG   SOMLINK mytch_penAddFingerOffsetPage(MyTouchClassName *somSelf,
                                                          HWND hwndNotebook)
   {
      return (SETTINGS_PAGE_REMOVED);
   }

--------------------------------------------------------------------------

Finally, modify your installation procedure to register your new class and create an instance of your class. You will now have an object that has all the behavior of the Pen for OS/2 PenLocatorFinger class, except the object will not have the Touch Offset page in its Settings notebook, as you specified through the method override above.

To perform more advanced modifications of a Pen for OS/2 object class (for example, adding your own Settings page), refer to Workplace Shell Programming Guide, System Object Model Programming Guide, Workplace Shell Programming Reference, and Pen for OS/2 Programming Guide and Reference.

The class definition files PENBTNDV.IDL, WPDISPLY.IDL, WPLOCATR.IDL, WPLOCPEN.IDL, and WPLOCFGR.IDL are included in the Pen for OS/2 Developer's Toolkit.

Installation Control Files

There are four control files used by the device driver installation program . The files must be created and placed on a device driver installation diskette along with the pen device driver and any optional programs you choose to provide such as calibration programs, auxiliary programs, or other utilities. The files might be in their original format or may be compressed into bundles using the IBM PACK.EXE utility program. The device driver installation program is invoked during Pen for OS/2 system extension installation. The user receives the option to install a pen device driver and specify where the pen device driver files are located. The pen device driver, ring 3 support programs, and dynamic link libraries are installed using the Pen for OS/2 installation program.

A description of each of the control files follows.

xxxxx.MCF Control File

xxxxx.MCF is the initial control file processed by the Pen for OS/2 installation program. In the Pen for OS/2 Developer's Toolkit, this file is PENDD.MCF for installation of the device driver named PENDD. The installation program searches for this file in the directory defined in the source path. The installation terminates if the file is not found. The contents of this file are detailed in the following figure.

--------------------------------------------------------------------------

package="Your Device"
filelist="PENDD.LST"
groupcount=1
munitcount=1
medianame="Device Driver Installation Diskette"
sourcedir = "\\"                  = 0
sourcedir = "\\HDCONTRL\\"        = 1
sourcedir = "\\INSTALL\\MMLCKDIR" = 2 /* Location of the unpacked files */
destindir = "\\"                  = 0
destindir = "\\INSTALL\\"         = 1
destindir = "\\DLL\\"             = 2
destindir = "\\INSTALL\\MMLCKDIR" = 3 /* For unpacking files            */
ssgroup=0
sssize=3500
ssname="PENDD device drivers"
ssversion="0.00"
ssinich="PENDD.WPO"
ssconfigch="PENDD.CCH"
ssdll="PENDD.DLL"
ssdllentry="installentry"

--------------------------------------------------------------------------

The first five statements provide information about the installation process. The packagekeyword represents the name of the device driver installation package in the form of a quoted string. The string is displayed in the Specify the Pen device you want to installlist box on the Pen for OS/2 device-driver target installation screen.

The filelistkeyword is used during the installation process to identify the file that contains the list of files to be processed; for the Pen for OS/2 device driver named PENDD provided in the Pen for OS/2 Developer's Toolkit, the list is in PENDD.LST. The groupcountkeyword defines the number of groups that make up the pen device-driver installation. A groupis a collection of information that pertains to the installation of this device. In a Pen for OS/2 device driver installation, only one group is needed and groupcountmust be 1. The munitcountand medianamekeywords list the number of device-driver installation diskettes and the names of the diskettes.

The next seven statements define the source and target subdirectories used for the PENDD installation. The directories are defined by the entries numbered 0 and greater. Special mention must be made of the temporary subdirectory represented as both a source subdirectory, 2, and target subdirectory, 3. This is a temporary subdirectory that is used only at installation time. It is the destination for the unpacking of the compressed files. When the files are unpacked into this subdirectory, it becomes the source subdirectory because the files are moved from this temporary location to the permanent subdirectory. The IBM program, PACK.EXE , is the only supported compression program. The Pen for OS/2 device driver installation program uses UNPACK.EXE to decompress the packed files. PACK. EXE can be obtained from the Pen for OS/2 Developer's Toolkit.

The final eight statements define the installation group. The installation of PENDD utilizes only one group, named PENDD device drivers. If additional groups are added to the PENDD installation, they would require their own group definition statements. The sssizefield shows how much space is required to install this group; the value is displayed on the User Prompts screen under the heading "Code to Install". The target drive must have at least the required amount of space or an error can occur when the user attempts to install to this location. The ssinichand ssconfigchfields define the other control files to be used during Pen for OS/2 installation. The final two fields, ssdlland ssdllentry, identify a group-specific dynamic link library (DLL) to be loaded and run during installation which permits some type of specialized processing to occur that is not covered during general installation of PENDD. If you are subclassing the device objects, you must include a DLL with an entry point to register and create an object of your new class. These last two fields are optional.

In addition to what is displayed are seven other fields that are used only to set additional information that cannot be set from the device driver. The fields are:

drivername = "Digitizer Mod 1" (The name is device-driver specific.)
PPMID_MOTION_STOP = "Pen", 14
PPMID_MOTION_START = "Pen", 32
PPMID_MINGESTURELENGTH = "Pen", 78
PPMID_TAPLENGTH = "Pen", 37
PPMID_TOUCHOFFSET_X = "Finger", 100
PPMID_TOUCHOFFSET_Y = "Finger", 100

"Pen" is the locator device name. It can be "Locator" or whatever other locator device you have. This information also is in the device driver. The six PPMID_ fields are used to customize the way the Pen Input subsystem interprets information from the device driver. These fields are useful for small tablets such as the Wacom Artpad.

xxxxx.LST Control File

This file contains a listing of the files to be processed by the device driver installation software and the location of the files. The first entry in this file is a number identifying the number of files to process during the installation. Next is a listing of those files, as shown in the following figure.

--------------------------------------------------------------------------

 /* File count                                                        */
    10
 /* Disk    installation   target  source   file                 file */
 /* Number  group          subdirectories   name                 type */
    0       0              0       0       "PENDD.MCF"           2
    0       0              0       0       "PENDD.LST"           2
    0       0              1       0       "PENDD.CCH"           2
    0       0              1       0       "PENDD.WPO"           2
    0       0              0       0       "PENDD.SYS"           2
    0       0              3       0       "PENDD.LS@"           3
    0       0              2       2       "PROGR.EXE"           1
    0       0              2       0       "PENDD.DLL"           2
    0       0              0       0       "CAL.EXE"             2
    0       0              0       0       "HELLO.EXE"           4

--------------------------------------------------------------------------

The first nonblank, noncomment record is a file count of the files that follow. All other entries have six fields. The first field is Disk Number . Disk numbering begins at 0. The largest number in this field must be less than the munitcountfield in the xxxxx.MCF file.

The second field identifies the installation group that this file belongs to. PENDD contains only one installation group, so all entries will have 0 in this field. The third and fourth fields identify the target and source subdirectories to be used when processing this file. The fifth entry is the file name and the sixth entry is the file type. A description of the file types follows:

1 The file was compressed in a packed file.
2 The file is in original format.
3 A packed file.
4 The file is to be deleted.

From the preceding figure, the sixth, seventh, and tenth lines are as follows:

�PENDD.LS@ is an packed file residing in directory 0 (that is, the root directory) on the diskette. This packed file is unpacked into its component file(s) into target destination directory 3 (for example, INSTAL\ MMLCKDIR) on the target.

�PROGR.EXE is a file that was compressed into PENDD.LS@. This file is moved from source subdirectory 2 (for example, INSTAL\MMLCKDIR) into target destination subdirectory 2 (for example, \DLL).

�The file HELLO.EXE might exist from a previous installation of PENDD; it is no longer supported or needed and will be deleted at installation time if it still exists in the destination location.

xxxxx.WPO Control File

This control file defines the objects in the new Pen for OS/2 folder. The following figure is a sample entry used to create a Pen for OS/2 device object. The first entry in this file represents the number of WPObjectentries to follow. The second entry is used to show the percent completed on the Updating system filesprogress indicator. The percent complete value from this file plus the percent values from .WPO and .CCH must equal 100 percent.

--------------------------------------------------------------------------

1
80
WPObject =
(
 WPClassName   = "WPFolder"
 WPTitle       = "Devices"
 WPSetupString = "OBJECTID=<DEVICES_FOLDER>"
 WPLocation    = "<PPM_FOLDER>"
 WPFlags       = OL
)
WPObject =
(
 WPClassName   = "PenLocatorPen"
 WPTitle       = "Pen"
 WPSetupString = "OBJECTID=<PENDD_STYLUS>;CALPROG=$(DEST)CAL.EXE;
                  CALPARMS=TRUE;
                  PEN_DRIVER=Digitizer Mod 3;
                  PEN_DEVICE=Pen"
 WPLocation    = "<DEVICES_FOLDER>"
 WPFlags       = 1L
)

--------------------------------------------------------------------------

Where:

$(DEST) A macro that is replaced by the full path that was specified as the destination path during device driver installation.

Pen The sample entry identifies a new object as a device object titled "Pen ". It will be known by the OS/2 operating system as PENDD_STYLUS and reside in the Devices folder.

WPFLags Specifies an action on PENDD_STYLUS as follows:

0 Indicates the creation should fail if PENDD_STYLUS already exists.
1 Indicates the folder should replace PENDD_STYLUS if it already exists.
2 Specifies that this folder should update the PENDD_STYLUS if it already exists.

CALPROG Specifies the name of the calibration program. If your calibration program does not need the PEN_DRIVER and PEN_DEVICE parameters passed to it as input parameters, do not use this keyword. CALPARMS=TRUE is used to tell the object to pass the PEN_DRIVER and PEN_DEVICE names as input parameters when starting CAL.EXE. The sample program, CAL.EXE, needs these two parameters to be passed in when starting. For more information, see Calibration Program.

PEN_DRIVER Refers to the string specified by the device driver in the Common Capabilities Packet defined as ccap_device_name for logical device unit 0.

PEN_DEVICE Refers to the string specified by the device driver in the Common Capabilities Packet defined as ccap_device_name for logical device units other than zero.

xxxxx.CCH Control File

This control file defines the changes to be made to CONFIG.SYS as shown in the following figure.

20
MERGE "LIBPATH"    = 2
MERGE "SET PATH"   = 0
MERGE "SET DPATH"  = 0
DELETE "DEVICE=MOUSE.SYS"
REPLACE "SET PENDD" = 0
DEVICE = "$(DEST)PENDD.SYS TYPE=3"
DEVICE = "$(BOOT):\\OS2\\MOUSE.SYS"

Where:

20 The first entry in this file represents the percentage to paint the Updating system filesprogress indicator.

MERGE The MERGE statements add information to existing CONFIG.SYS statements. For example, the first statement adds an additional directory to the LIBPATH statement in CONFIG.SYS. The directory being added is represented by the number 2. This number corresponds with the destindir statement in the xxxxx.MCF control file described earlier. The PENDD.MCF file has the following statement:

--------------------------------------------------------------------------

destindir = "\\DLL\\"          = 2

--------------------------------------------------------------------------

If the user accepts the default PENDD directory name, the LIBPATH statement is changed to reflect the addition of the x:\PENDD\DDL subdirectory (where xis the drive letter specified by the user).

DELETE The DELETE statement is used to remark out lines in CONFIG.SYS. In the DELETE statement above, the DEVICE=MOUSE.SYS statement is remarked out.

REPLACE The REPLACE statement is used to change the value of a CONFIG.SYS environment setting. The directory being pointed to in the existing SET PENDD statement will be replaced by the base directory the user specifies in the target pathfield on the User Prompts screen.

DEVICE The DEVICE statement permits additional device drivers to be loaded by the CONFIG.SYS file. The DEVICE statement is written to CONFIG.SYS with the fully qualified file name.

$(DEST) A macro that is resolved to the fully qualified destination path to which the device is being installed.

$(BOOT) A macro that is replaced by the start drive letter of the operating system.

The installation script files also support two additional macros. A description of these macros follows:

$(DIR)# Where # is a number of the destination directory as stated in the file XXX.MCF. The full macro is replaced by the complete path of the destination directory.

$(DRIVE) This macro is replaced by the installation target drive letter. No colon is appended.

Programming Interface

The device-driver-socket programming interface of the pen device driver is made up of the following:

• Request packet interface
• Generic IOCtl interface
• Pen for OS/2 extended interface

The examples in this book are written in assembly language to show detail. The definitions and data structures in this chapter are given in C language for clarity. The following table shows C data types and the equivalent assembly language data lengths.

/-------------------------------------\
|C             |ASM                   |
|--------------+----------------------|
|LONG          |DD                    |
|--------------+----------------------|
|SHORT         |DW                    |
|--------------+----------------------|
|UCHAR         |DB                    |
|--------------+----------------------|
|ULONG         |DD                    |
|--------------+----------------------|
|USHORT        |DW                    |
\-------------------------------------/

Variables are usually referred to using the name that is used in the sample pen device driver. For example, pqusd.capabilitiesis referred to in Function 60h. This is the name of the variable used in the sample.

Request Packet Interface

The pen device driver is a character device driver and implements the following OS/2 device driver strategy commands:

/-------------------------------------\
|Code          |Command               |
|--------------+----------------------|
|0H            |INIT                  |
|--------------+----------------------|
|DH            |OPEN DEVICE           |
|--------------+----------------------|
|EH            |CLOSE DEVICE          |
|--------------+----------------------|
|10H           |GENERIC IOCtl         |
\-------------------------------------/

Note:BAD_COMMAND (8103H) is returned for all other commands that are not supported. DosDevIOCtl2 is not supported.

INIT is described in Initialization. There is minimal support for OPEN and CLOSE commands, only a count for the number of OPENs is maintained. Generic IOCtl processing by the device driver is described in Driver Subcomponents. Generic IOCtl Interfacedescribes the IOCtl functions the device driver must support.

Generic IOCtl Interface

The IOCtl functions provide a method for an application to send device- specific control commands to a pen device driver. These IOCtls are subfunctions that are issued through the DosDevIOCtl API function request. The following table lists the categories and functions for the generic IOCtl functions.

/--------------------------------------------------------------\
|Category       |Function       |Description                   |
|---------------+---------------+------------------------------|
|90h            |               |Driver                        |
|---------------+---------------+------------------------------|
|               |50h            |Set Unit Specific Data        |
|---------------+---------------+------------------------------|
|               |51h            |Set Unit Variable             |
|---------------+---------------+------------------------------|
|               |52h            |Reset Trace Table             |
|---------------+---------------+------------------------------|
|               |53h            |Set Trace Table Size          |
|---------------+---------------+------------------------------|
|               |60h            |Query Unit Specific Data      |
|---------------+---------------+------------------------------|
|               |61h            |Query Unit Variable           |
|---------------+---------------+------------------------------|
|               |62h            |Query Unit Capabilities       |
|---------------+---------------+------------------------------|
|               |63h            |Query Trace Table             |
|---------------+---------------+------------------------------|
|               |64h            |Query Trace Table Size        |
|---------------+---------------+------------------------------|
|91h            |               |Locator                       |
|---------------+---------------+------------------------------|
|               |50h            |Set Locator Offset            |
|---------------+---------------+------------------------------|
|               |51h            |Set Locator Pass Rate         |
|---------------+---------------+------------------------------|
|               |52h            |Set Locator Sample Rate       |
|---------------+---------------+------------------------------|
|               |60h            |Query Locator Variables       |
|---------------+---------------+------------------------------|
|               |61h            |Query Locator Raw Coordinates |
|---------------+---------------+------------------------------|
|               |62h            |Query Default Locator Extents |
|---------------+---------------+------------------------------|
|92h            |               |Button                        |
|---------------+---------------+------------------------------|
|               |50h            |Set Button Assignment         |
|---------------+---------------+------------------------------|
|               |60h            |Query Button Assignment       |
|---------------+---------------+------------------------------|
|93h            |               |Display                       |
|---------------+---------------+------------------------------|
|               |50h            |Set Display State             |
|---------------+---------------+------------------------------|
|               |51h            |Set Display Inactivity Period |
|---------------+---------------+------------------------------|
|               |60h            |Query Display State           |
\--------------------------------------------------------------/

ERROR_INVALID_PARAMETER (8113H) is returned for invalid unit or for parameters out of the specified range.

General defines:

--------------------------------------------------------------------------

#define PEN_CAT_DRIVER  0x090        /* Driver category       */
#define PEN_CAT_LOCATOR 0x091        /* Locator category      */
#define PEN_CAT_BUTTON  0x092        /* Button category       */
#define PEN_CAT_DISPLAY 0x093        /* Display category      */

#define PEN_IOCTL_LEV_MAJOR 0        /* IOCtl interface level */
#define PEN_IOCTL_LEV_MINOR 3        /* IOCtl interface level */

--------------------------------------------------------------------------

The rest of this section describes the IOCtl functions defined in PENIOCTL. H.

Category 90h - Driver IOCtls

The following are Category 90h - Driver IOCtls:

�Function 50h- Set Unit Specific Data
�Function 51h- Set Unit Variable
�Function 52h- Reset Trace Table
�Function 53h- Set Trace Table Size
�Function 60h- Query Unit Specific Data
�Function 61h- Query Unit Variables
�Function 62h- Query Unit Capabilities
�Function 63h- Query Trace Table
�Function 64h- Query Trace Table Size

Set Unit Specific Data - Function 50h

---

Category 90h, Driver IOCtls- Set Unit Specific Data

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

---

#define PEN_FUNC_SUSD 0x050

This function sets the device-specific data for the requested unit.

Category 90h, Function 50h - Description

#define PEN_FUNC_SUSD 0x050

This function sets the device-specific data for the requested unit.

Category 90h, Driver IOCtls - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Requested unit                 ULONG     |
|-----------------------------------------|
|Byte count of the              ULONG     |
|device-specific data area                |
\-----------------------------------------/

Category 90h, Driver IOCtls - Data Packet Format

Device specific structure, first LONG has byte count.

Note:If the device supports standard locator unit-specific data, this structure is used by the sample driver to maintain calibration alignment data. Other driver information can be appended after this standard structure.

Category 90h, Function 50h -

Category 90h, Driver IOCtls- Set Unit Specific Data

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

Set Unit Variable - Function 51h

---

Category 90h, Driver IOCtls- Set Unit Variable

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

---

#define PEN_FUNC_SUV 0x051

This function sets the device-specific variable for the requested unit.

Category 90h, Function 51h - Description

#define PEN_FUNC_SUV 0x051

This function sets the device-specific variable for the requested unit.

Category 90h, Driver IOCtls - Parameter Packet Format

/---------------------------------------\
|Field                        Length    |
|---------------------------------------|
|Requested unit               ULONG     |
|---------------------------------------|
|Index of variable to set     ULONG     |
|---------------------------------------|
|Value to set                 LONG      |
\---------------------------------------/

Category 90h, Driver IOCtls - Data Packet Format

None.

Category 90h, Function 51h -

Category 90h, Driver IOCtls- Set Unit Variable

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

Reset Trace Table - Function 52h

---

Category 90h, Driver IOCtls- Reset Trace Table

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

---

#define PEN_FUNC_RTT 0x052

This function resets the transaction trace buffer. Resetting the trace buffer is a convenient way to view only current stroke data.

Category 90h, Function 52h - Description

#define PEN_FUNC_RTT 0x052

This function resets the transaction trace buffer. Resetting the trace buffer is a convenient way to view only current stroke data.

Category 90h, Driver IOCtls - Parameter Packet Format

None.

Category 90h, Driver IOCtls - Data Packet Format

None.

Category 90h, Function 52h -

Category 90h, Driver IOCtls- Reset Trace Table

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

Set Trace Table Size - Function 53h

---

Category 90h, Driver IOCtls- Set Trace Table Size

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

---

#define PEN_FUNC_STTS 0x053

This function allocates a trace table for tracing.

Category 90h, Function 53h - Description

#define PEN_FUNC_STTS 0x053

This function allocates a trace table for tracing.

Category 90h, Driver IOCtls - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Number of LONG values in table ULONG     |
|(Number of bytes/4)                      |
\-----------------------------------------/

Category 90h, Driver IOCtls - Data Packet Format

None.

Category 90h, Function 53h -

Category 90h, Driver IOCtls- Set Trace Table Size

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

Query Unit Specific Data - Function 60h

---

Category 90h, Driver IOCtls- Query Unit Specific Data

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

---

#define PEN_FUNC_QUSD 0x060

This function reads the device-specific data for the requested unit. The device-specific data area is truncated when the pqusd.byteCountis less than the length of the device-specific data. The first ULONG in the unit- specific data is the entire length of the area. This is not reduced to reflect a truncated query.

Category 90h, Function 60h - Description

#define PEN_FUNC_QUSD 0x060

This function reads the device-specific data for the requested unit. The device-specific data area is truncated when the pqusd.byteCountis less than the length of the device-specific data. The first ULONG in the unit- specific data is the entire length of the area. This is not reduced to reflect a truncated query.

Category 90h, Driver IOCtls - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Requested unit                 ULONG     |
|-----------------------------------------|
|Byte count of the device       ULONG     |
|specific data area                       |
|-----------------------------------------|
|Bytes returned (output         ULONG     |
|parameter)                               |
|-----------------------------------------|
|Return code (output parameter) ULONG     |
|-----------------------------------------|
|Capabilities (output           ULONG     |
|parameter)                               |
\-----------------------------------------/

Category 90h, Driver IOCtls - Data Packet Format

Device specific structure.

Category 90h, Function 60h - Remarks

Values for pqusd.capabilities:

#define QUSD_RESERVD 0x0000FFFF       /* Reserved for architected use        */
#define QUSD_OEM     0xFFFF0000       /* Reserved for OEM use                */

The following are defined for all device types:

#define QUSD_LENGTH   0x00000001      /* First word of unit data is length.  */
#define QUSD_STANDARD 0x00000002      /* Starts with standard
                                         device-specific layout.             */

The following are locator specific:

#define QUSD_X_INVERT 0x00000004      /* X raw coordinate is inverted.       */
#define QUSD_Y_INVERT 0x00000008      /* Y raw coordinate is inverted.       */

Values for pqusd.rc:

#define QUSD_OK     0       /* All data was copied.                */
#define QUSD_TRUNC  1       /* Data was truncated.                 */
#define QUSD_NA     2       /* Data is not available; none copied. */

typedef struct _SLUSD {
   ULONG   length;           /* Length of entire data area             */
   ULONG   XoriginDefault;   /* Default x origin coordinate adjustment */
   ULONG   Xorigin;          /* x-coordinate origin adjustment         */
   ULONG   XmeasuredExtent;  /* Measured x extent                      */
   ULONG   YoriginDefault;   /* Default y origin coordinate adjustment */
   ULONG   Yorigin;          /* y-coordinate origin adjustment         */
   ULONG   YmeasuredExtent;  /* Measured y extent                      */
} SLUSD;

Category 90h, Function 60h -

Category 90h, Driver IOCtls- Query Unit Specific Data

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

Query Unit Variables - Function 61h

---

Category 90h, Driver IOCtls- Query Unit Variables

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 

---

#define PEN_FUNC_QUV 0x061

This function gets the device-specific variable from the requested unit. Unit 0, variable 0, returns an error counter. Unit 0, variable 1, returns a panic flag word.

Category 90h, Function 61h - Description

#define PEN_FUNC_QUV 0x061

This function gets the device-specific variable from the requested unit. Unit 0, variable 0, returns an error counter. Unit 0, variable 1, returns a panic flag word.

Category 90h, Driver IOCtls - Parameter Packet Format

/---------------------------------------\
|Field                        Length    |
|---------------------------------------|
|Requested unit               ULONG     |
|---------------------------------------|
|Index of variable to set     ULONG     |
\---------------------------------------/

Category 90h, Driver IOCtls - Data Packet Format

/-----------------------------\
|Field              Length    |
|-----------------------------|
|Value returned     ULONG     |
\-----------------------------/

Category 90h, Function 61h - Data Structure

typedef struct _D_QUV {
   ULONG   value;           /* Value returned */
} DQUV;

Note:The sample program provided in the Pen for OS/2 Developer's Toolkit uses unit 0 and variable 0 to report the error count. To report the panic values (internal errors), the Pen for OS/2 Developer's Toolkit sample program uses unit 0 and variable 1. The numerical panic values are mapped to their meanings in the PEN.INC file.

Category 90h, Function 61h -

Category 90h, Driver IOCtls- Query Unit Variables

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 

Query Unit Capabilities - Function 62h

---

Category 90h, Driver IOCtls- Query Unit Capabilities

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

---

#define PEN_FUNC_QUC 0x062

This function returns the capabilities for the unit.

Category 90h, Function 62h - Description

#define PEN_FUNC_QUC 0x062

This function returns the capabilities for the unit.

Category 90h, Driver IOCtls - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Requested unit                 ULONG     |
|-----------------------------------------|
|Size in bytes of area to       ULONG     |
|receive data                             |
|-----------------------------------------|
|Bytes returned (output         ULONG     |
|parameter)                               |
|-----------------------------------------|
|Return code (output parameter) ULONG     |
\-----------------------------------------/

Category 90h, Driver IOCtls - Data Packet Format

Area to receive extended information registration packet (defined in PENEI. H).

Category 90h, Function 62h - Remarks

Values for pquc.rcare the same as for spqusd.rc.

Category 90h, Function 62h -

Category 90h, Driver IOCtls- Query Unit Capabilities

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

Query Trace Table - Function 63h

---

Category 90h, Driver IOCtls- Query Trace Table

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

---

#define PEN_FUNC_QTT 0x063

This function returns the valid entries in the trace table. Each entry is a DWORD (4 bytes) and can be considered an array of ULONGs. The first entry has the number of valid entries to follow.

Category 90h, Function 63h - Description

#define PEN_FUNC_QTT 0x063

This function returns the valid entries in the trace table. Each entry is a DWORD (4 bytes) and can be considered an array of ULONGs. The first entry has the number of valid entries to follow.

Category 90h, Driver IOCtls - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Number of LONGs in allocated   ULONG     |
|table                                    |
\-----------------------------------------/

Category 90h, Driver IOCtls - Data Packet Format

PLONG to trace table array.

Category 90h, Function 63h - Remarks

Each entry has a trace code describing the contents of the entry:

#define TRACE_MASK      0x0FF000000   /* Isolate trace code from entry.          */
#define TRACE_MASK_SUB  0x0F0000000   /* Isolate sub code value.                 */

#define TRACE_INT       0x0F0000000   /* Interrupt event                         */
#define TRACE_INT_H     0x0F000

#define TRACE_TICK      0x0C0000000   /* Timer tick; low word is tick count.     */
#define TRACE_TICK_H    0x0C000
#define TRACE_ABS       0x010000000   /* Absolute packet sub trace code          */
#define TRACE_ABS_E     0x01E000000   /* -- Mouse button event is low word.      */
#define TRACE_ABS_EH    0x01E00
#define TRACE_ABS_X     0x011000000   /* -- x-coordinate is low word.            */
#define TRACE_ABS_XH    0x01100
#define TRACE_ABS_Y     0x012000000   /* -- y-coordinate is low word.            */
#define TRACE_ABS_YH    0x01200
#define TRACE_ABS_Z     0x014000000   /* -- z-coordinate is low word.            */
#define TRACE_ABS_ZH    0x01400
#define TRACE_ABS_D     0x015000000   /* -- EI device bits                       */
#define TRACE_ABS_DH    0x01500
#define TRACE_ABS_C     0x016000000   /* -- EI control word
#define TRACE_ABS_CH    0x01600

#define TRACE_ERROR     0x0E0000000   /* Error trace; word is error count.       */
#define TRACE_ERROR_H   0x0E000

#define TRACE_DATA      0x000000000   /* Raw data trace; byte is in low byte.    */
#define TRACE_DATA_1    0x001000000   /* -- First byte of a packet (optional)    */
#define TRACE_DATA_1H   0x00100
#define TRACE_DATA_H    0x00000       /* -- Not first byte                       */

#define TRACE_SYS       0x020000000   /*  System device event (EMI only)         */
#define TRACE_SYS_H     0x02000       /*                                         */
#define TRACE_BUTTON    0x0B0000000   /* Button event sub trace code             */
#define TRACE_BREL      0x0B0000000   /* Button release mask is low word.        */
#define TRACE_BREL_H    0x0B000
#define TRACE_BACT      0x0B1000000   /* Button activation mask is low word.     */
#define TRACE_BACT_H    0x0B100

#define TRACE_DISPLAY   0x0D0000000   /* Display event sub trace code            */
#define TRACE_DOFF      0x0D0000000   /* Display is turned off.                  */
#define TRACE_DOFF_H    0x0D000
#define TRACE_DON       0x0D1000000   /* Display is turned on.                   */
#define TRACE_DON_H     0x0D100
#define TRACE_DD        0x090000000   /* Trace is device dependent.              */
                                      /* Low word is data; second byte is index. */
#define TRACE_DD_H      0x09000

Category 90h, Function 63h -

Category 90h, Driver IOCtls- Query Trace Table

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

Query Trace Table Size - Function 64h

---

Category 90h, Driver IOCtls- Query Trace Table Size

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 

---

#define PEN_FUNC_QTTS 0x064

This function returns the size of the entire trace table. This function can be used to obtain the memory allocation size to be used for the Query Trace Table function.

Category 90h, Function 64h - Description

#define PEN_FUNC_QTTS 0x064

This function returns the size of the entire trace table. This function can be used to obtain the memory allocation size to be used for the Query Trace Table function.

Category 90h, Driver IOCtls - Parameter Packet Format

None.

Category 90h, Driver IOCtls - Data Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Number of LONG values in table ULONG     |
|(Number of bytes/4)                      |
\-----------------------------------------/

Category 90h, Function 64h - Data Structure

typedef struct _D_QTTS {
  ULONG   size;         /* Number of LONG values in table
                           (number of bytes/4)            */
} DQTTS;

Category 90h, Function 64h -

Category 90h, Driver IOCtls- Query Trace Table Size

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 

Category 91h - Locator IOCtls

The following are Category 91h - Locator IOCtls:

�Function 50h- Set Locator Offset
�Function 51h- Set Locator Pass Rate
�Function 52h- Set Locator Sample Rate
�Function 60h- Query Locator Variables
�Function 61h- Query Locator Raw Coordinates

Set Locator Offset - Function 50h

---

Category 91, Locator IOCtls- Set Locator Offset

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

---

#define PEN_FUNC_SLO 0x050

This function is used to change the finger offset of the digitizer. An offset can be negative. Both or either offsets can be changed according to the functions ORed in the command field.

Category 91h, Function 50h - Description

#define PEN_FUNC_SLO 0x050

This function is used to change the finger offset of the digitizer. An offset can be negative. Both or either offsets can be changed according to the functions ORed in the command field.

Category 91, Locator IOCtls - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Requested unit                 ULONG     |
|-----------------------------------------|
|Command                        ULONG     |
|-----------------------------------------|
|X offset in digitizer units    ULONG     |
|-----------------------------------------|
|Y offset in digitizer units    ULONG     |
\-----------------------------------------/

Category 91, Locator IOCtls - Data Packet Format

None.

Category 91h, Function 50h - Remarks

Values for pslo.command:

#define PSLO_SET_X   0x01      /* Set x offset        */
#define PSLO_SET_Y   0x02      /* Set y offset        */

Category 91h, Function 50h -

Category 91, Locator IOCtls- Set Locator Offset

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

Set Locator Pass Rate - Function 51h

---

Category 91h, Locator IOCtls- Set Locator Pass Rate

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

---

#define PEN_FUNC_SLPR 0x051

This function is used to change the OS/2 event rate. If the rate=2, then for every 2 digitizer samples only 1 is reported to Pen for OS/2 as a mouse event. All samples are reported to Pen for OS/2.

If left at 0, Pen for OS/2 device driver services will calculate the pass rate automatically. This variable should be used only if the automatic value requires manual tuning.

Category 91h, Function 51h - Description

#define PEN_FUNC_SLPR 0x051

This function is used to change the OS/2 event rate. If the rate=2, then for every 2 digitizer samples only 1 is reported to Pen for OS/2 as a mouse event. All samples are reported to Pen for OS/2.

If left at 0, Pen for OS/2 device driver services will calculate the pass rate automatically. This variable should be used only if the automatic value requires manual tuning.

Category 91h, Locator IOCtls - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Requested unit                 ULONG     |
|-----------------------------------------|
|Number of ext events for each  ULONG     |
|OS/2 event                               |
\-----------------------------------------/

Category 91h, Locator IOCtls - Data Packet Format

None.

Category 91h, Function 51h -

Category 91h, Locator IOCtls- Set Locator Pass Rate

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

Set Locator Sample Rate - Function 52h

---

Category 91h, Locator IOCtls- Set Locator Sample Rate

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

---

#define PEN_FUNC_SLSR 0x052

This function is used to change the sample rate. The device must round the rate to the closest value.

Category 91h, Function 52h - Description

#define PEN_FUNC_SLSR 0x052

This function is used to change the sample rate. The device must round the rate to the closest value.

Category 91h, Locator IOCtls - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Requested unit                 ULONG     |
|-----------------------------------------|
|Sample rate in samples per     ULONG     |
|second                                   |
\-----------------------------------------/

Category 91h, Locator IOCtls - Data Packet Format

None.

Category 91h, Function 52h -

Category 91h, Locator IOCtls- Set Locator Sample Rate

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

Query Locator Variables - Function 60h

---

Category 91, Locator IOCtls- Query Locator Variables

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 

---

#define PEN_FUNC_QLV 0x060

This function returns the Pen for OS/2 locator variables.

Category 91h, Function 60h - Description

#define PEN_FUNC_QLV 0x060

This function returns the Pen for OS/2 locator variables.

Category 91, Locator IOCtls - Parameter Packet Format

/-----------------------------\
|Field              Length    |
|-----------------------------|
|Requested unit     ULONG     |
\-----------------------------/

Category 91, Locator IOCtls - Data Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|X offset in digitizer units    LONG      |
|-----------------------------------------|
|Y offset in digitizer units    LONG      |
|-----------------------------------------|
|Pass rate                      ULONG     |
|-----------------------------------------|
|Sample rate in samples per     ULONG     |
|second                                   |
\-----------------------------------------/

Category 91h, Function 60h - Data Structure

typedef struct _D_QLV {
   LONG   xOffset;      /* x offset in digitizer units       */
   LONG   yOffset;      /* y offset in digitizer units       */
   ULONG  passRate;     /* Pass rate                         */
   ULONG  sampelRate;   /* Sample rate in samples per second */
} DQLV;

Category 91h, Function 60h -

Category 91, Locator IOCtls- Query Locator Variables

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 

Query Locator Raw Coordinates - Function 61h

---

Category 91h, Locator IOCtls- Query Locator Raw Coordinates

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 
Remarks 

---

#define PEN_FUNC_QLRC 0x061

This function returns the next valid raw locator coordinate. The dqlrc.rcvalue reflects whether a coordinate value was available within the specified timeout period.

Category 91h, Function 61h - Description

#define PEN_FUNC_QLRC 0x061

This function returns the next valid raw locator coordinate. The dqlrc.rcvalue reflects whether a coordinate value was available within the specified timeout period.

Category 91h, Locator IOCtls - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Requested unit                 ULONG     |
|-----------------------------------------|
|Timeout value in milliseconds  ULONG     |
\-----------------------------------------/

Category 91h, Locator IOCtls - Data Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Return code                    LONG      |
|-----------------------------------------|
|X offset in raw digitizer      LONG      |
|units                                    |
|-----------------------------------------|
|Y offset in raw digitizer      LONG      |
|units                                    |
\-----------------------------------------/

Category 91h, Function 61h - Data Structure

typedef struct _D_QLRC {
  LONG   rc;            /* Return code              */
  LONG   xRaw;          /* x in raw digitizer units */
  LONG   yRaw;          /* y in raw digitizer units */

} DQLRC;

Category 91h, Function 61h - Remarks

Values for dqlrc.rc:

#define  QLRC_VALID      0     /* Valid coordinates returned.           */
#define  QLRC_TIMEOUT    1     /* Timed out, coordinates are not valid. */
#define  QLRC_BUSY       2     /* Only one thread at a time allowed.    */

Category 91h, Function 61h -

Category 91h, Locator IOCtls- Query Locator Raw Coordinates

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 
Remarks 

Query Default Locator Extents - Function 62h

---

Category 91h, Locator IOCtls- Query Default Locator Extents

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 
Remarks 

---

#define PEN_FUNC_QDLE 0x062

This function returns the default locator extents. The dqdle.rcvalue reflects whether the default extents were retrieved.

Category 91h, Function 62h - Description

#define PEN_FUNC_QDLE 0x062

This function returns the default locator extents. The dqdle.rcvalue reflects whether the default extents were retrieved.

Category 91h, Locator IOCtls - Parameter Packet Format

/-----------------------------\
|Field              Length    |
|-----------------------------|
|Requested unit     ULONG     |
\-----------------------------/

Category 91h, Locator IOCtls - Data Packet Format

/--------------------------\
|Field           Length    |
|--------------------------|
|Return code     LONG      |
|--------------------------|
|X extent        ULONG     |
|--------------------------|
|Y extent        ULONG     |
\--------------------------/

Category 91h, Function 62h - Data Structure

typedef struct _D_QDLE {
  ULONG   rc;            /* Return code              */
  ULONG   Xdefault;      /* x default extent         */
  ULONG   Ydefault;      /* y default dextent        */

} DQDLE;

Category 91h, Function 62h - Remarks

Values for dqdle.rc:

#define  QDLE_OK         0     /* The default extents were valid.       */
#define  QDLE_FAIL       1     /* The default extents were not valid.   */

Category 91h, Function 62h -

Category 91h, Locator IOCtls- Query Default Locator Extents

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 
Remarks 

Category 92h - Button IOCtls

The following are Category 92h - Button IOCtls:

�Function 50h- Set Button Assignment
�Function 60h- Query Button Assignment

Set Button Assignment - Function 50h

---

Category 92h, Button IOCtls- Set Button Assignment

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

---

#define PEN_FUNC_SBA 0x050

This function sets the assignment for a button.

Category 92h, Function 50h - Description

#define PEN_FUNC_SBA 0x050

This function sets the assignment for a button.

Category 92h, Button IOCtls - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Requested unit                 ULONG     |
|-----------------------------------------|
|Index of button (0 to 15)      ULONG     |
|-----------------------------------------|
|Action to perform              ULONG     |
|-----------------------------------------|
|Hot-key value for hot-key      ULONG     |
|assignment                               |
|-----------------------------------------|
|Mouse button selection mask    ULONG     |
\-----------------------------------------/

Category 92h, Button IOCtls - Data Packet Format

None.

Category 92h, Function 50h - Remarks

Values for psba.action:

Note:Values mustmatch order of capability fields in DCAP struct.

#define  NOBUTTONACTION     0     /* Null - do nothing (the default).            */
#define  SENDHOTKEY         1     /* Send hot key; value in PSBA.hotkey.         */
#define  SHIFTBUTTON        2     /* Set shift for button using mouseButtonMask. */
#define  APPLBUTTON         3     /* Assign button for application use.          */
#define  AUGMENTATIONBUTTON 4     /* Assign button for key augmentation.         */
#define  GESTUREMODE        5     /* Assign button for gesture mode.             */

Values for psba.valuefor action = SHIFTBUTTON:

#define  MOUSEBUTTON1     0x04    /* Mouse button 1                              */
#define  MOUSEBUTTON2     0x10    /* Mouse button 2                              */
#define  MOUSEBUTTON3     0x40    /* Mouse button 3                              */

Values for psba.valuefor action = SENDHOTKEY:

#define HOTKEY_CNTRL_ESC    1     /* Do a Ctrl+Esc.                              */
#define HOTKEY_ALT_ESC      2     /* Do an Alt+Esc.                              */

Category 92h, Function 50h -

Category 92h, Button IOCtls- Set Button Assignment

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

Query Button Assignment - Function 60h

---

Category 92h, Button IOCtls- Query Button Assignment

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 

---

#define PEN_FUNC_QBA 0x060

This function returns the assignment of a button.

Category 92h, Function 60h - Description

#define PEN_FUNC_QBA 0x060

This function returns the assignment of a button.

Category 92h, Button IOCtls - Parameter Packet Format

/----------------------------------------\
|Field                         Length    |
|----------------------------------------|
|Requested unit                ULONG     |
|----------------------------------------|
|Index of button (0 to 15)     ULONG     |
\----------------------------------------/

Category 92h, Button IOCtls - Data Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Action to perform              ULONG     |
|-----------------------------------------|
|Hot-key value for hot-key      ULONG     |
|assignment or mouse button               |
|selection mask                           |
\-----------------------------------------/

Category 92h, Function 60h - Data Structure

typedef struct _D_QBA {
  ULONG   action;           /* Action to perform                    */
  ULONG   value;            /* Hot-key value for hot-key assignment
                               or mouse button selection mask       */
} DQBA;

Category 92h, Function 60h -

Category 92h, Button IOCtls- Query Button Assignment

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 

Category 93h - Display IOCtls

The following are Category 93h - Display IOCtls:

• Function 50h- Set Display State
• Function 51h- Set Display Inactivity Period
• Function 60h- Query Display State

Set Display State - Function 50h

---

Category 93h, Display IOCtls- Set Display State

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

---

#define PEN_FUNC_SDS 0x050        /* Set display state.          */

#define TURNBACKLIGHTON     1     /* Value to turn backlight on  */
#define TURNBACKLIGHTOFF    0     /* Value to turn backlight off */

This function is used to turn the backlight either on or off. Turning on the backlight restarts the inactivity timer. The inactivity timer is used only if automatic control is enabled.

Category 93h, Function 50h - Description

#define PEN_FUNC_SDS 0x050        /* Set display state.          */

#define TURNBACKLIGHTON     1     /* Value to turn backlight on  */
#define TURNBACKLIGHTOFF    0     /* Value to turn backlight off */

This function is used to turn the backlight either on or off. Turning on the backlight restarts the inactivity timer. The inactivity timer is used only if automatic control is enabled.

Category 93h, Display IOCtls - Parameter Packet Format

/----------------------------------------\
|Field                         Length    |
|----------------------------------------|
|Requested unit                ULONG     |
|----------------------------------------|
|Command to turn on or off     ULONG     |
\----------------------------------------/

Category 93h, Display IOCtls - Data Packet Format

None.

Category 93h, Function 50h -

Category 93h, Display IOCtls- Set Display State

Select an item:

Description
Parameter Packet Format 
Data Packet Format 

Set Display Inactivity Period - Function 51h

---

Category 93h, Display IOCtls- Set Display Inactivity Period

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

---

#define PEN_FUNC_SDIP 0x051

This function controls how the driver handles turning the display backlight on and off automatically. The following options can be set:

AutoEnable = (enable | disable) When enabled, the backlight is turned off after a period of no user activity. User activity turns the backlight back on. User activity consists of input from any locator device, buttons, the OS/2 mouse, or the keyboard.

Opaque = (enable | disable) When enabled, button actions and locator points from this driver are processed even though the backlight is off. When disabled, button actions are not processed, and locator points are sent to the device driver services but are not processed by the OS/2 operating system.

Suppress = (enable | disable) When enabled, button down action from the locator or a mouse action that turned the backlight on will be ignored and reported as a movement only. Button actions will be ignored.

Period = <seconds> The length of the inactivity period in seconds.

All of these options are independent. All combinations can be specified on a single IOCtl call. AutoEnable, Suppress, and Period are processed only if the display device capabilities allow automatic backlight control.

Category 93h, Function 51h - Description

#define PEN_FUNC_SDIP 0x051

This function controls how the driver handles turning the display backlight on and off automatically. The following options can be set:

AutoEnable = (enable | disable) When enabled, the backlight is turned off after a period of no user activity. User activity turns the backlight back on. User activity consists of input from any locator device, buttons, the OS/2 mouse, or the keyboard.

Opaque = (enable | disable) When enabled, button actions and locator points from this driver are processed even though the backlight is off. When disabled, button actions are not processed, and locator points are sent to the device driver services but are not processed by the OS/2 operating system.

Suppress = (enable | disable) When enabled, button down action from the locator or a mouse action that turned the backlight on will be ignored and reported as a movement only. Button actions will be ignored.

Period = <seconds> The length of the inactivity period in seconds.

All of these options are independent. All combinations can be specified on a single IOCtl call. AutoEnable, Suppress, and Period are processed only if the display device capabilities allow automatic backlight control.

Category 93h, Display IOCtls - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Requested unit                 ULONG     |
|-----------------------------------------|
|Command to turn enable and     ULONG     |
|disable                                  |
|-----------------------------------------|
|Inactivity period in seconds   ULONG     |
\-----------------------------------------/

Category 93h, Display IOCtls - Data Packet Format

None.

Category 93h, Function 51h - Remarks

PSDIP.commandvalues:

#define SDIP_PERIOD      0x01    /* Change period value                   */
#define SDIP_EN_AUTO     0x02    /* Enable automatic inactivity period    */
#define SDIP_DI_AUTO     0x04    /* Disable automatic inactivity period   */
#define SDIP_EN_OPAQUE   0x08    /* Process events while backlight is off */
#define SDIP_DI_OPAQUE   0x10    /* Ignore events while backlight is off  */
#define SDIP_EN_SUPPRESS 0x20    /* Suppress after auto turn on           */
#define SDIP_DI_SUPPRESS 0x40    /* Do not suppress after auto turn on    */

Category 93h, Function 51h -

Category 93h, Display IOCtls- Set Display Inactivity Period

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Remarks 

Query Display State - Function 60h

---

Category 93h, Display IOCtls- Query Display State

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 
Remarks 

---

#define PEN_FUNC_QDS 0x060

This function returns whether the automatic inactivity period monitor is enabled or disabled, and if enabled, the time remaining in the inactivity period.

Category 93h, Function 60h - Description

#define PEN_FUNC_QDS 0x060

This function returns whether the automatic inactivity period monitor is enabled or disabled, and if enabled, the time remaining in the inactivity period.

Category 93h, Display IOCtls - Parameter Packet Format

/-----------------------------\
|Field              Length    |
|-----------------------------|
|Requested unit     ULONG     |
\-----------------------------/

Category 93h, Display IOCtls - Data Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|State of backlight             ULONG     |
|-----------------------------------------|
|Automatic options              ULONG     |
|-----------------------------------------|
|Inactivity period in seconds   ULONG     |
\-----------------------------------------/

Category 93h, Function 60h - Data Structure

typedef struct _D_QDS {
  ULONG  state;        /* State of backlight                          */
  ULONG  automatic;    /* Automatic options                           */
  ULONG  period;       /* Inactivity period in seconds                */
} DQDS;

Category 93h, Function 60h - Remarks

DQDS.stateuses same values as PSDIP.state.

DQDS.automaticuses same values as PSDIP.command.

Category 93h, Function 60h -

Category 93h, Display IOCtls- Query Display State

Select an item:

Description
Parameter Packet Format 
Data Packet Format 
Data Structure 
Remarks 

Pen for OS/2 Extended Interface

This section describes the extended Pen for OS/2 system extension interface , including the direct call interface to the device driver services.

General defines:

--------------------------------------------------------------------------

#define PEN_DDS_LEV_MAJOR 0             /* Level of this specification           */
#define PEN_DDS_LEV_MINOR 3             /* Level of this specification           */

--------------------------------------------------------------------------

DevHlp_RegisterDeviceClass values:

--------------------------------------------------------------------------

#define DEVCLASS_INPUT 2                /* Device class for RegisterDeviceClass  */

--------------------------------------------------------------------------

Defines for DCFlags:

--------------------------------------------------------------------------

#define REG_EXT_IF  0x0001              /* Supports extended interface           */
#define REG_AUX     0x8000              /* Keyboard AUX port used                */

--------------------------------------------------------------------------

Pen Device Driver IDC Interface

These IDC requests are provided by the pen device driver at the IDC entry point declared with DevHlp_RegisterDeviceClass and are defined in PENIDC.H:

--------------------------------------------------------------------------

#define QUERY_CAPABILITIES     1    /* Request unit capabilities
                                       bl = unit
                                       es:di = Area to copy capabilities packet;
                                                first word has size of copy buffer
                                       Successful return
                                        nc (no carry), ax = 0, Packet copied
                                       Error return
                                        cy (carry), ax == Error code              */

#define QUERY_DEV_CONFIG       2    /* Query optional device configuration
                                       bl = unit
                                       es:di = target DevData packet address      */
#define START_LOGICAL_DEVICE   3    /* Start logical device
                                       bl = unit
                                       es:di = SINFO packet
                                       Successful return
                                        nc, ax = 0, Registration accepted
                                       Error return
                                        cy, ax = = Error code
                                        4 and 5 are reserved for future
                                        "by unit" calls                           */

--------------------------------------------------------------------------

These functions invoke global calls to the driver:

--------------------------------------------------------------------------

#define  READ_ENABLE           6    /* Enable reporting of events
                                       pass   cx:dx style capabilities to driver
                                       return cx:dx style request to services     */
#define  READ_DISABLE          7    /* Disable reporting of events                */
#define  ENABLE_DEVICE         8    /* Enable the device to interrupt             */
#define  DISABLE_DEVICE        9    /* Disable the device from interrupting       */
#define  ACTIVITY_CALLBACK    10    /* System activity callback (called
                                       as result of REQUEST_CALLBACK)             */
#define  VIDEO_MODE_CHANGE    11    /* Video mode change
                                       cl == -1 Start of change
                                              0 End of change
                                       ch == -1 Packet is valid
                                              0 Packet is invalid
                                       es:di = VINFO packet                       */

--------------------------------------------------------------------------

Style capabilities for READ_ENABLE (See 6 above): CX register is reserved, must be 0.

Style capabilities for READ_ENABLE: DX register:

--------------------------------------------------------------------------

#define STYLE_NOTIFY_VMCHANGE 0x0001  /* Report VM_CHANGE
                                               on = DON'T report, reset
                                               to receive events           */

--------------------------------------------------------------------------

Error Codes:

--------------------------------------------------------------------------

#define DRV_ERR_GEN_ERROR   1         /* General error                     */
#define DRV_ERR_NOT_FOUND   2         /* Unit number not found             */
#define DRV_ERR_BUFF_TRUNC  3         /* Registration packet truncated,
                                         buffer small                      */
#define DRV_ERR_LEVEL       4         /* Level mismatch                    */
#define DRV_ERR_NOT_ALLOWED 5         /* Request not allowed at this time  */
#define DRV_ERR_NO_FUNC     6         /* Function not supported            */

--------------------------------------------------------------------------

The following packet is passed on READ_ENABLE. The packet and service routine is valid only during the READ_ENABLE call.

--------------------------------------------------------------------------

typedef struct _SINFO  {    /* sinfo                                    */
  USHORT length;            /* Total length of packet                   */
  UCHAR  eif_major;         /* Major level (PEN_EI_LEV_MAJOR)           */
  UCHAR  eif_minor;         /* Minor level (PEN_EI_LEV_MINOR)           */
  UCHAR  idc_major;         /* Major level (PEN_DDS_LEV_MAJOR)          */
  UCHAR  idc_minor;         /* Minor level (PEN_DDS_LEV_MINOR)          */
  USHORT service_ds;        /* Data segment to load for service routine */
  ULONG  service_rtn;       /* 16:16 address for service routine        */

} SINFO;

--------------------------------------------------------------------------

The following packet is passed on VIDEO_MODE_CHANGE.

--------------------------------------------------------------------------

typedef struct _VINFO   {        /* vinfo                      */
  UCHAR  Mtype;                  /* Video mode type            */
  UCHAR  Color;                  /* Number of colors           */
  UCHAR  TCol_res;               /* Text column   resolution       * / 
   USHORT   TRow _ res ;                  / *   Text   row   resolution          * / 
   USHORT   GCol _ res ;                  / *   Graphics   column   resolution   * / 
   USHORT   GRow _ res ;                  / *   Graphics   row   resolution      * / 

}   VINFO ; 

--------------------------------------------------------------------------

Defines for vinfo.Mtype:

--------------------------------------------------------------------------

#define MTYPE_GRAPHICS 0x0002   /* Graphics mode */

--------------------------------------------------------------------------

Device data structure is returned by locator devices on QUERY_DEV_CONFIG. The other devices do not have device configuration data to return.

--------------------------------------------------------------------------

typedef struct _DevData {         /* DevData             */
  USHORT CfgDataLen;              /* Length of data      */
  UCHAR  NumMics;                 /* Number mickeys/cm   */
  UCHAR  NumButt;                 /* Number of buttons   */
  UCHAR  IRQ;                     /* IRQ level           */
  UCHAR  MouseType;               /* Mouse type attached */
  UCHAR  ComPortNum;              /* Com port number     */
  USHORT ComPortAddr;             /* Com port address    */
} DevData;

--------------------------------------------------------------------------

Pen for OS/2 Device Driver Services

These services are provided by the Pen for OS/2 system extension at the service entry point and are defined in PENIDC.H:

--------------------------------------------------------------------------

#define REGISTER_DEVICE       1       /* Register device
                                         es:di = Capabilities packet         */
#define REPORT_EVENT          2       /* Report event
                                         es:di = Event packet                */
#define UPDATE_CAPS           3       /* Update registration packet
                                         es:di = Capabilities packet         */
#define QUERY_ACTIVITY        4       /* Query user input activity
                                         Returns dx = low word count
                                                 cx = high word count
                                                edx = dword count            */
#define REQUEST_CALLBACK      5       /* Request callback for system activity
                                         cl = Driver device ID               */
#define CANCEL_CALLBACK       6       /* Cancel callback for system activity
                                         cl = Driver device ID               */
#define SUPPRESS_STROKE       7       /* Suppress stroke
                                         cl = Driver device ID               */
#define DISABLE_SUPPORT       8       /* Disable driver
                                         cl = Driver device ID               */

--------------------------------------------------------------------------

Extended Information Structures

--------------------------------------------------------------------------

#define PEN_EI_LEV_MAJOR  0       /* Level of this specification             */
#define PEN_EI_LEV_MINOR  6       /* Level of this specification             */

--------------------------------------------------------------------------

Defines for all dev_type:

--------------------------------------------------------------------------

#define DT_DRIVER     0x00        /* Index to access driver                  */
#define DT_CONTROL    0x01        /* Control (not used by pen device driver) */
#define DT_SYSTEM     0x02        /* System  (not used by pen device driver) */
#define DT_LOCATOR    0x03        /* Locator                                 */
#define DT_BUTTON     0x04        /* Button                                  */
#define DT_DISPLAY    0x05        /* Display                                 */

--------------------------------------------------------------------------

Common Capabilities Packet

Each capability packet starts with these common fields:

--------------------------------------------------------------------------

typedef struct _CCAP    {   /* ccap                                     */
  USHORT length;            /* Total length of capabilities packet      */
  USHORT device_type        /* Device type                              */
  UCHAR  device_id;         /* Device ID (is returned from registration)*/
  UCHAR  unit;              /* Unit number within the driver            */
  UCHAR  flags;             /* Round to word boundary                   */
  UCHAR  driver_name[8];    /* Device driver name                       */
  UCHAR  device_name[32];   /* Device name                              */
  USHORT event_caps;        /* Events that will be generated            */
}  CCAP;

--------------------------------------------------------------------------

Note: CCAP.event_capsis defined by lev.cev.devicebits, bev.cev.devicebits , and dev.cev.devicebits.

Defines for word boundary flags:

--------------------------------------------------------------------------

#define CCAP_DEFAULTDATA  0x00        /* Use the data from the device driver    */
#define DT_CONTROL        0x01        /* Use the data stored in OS2.INI         */

--------------------------------------------------------------------------

Driver-Specific Capabilities Packet

The unit 0 device capabilities describe the entire driver and are used to:

�Verify the expected levels of the driver match

�Determine the number of logical devices in the driver

--------------------------------------------------------------------------

typedef struct _DDCAP   {    /* ddcap                                 */
  CCAP   ccap;               /* Common capabilities packet            */
  ULONG  capabilities;       /* Reserved                              */
  UCHAR  unitCount;          /* Number of logical devices, including
                                one for the driver device             */
  UCHAR  rev_major;          /* Driver major level                    */
  UCHAR  rev_minor;          /* Driver minor level                    */
  UCHAR  ioc_major;          /* IOCtl interface major level           */
  UCHAR  ioc_minor;          /* IOCtl interface minor level           */
  UCHAR  eif_major;          /* Extended interface major level        */
  UCHAR  eif_minor;          /* Extended interface minor level        */
  UCHAR  idc_major;          /* DDS IDC interface major level         */
  UCHAR  idc_minor;          /* DDS IDC interface minor level         */

} DDCAP;

--------------------------------------------------------------------------

Locator-Specific Capabilities Packet

Defines for LCAP.type:

--------------------------------------------------------------------------

#define LOCTYPE_MOUSE       0x0001   /* Stock device                    */
#define LOCTYPE_PEN         0x0002   /* Pen                             */
#define LOCTYPE_FINGER      0x0004   /* Finger                          */
#define LOCTYPE_OTHER       0x0008   /* Other                           */
#define LOCTYPE_ABSOLUTE    0x0010   /* Absolute                        */
#define LOCTYPE_RELATIVE    0x0020   /* Relative                        */

--------------------------------------------------------------------------

Defines for LCAP.pen_type:

--------------------------------------------------------------------------

#define PENCAP_TETHERED   0x0001    /* 1 - Tethered, 0 - Untethered     */
#define PENCAP_PROXIMITY  0x0002    /* Generates enter and exit events  */
#define PENCAP_TILT       0x0004    /* Stylus tilt angle reported       */
#define PENCAP_ROTATE     0x0008    /* Stylus rotation reported         */
#define PENCAP_OEMDATA    0x0010    /* OEM data reported                */
#define PENCAP_TIMESTAMP  0x0020    /* dev_timestamp reported           */
#define PENCAP_ZPRESSURE  0x0040    /* z-axis represents pressure       */
#define PENCAP_ZHEIGHT    0x0080    /* z-axis represents height         */
#define PENCAP_PIN        0x0100    /* 1=Personal Identification Number */
#define PENCAP_ERASER     0x0200    /* 1=device used as an eraser       */
#define PENCAP_DISPLAY    0x0400    /* 1=integrated display             */

--------------------------------------------------------------------------

Defines for LCAP.std_res:

--------------------------------------------------------------------------

#define STD_RESOLUTION    1000      /* Standard resolution is 1000
                                        points per inch.                */

--------------------------------------------------------------------------

--------------------------------------------------------------------------

typedef struct _LCAP   {  /* lcap                                       */
  CCAP   ccap;            /* Common capabilities packet                 */
  USHORT type;            /* Locator type                               */
  USHORT caps;            /* Locator capabilities                       */
  USHORT sample_rate;     /* Device sample rate                         */
  USHORT max_sample_rate; /* Maximum device sample rate                 */
  UCHAR  barrel_num;      /* Number of barrel buttons                   */
  UCHAR  barrel_mask;     /* Bit position of barrel buttons             */
  ULONG  dev_x_extent;    /* Device x-axis extent                       */
  ULONG  dev_y_extent;    /* Device y-axis extent                       */
  ULONG  std_x_extent;    /* Standard x-axis extent                     */
  ULONG  std_y_extent;    /* Standard y-axis extent                     */
  SHORT  dev_z_p_extent;  /* Device z-axis pressure extent (negative)   */
  SHORT  dev_z_h_extent;  /* Device z-axis height extent (positive)     */
  UCHAR  pass_rate;       /* Device pass rate                           */
  UCHAR  num_mouse_but;   /* Number of mouse buttons emulated by device */
  USHORT std_res;         /* Points per inch for standard resolution    */
  USHORT dev_x_res;       /* Points per inch on x-axis                  */
  USHORT dev_y_res;       /* Points per inch on y-axis                  */
  ULONG  dev_timestampRes;/*Device time stamp resolution in microseconds*/
} LCAP;

--------------------------------------------------------------------------

Note:This structure can be imbedded into an OEM Capabilities Structure if you need to pass additional information such as whether the device time stamp or the OEM_datafield is being used, or how many bytes of the OEM_ datafield are being used.

Button-Specific Capabilities Packet

Defines for BCAP.barreland BCAP.nonBarrelcapabilities (If these bits are set, the action is supported by the barrel or nonbarrel buttons):

--------------------------------------------------------------------------

#define CAP_NOBUTTONACTION     0x0001  /* Null; do nothing (the default) */
#define CAP_SENDHOTKEY         0x0002  /* Hot-key support                */
#define CAP_SHIFTBUTTON        0x0004  /* Shift button support           */
#define CAP_APPLBUTTON         0x0008  /* Button for application use     */
#define CAP_AUGMENTATIONBUTTON 0x0010  /* Button for key augmentation    */
#define CAP_GESMODEBUTTON      0x0020  /* Button for gesture mode        */

#define CAP_DEFAULT_BARREL CAP_NOBUTTONACTION|CAP_SHIFTBUTTON|CAP_GESMODEBUTTON
#define CAP_DEFAULT_NBARREL CAP_DEFAULT_BARREL|
        CAP_SENDHOTKEY|CAP_APPLBUTTON|CAP_AUGMENTATIONBUTTON

--------------------------------------------------------------------------

--------------------------------------------------------------------------

typedef struct _BCAP  { /* bcap                                        */
  CCAP   ccap;          /* Common capabilities packet                  */
  USHORT num;           /* Number of buttons (0 to 16)                 */
  USHORT typeMask;      /* Bit mask for type (1=barrel, 0=not barrel)  */
  USHORT nullMask;      /* Bit mask to show null assignment            */
  USHORT hotKeyMask;    /* Bit mask to show assignment to hot key      */
  USHORT oneTimeMask;   /* Bit mask to show assignment to mouse mode   */
  USHORT shiftMask;     /* Bit mask to show assignment to mouse mode   */
  USHORT appKeyMask;    /* Bit mask to show assignment to appl key     */
  USHORT augKeyMask;    /* Bit mask to show assignment to augmentation */
} BCAP;

--------------------------------------------------------------------------

Note:Button index 0 is represented with the least significant bit in the mask (0x0001).

Display-Specific Capabilities Packet

Defines for DCAP.type:

--------------------------------------------------------------------------

#define DISPTYPE_LCD       0x0001    /* 1 - LCD,      0 - not LCD         */
#define DISPTYPE_CRT       0x0002    /* 1 - CRT,      0 - not CRT         */
#define DISPTYPE_BLANKING  0x0004    /* Display performs screen blanking. */
#define DISPTYPE_COLOR     0x0008    /* 1 - Color,    0 - Monochrome      */
#define DISPTYPE_ATTACHED  0x0010    /* 1 - Attached, 0 - Portable        */
#define DISPTYPE_NO_KBD    0x0020    /* No Keyboard Attached              */
#define DISPTYPE_BATTERY   0x0040    /* 1 - Battery,  0 - AC power        */
#define DISPTYPE_SPEAKER   0x0080    /* 1 - Speaker is close to display.  */

--------------------------------------------------------------------------

--------------------------------------------------------------------------

typedef struct _DCAP   {  /* dcap                                       */
  CCAP   ccap;            /* Common capabilities packet                 */
  USHORT type;            /* Display type                               */
  USHORT auto_flag;       /* Capable of supporting automatic inactivity
                             period (1=yes, 0 = no)                     */
  ULONG  height;          /* Screen height in .01 of an inch            */
  ULONG  width;           /* Screen width in .01 of an inch             */
} DCAP;

--------------------------------------------------------------------------

Common Event Packet

This is a common prefix to all events: locator, button, and display.

--------------------------------------------------------------------------

typedef struct _CEV { /* cev                                            */
  USHORT length;      /* Total length of eiq event packet               */
  UCHAR  device_type; /* Event category - system, locator,
                          display, control                              */
  UCHAR  device_id;   /* Identity of device that generated event        */
  ULONG  timestamp;   /* Millisecond time stamp (not for DD)            */
  UCHAR  session;     /* Foreground session number (not for DD)         */
  UCHAR  cntrl;       /* Control info (not for DD)                      */
  USHORT devicebits;  /* Event field (defined by device type)           */
} CEV;

--------------------------------------------------------------------------

Locator-Specific Event Packet

Defines for LEV.cntrl:

--------------------------------------------------------------------------

#define LOC_PASS_ON        0x0001     /* If set, event is to be passed to PM.
                                           (used by pass rate filter)                */
#define LOC_ARBITRATED_OUT 0x0002     /* For use by arbitration (treat as reserved)  */
#define LOC_SUPPRESSED     0x0004     /* Suppressed contact due to backlight auto on */
#define LOC_BKLT_OFF       0x0008     /* Suppressed contact due to backlight off     */
#define LOC_REL            0x0010     /* dev_x and dev_y are relative                */
#define LOC_ABS            0x0020     /* dev_x and dev_y are absolute                */
#define LOC_FAKE           0x0040     /* Device coordinates are valid, but fake.     */
#define LOC_INVALID        0x0080     /* Coordinates are not valid.                  */
#define LOC_CONTACT        0x0100     /* Indicates the locator is in contact.        */
#define LOC_PROX           0x0200     /* Indicates the locator is in proximity.      */
#define LOC_GSTMODE        0x0400     /* Force gesture mode                          */

--------------------------------------------------------------------------

Defines for LEV.cev.devicebits(low-order byte = mouse event):

--------------------------------------------------------------------------

#define EV_NONE         0x00           /* No buttons, no movement                    */
#define EV_MOVE         0x01           /* Movement only, no buttons                  */
#define EV_BUTTON1_MOVE 0x02           /* Movement and button 1 down                 */
#define EV_BUTTON1      0x04           /* Button 1 down only, no movement            */
#define EV_BUTTON2_MOVE 0x08           /* Movement and button 2 down                 */
#define EV_BUTTON2      0x10           /* Button 2 down only, no movement            */
#define EV_BUTTON3_MOVE 0x20           /* Movement and button 3 down                 */
#define EV_BUTTON3      0x40           /* Button 3 down only, no movement            */

#define EV_ANY_STAT_BUTTON   EV_BUTTON1 | EV_BUTTON2 | EV_BUTTON3
#define EV_ANY_MOVE_BUTTON   EV_BUTTON1_MOVE | EV_BUTTON2_MOVE | EV_BUTTON3_MOVE
#define EV_ANY_MOVE          EV_MOVE | EV_ANY_MOVE_BUTTON
#define EV_ANY_BUTTON        EV_ANY_STAT_BUTTON | EV_ANY_MOVE_BUTTON
#define EV_STD_MOUSE         EV_ANY_STAT_BUTTON | EV_ANY_MOVE

--------------------------------------------------------------------------

(high-order byte = mouse events that changed):

--------------------------------------------------------------------------

#define EV_BUTTON1_CHANGED    0x0400   /* Button 1 changed                           */
#define EV_BUTTON2_CHANGED    0x1000   /* Button 2 changed                           */
#define EV_BUTTON3_CHANGED    0x4000   /* Button 3 changed                           */

#define EV_BUTTON_CHG        EV_BUTTON1_CHANGED|EV_BUTTON2_CHANGED|EV_BUTTON3_CHANGED

--------------------------------------------------------------------------

Stroke events:

--------------------------------------------------------------------------

#define EV_EXIT_PROX  0x0080           /* Exit proximity                             */
#define EV_ENTER_PROX 0x8000           /* Enter proximity                            */
#define EV_PROX              EV_EXIT_PROX | EV_ENTER_PROX

--------------------------------------------------------------------------

--------------------------------------------------------------------------

typedef struct _LEV    {      /* lev                                    */
  CEV  cev;                   /* Common event packet                    */
  USHORT cntrl;               /* Locator control info                   */
  USHORT scr_x;               /* Screen coordinates (NOT filled in by
  USHORT scr_y;                  pen device driver)                     */
  SHORT  scr_z;               /* Normalized z coord (-4k to 4k)         */
  USHORT buttons;             /* State of buttons 0 - 15;               */
  ULONG  dev_x;               /* Device coordinates                     */
  ULONG  dev_y;
  ULONG  std_x;               /* Standard coordinates                   */
  ULONG  std_y;
  SHORT  dev_z;               /* Negative = pressure, positive = height */
  ULONG  dev_timestamp;       /* High resolution device time stamp      */
  USHORT dev_sequence;        /* Increment for each event               */
                              /* Angles range from +180 to -180 degrees */
  SHORT dev_angle_theta;      /* Pen angle from vertical, increases     */
                              /*  in positive x direction.              */
  SHORT dev_angle_phi;        /* Pen angle from vertical, increases     */
                              /*  in positive y direction.              */
  UCHAR  OEM_data[8];         /* OEM-specific locator data (optional)   */
} LEV;

--------------------------------------------------------------------------

Button-Specific Event Packet

Defines for BEV.cev.devicebits:

--------------------------------------------------------------------------

#define BEV_BUTTON_CHANGE       0x01  /* Button change event                     */

--------------------------------------------------------------------------

Defines for BEV.cntrl:

--------------------------------------------------------------------------

#define BEV_SUPPRESSED LOC_SUPPRESSED /* Suppressed contact due to bklt auto-on  */
#define BEV_BKLT_OFF LOC_BKLT_OFF     /* Suppressed contact due to backlight off */

--------------------------------------------------------------------------

--------------------------------------------------------------------------

typedef struct _BEV  {   /* bev                                         */
  CEV  cev;              /* Common event packet                         */
  USHORT cntrl;          /* Button control info                         */
  USHORT state;          /* Button state mask (1=activated, 0=released) */
  USHORT change;         /* Mask, 1= Changed since last event report    */
  UCHAR  action;         /* Action to perform                           */
  UCHAR  value;          /* Hot-key value for hot-key assignment or     */
                         /* Mouse button selection mask                 */
  UCHAR  OEM_data[8];    /* OEM-specific display data (optional)        */
} BEV;

--------------------------------------------------------------------------

Display-Specific Event Packet

Defines for DEV.cev.devicebits:

--------------------------------------------------------------------------

#define DEV_BACKLIGHT_CHANGE    0x01 /* State of backlight changed */

--------------------------------------------------------------------------

--------------------------------------------------------------------------

typedef struct _DEV     {     /* dev                                  */
  CEV  cev;                   /* Common event packet                  */
  USHORT state;               /* State of backlight (0=off, 1=on)     */
  USHORT OEM_data[8];         /* OEM-specific display data (optional) */
} DEV;

--------------------------------------------------------------------------

Pen for OS/2 Component of IBM Developer Connection Device Driver Kit for OS/2

This appendix describes the contents of the Pen for OS/2 component of IBM Developer Connection Device Driver Kit for OS/2 pertaining to the development of a pen device driver.

Subdirectory Structure

The subdirectory structure is created when you install the the Pen for OS/2 component of IBM Developer Connection Device Driver Kit for OS/2 on a hard disk. The following portion of the subdirectory structure contains the information relating to the development of a device driver.

--PENTKT
     |--PENBASE
     |    |--INC
     |    \--PENDD
     |
     \--UTIL
          |--DDINST
          |--PENCAL
          \--PENTL

The subdirectories and their contents are:

PENTKT\PENBASE This subdirectory contains the device driver subcomponent modules.

PENTKT\PENBASE\INC This subdirectory contains the include and header files. These files must not be changed because the files define the interface with the system.

PENTKT\PENBASE\PENDD This subdirectory contains the device-dependent code and the PENDD.SYS load module for the sample pen device driver.

PENTKT\UTIL\DDINST This subdirectory contains the sample control files used to install a device driver. Installation Control Files provides a description of these files.

PENTKT\UTIL\PENCAL This subdirectory contains the sample code for a pen calibration program.

PENTKT\UTIL\PENTL This subdirectory contains the sample code for a tool to test and call the pen device driver.

Pen Device Driver Tool

The Pen for OS/2 component of IBM Developer Connection Device Driver Kit for OS/2 provides a test tool. This diagnostic program extracts the trace buffer and generates IOCtls. The program runs interactively or accepts commands from a file. The tool provides a means to control and query all aspects of the pen device driver, assisting in program development and in debugging of the pen device driver. It can be extended for any device-specific functions but is not intended to be shipped as part of the finished product.

There are commands for each of the IOCtls, including Category 90h Function 51h Set Unit Variable and Category 90h Function 61h Query Unit Variable, whose purposes are debugging. These commands can direct operation in the pen device driver or extract collected debug data.

There also are commands to control the format of the trace output. You can dynamically set and change the size of the trace table. Resetting the trace to empty separates future activity from past.

The following example code shows how the device driver tool can extract a trace of locator events sent to the Pen for OS/2 Device Driver Services.

c:>pentl

The tool can be started in either an OS/2 full-screen session or OS/2 window session. In this case, the tool is in interactive mode, showing that it is ready for a command by displaying a . prompt.

To display a trace, the first step is to allocate a trace buffer. By default, no trace buffer is allocated.

The command to allocate a trace buffer is stts, which stands for Set Trace Table Size, and corresponds to the Set Trace Table Size IOCtl. As in all the commands, this command is composed of the first letter of the IOCtl name. In the following example, we have allocated a trace table with 1000 DWORD entries.

.stts 1000
.

If you query the trace table before making a stroke with the pen, you see only a tick count entry:

.qtt
(tick 152)
.

This entry shows that 152 timer ticks occurred since the creation of the trace. If you query it again, you see:

.qtt
(tick 4157)
.

This means that 4157 - 152 = 4005 ticks passed between queries of the trace buffer.

After a stroke is made and you enter the commands:

.hd
.hi
.pa
.qtt

and the buffer displays the following:

(tick 7169)
(abs 8406 645 505 0)
(abs 0004 645 505 0)
(abs 0004 645 505 0)
(abs 0002 646 505 0)
(abs 0004 646 505 0)
(abs 0002 648 506 0)
(abs 0002 650 507 0)(tick 1)
(abs 0002 653 508 0)
(abs 0002 657 509 0)
(abs 0002 662 511 0)
(abs 0002 668 514 0)
(abs 0002 675 517 0)
(abs 0002 682 520 0)(tick 1)
(abs 0002 691 524 0)
(abs 0002 701 528 0)
(abs 0002 712 533 0)
(abs 0002 724 539 0)
(abs 0002 738 545 0)
(abs 0002 753 552 0)(tick 1)
(abs 0002 770 559 0)
(abs 0002 789 567 0)
(abs 0002 809 575 0)
(abs 0002 830 584   0 ) 
( abs   0002   852   594   0 ) 
( abs   0002   876   604   0 ) 
( abs   0002   900   613   0 ) ( tick   1 ) 
( abs   0002   922   623   0 ) 
( abs   0002   943   631   0 ) 
( abs   0002   975   644   0 ) 
( abs   0002   1007   656   0 ) 
( abs   0002   1042   668   0 ) 
( abs   0401   1077   680   0 ) 
( abs   0001   1113   692   0 ) ( tick   1 ) 
( abs   0001   1148   703   0 ) 
( abs   0001   1183   714   0 ) 
( abs   0001   1215   723   0 ) 
( abs   0001   1246   731   0 ) 
( abs   0001   1275   738   0 ) 
( abs   0001   1302   744   0 ) 
( abs   0001   1326   750   0 ) ( tick   1 ) 
( abs   0001   1348   754   0 ) 
( abs   0001   1370   759   0 ) 
( abs   0001   1392   763   0 ) 
( abs   0001   1414   768   0 ) ( tick   5 ) 
( abs   0081   1414   768   0 ) ( tick   54353 ) 

The PA command formats the trace with line feeds before each event packet. The HD command hides the data events and the HI command hides the interrupt events. All events reside in the trace buffer; the H commands only affect the way the trace is displayed.

The format of the trace is (abs devicebits xcoord ycoord zcoord). The abs parameter identifies the event as an absolute locator event packet. The devicebits parameter identifies mouse-emulation-button activity and proximity events. The first entry is 8406. The 8000 bit indicates enter proximity. The 0400 indicates that the state of emulated mouse button 1 has changed. This was a rapid touch-down point with no proximity points before contact. The 0006 bits indicate that emulated mouse button 1 is down and that movement occurred.

The next devicebits entries in the example with 0002 and 0004 identify a point in the stroke. The 0002 bit indicates button 1 movement, and 0004 bit indicates button down with no movement. Entry 0401 indicates the locator device was removed from the sensor. The 0400 bit indicates that the state of mouse button 1 has changed. The 0001 bit indicates mouse movement with no buttons down.

The last entry is 0081. Entry 0080 indicates an exit proximityevent. Entry 0001 indicates mouse movement with no buttons down.

The xcoord and ycoord indicate the locator position in normalized device coordinates for each point in the stroke. The zcoord is not valid for the device in the example and is always 0. The tick entries show how many sample points are being collected in each timer tick.

The tool processes five groups of commands. The first group consists of unit commands corresponding to the category 90 IOCtls. These commands are listed by typing: H U or ? U. The next group consists of locator commands and correspond to the category 92 IOCtls. These commands are listed by typing: H L or ? L. Likewise, there are a set of button commands and display commands that correspond to category 92 and 93 IOCtls listed by typing: H B or ? B and H D or ? D, respectively. The final group consists of general commands; they are listed by typing H G or ? G. All five groups of commands can be listed together by typing: H or ?.

The general commands do not correspond to IOCtls but are used to control the tool. The hide (H) and linefeed (P) commands have been discussed in the stroke events example. Trace entries are hidden with H commands and shown with S commands. Linefeeds are placed before events with the P commands and removed with the C commands. There are six types of events controlled by the H, S, P, and C commands:

I Interrupts

T Timer ticks

A Event packets

D Raw data bytes

E Error events

X Special device driver-specific events

There are also three assignment (A) commands. For convenience, the locator, button, and display commands assume a unit number for the IOCtls to the pen driver. By default, the locator is unit 1, button is unit 2, and display is unit 3. The assignment commands can change these implicit unit numbers.

Calibration Program

The Pen for OS/2 component of IBM Developer Connection Device Driver Kit for OS/2 provides a sample calibration program to supply alignment adjustments for the position of the digitizer in relation to the display panel. The program aligns the location of the pointer seen on the display to be the same as where the actual pen device touches the display.

 [Artwork not shown] 

The program provides the following functions:

OK Accept new alignment.

Align Collect alignment data and calculate adjustments used by the pen driver.

Defaults Reset the alignment adjustment to those shipped in the driver.

Test Test alignment using a target for the mouse pointer.

Cancel Restore alignment to the alignment when the program started.

Alignment data is collected by instructing the user to place the locator in the center of a target at each corner of the screen as shown in the preceding figure. The target moves to the next corner of the screen after the program has collected enough samples to get a valid position.

The program consists of two threads: a PM thread and an alignment thread. The PM thread executes in a standard PM window procedure and handles routine PM messages and messages from the alignment thread. The alignment thread processes three commands from the PM thread: (1) align; (2) cancel an alignment; and (3) terminate. The alignment thread controls the screen by sending messages to the PM thread to paint a target in a rectangle. Points in the rectangle are ignored by the PM thread but are collected by the alignment thread. Points outside the rectangle are ignored by the alignment thread but used by the PM thread to control the selection of operations through the button controls.

The calibration program can be invoked from the device object associated with it or from the command line in the following form:

--------------------------------------------------------------------------

cal driver_name device_name

--------------------------------------------------------------------------

where:

driver_name is the name of the hardware; for example, "IBM Color Workpad".

device_name is the name of the device; for example, pen.

Note:The input parameters must be put in quotes if spaces occur in the names.

When making changes to the calibration program, a debug mechanism is available. If a file named pencal.logexists, debug information is written to it. This is helpful for determining what data is being collected and used to do the calibration. Libraries and headers from Pen for OS/2 Developer's Toolkit are required to build this program.

Sample Pen Device Driver

The Pen for OS/2 component of IBM Developer Connection Device Driver Kit for OS/2 contains a sample pen device driver that uses all the Pen for OS/2 system extension interfaces and implements the semantics of all the API functions. You need only modify the device-specific sections of the example code.

You can implement the pen device driver and meet the architected interfaces in any fashion. The sample pen device driver can help you get your pen hardware product working with Pen for OS/2. It also minimizes the experience you must have in developing OS/2 device drivers and Workplace Shell objects.

The following sections give an overview of the sample pen device driver. Each subcomponent has additional information in its routine entry-point comments and module prolog comments.

Driver Organization

Pen Device Driver
/--------------------------------------------\
|    /----------------------------------\    |
|    | Device-Type-Independent Routines |    |
|    |                                  |    |
|    \----------------------------------/    |
|                                            |
| /------------------------------\           |
| | Device-Type-DISPLAY Routines |           |
| |    /------------------------------\      |
| \----| Device-Type-BUTTON Routines  |      |
|      |    /------------------------------\ |
|      \----| Device-Type-LOCATOR Routines | |
|           |                              | |
|           \------------------------------/ |
|                                            |
|    /----------------------------------\    |
|    |     Device-Dependent Routines    |    |
|    |                                  |    |
|    \----------------------------------/    |
|                                            |
\--------------------------------------------/

The sample pen device driver is organized into three types of code:

�Device-Type-Independent Code

This code provides services common to all device types and is shared, or called, by all devices in the pen device driver.

�Device-Type-Dependent Code

There are three types of device-type-dependent code, one for each of the three device types: locator, button, and display. The device-type- dependent code provides the logic to produce the behavior of the logical device type.

The device-type-independent code can call the device-type-dependent code to perform generic operations, like initializing and starting the device. The device-type-dependent code performs the operations appropriate for its device type.

�Device-Dependent Code

You must provide the device-dependent code and address the details of the particular pen hardware product. The pen hardware product device-dependent code is linked with the supplied sample pen device driver code to build the pen device driver. The device-type-dependent code calls the device- dependent code to perform operations specific to the hardware.

The device-dependent code manages the device while the device-type- dependent code produces the Pen for OS/2 device behavior.

Driver Subcomponents

The driver is further organized into multiple subcomponents, each with a specific duty as shown in the following figure.

 Pen Device Driver
/---------------------------------------------\
|  /---------------------------------------\  |
|  | Device-Type-Independent Subcomponents |  |
|  |  /-------\    /-------\    /-------\  |  |
|  |  | STRAT |    |  GIO  |    |  IDC  |  |  |
|  |  \-------/    \-------/    \-------/  |  |
|  |  /-------\    /-------\    /-------\  |  |
|  |  | INIT  |    | TRACE |    | TIMER |  |  |
|  |  \-------/    \-------/    \-------/  |  |
|  \---------------------------------------/  |
|  /---------------------------------------\  |
|  |   Locator-Device-Type Subcomponents   |  |
|  |          /----------------\           |  |
|  |          | LOCATOR ENGINE |           |  |
|  |          \----------------/           |  |
|  \---------------------------------------/  |
|  /---------------------------------------\  |
|  |   Button-Device-Type Subcomponents    |  |
|  |          /---------------\            |  |
|  |          | BUTTON ENGINE |            |  |
|  |          \---------------/            |  |
|  \---------------------------------------/  |
|  /---------------------------------------\  |
|  |   Display-Device-Type Subcomponents   |  |
|  |          /----------------\           |  |
|  |          | DISPLAY ENGINE |           |  |
|  |          \----------------/           |  |
|  \---------------------------------------/  |
|  /---------------------------------------\  |
|  | Device-Type Subcomponents             |  |
|  |                                       |  |
|  \---------------------------------------/  |
|     | DEVICE DEPENDENT |     | SERIAL |     |
|     \------------------/     \--------/     |
\---------------------------------------------/

�Device-Type-Independent Subcomponents

-STRAT

OS/2 strategy entry point. OS/2 device driver commands are handled and routed to worker routines in device-type-dependent subcomponents. Most notable are the Generic IOCtl handler and the INIT command handler.

-INIT

The OS/2 operating system issues the INIT command after loading the driver. The STRAT subcomponent routes the command to the INIT command handler routine. The INIT routine takes care of OS/2 details and calls each subcomponent's INIT entry routine. After all INIT routines are called, the declared logical device types are identified to the Pen for OS/2 system extension with the DevHlp_RegisterDeviceClass routine.

The initialization code and data segments are returned to the system after the INIT command returns to the OS/2 operating system.

-GIO

Generic IOCtl handler. Architected IOCtls are routed to a subcomponent for processing. Device-specific IOCtls are routed to the device-dependent routine.

-IDC

Inter-device-driver communication (IDC) entry points. This subcomponent processes IDC calls to the Pen for OS/2 Device Driver Services.

-TRACE

The trace subcomponent provides trace services useful for driver debugging.

-TIMER

The timer provides timer services in the form of per-tick callouts to subcomponents and the device-dependent code. Timers are used to manage the backlight and ensure that exit proximity is reported.

�Device-Type-Dependent Subcomponents

-ENGINE

There is a device-type-dependent engine subcomponent for each of the logical device types. The engine is called from the device-dependent code to process locator, button, or display operations. The engine shields the details of the Pen for OS/2 interface and calls back to the device- dependent code for hardware-specific operations.

�Device-Dependent Subcomponents

-DEVICE DEPENDENT

The device-dependent subcomponent supplies the specific hardware-handling operations.

-SERIAL

A serial subcomponent for hardware devices attached by way of a serial port .

The detailed design of each subcomponent can be found in the module prolog of the assembly file (*ASM) for that subcomponent.

Driver Data Structures

 Pen Device Driver
/----------------------------------------------------------\
|                DEVICE CONTROL BLOCK (DCB)                |
|                  /-------------------\                   |
|   DCB_anchor ----�     dcb_link      |----� Next DCB     |
|                  |-------------------|                   |
|       /----------| Device-Type       |                   |
|       |          | Independent       |  /--------------\ |
|       |          | Section      /----+--| Device-Type- | |
|       �          |              |    |  | Independent  | |
| Pointers to Data |              | /--+--| Code         | |
| Common to        |              | |  |  \--------------/ |
| All Types        |              | |  |                   |
|                  |              | |  |  /--------------\ |
|                  |              | \--+--� Device-Type- | |
|                  |--------------+----|  | Dependent    | |
|       /----------| Device-Type- | /--+--| Code         | |
|       |          | Dependent    | |  |  \--------------/ |
|       |          | Section      | |  |                   |
|       �          |              | |  |                   |
| Pointers to Data |              | |  |  /--------------\ |
| Common to this   |              | \--+--� Device-      | |
| Device Type      |              |    |  | Dependent    | |
|                  |              \----+--� Code         | |
|                  |                   |  \--------------/ |
|                  |-------------------|                   |
|       /----------| Device-           |                   |
|       |          | Dependent         |                   |
|       |          | Section           |                   |
|       �          |                   |                   |
| Pointers to Data |                   |                   |
| Private to the   |                   |                   |
| Device           |                   |                   |
|                  |                   |                   |
|                  |                   |                   |
|                  \-------------------/                   |
\----------------------------------------------------------/

The sample pen device driver has very few global variables. Each device has its own device-control block (DCB). There are three sections in each DCB, one for each of the three code organizations: device-type-independent , device-type-dependent, and device-dependent. The first two are provided with the sample pen device driver, and you must define the device-dependent section.

The DCB has data fields and pointers to data structures and routines needed by particular layers of the driver. The indirect call pointers declare device type-dependent and device-dependent routines, enabling common code to support different device types and physical devices without conditional logic and naming conventions to select a routine.

Upward calls from device-dependent code to device type-dependent code or device type-independent code, and from device type-dependent code to device type-independent code can be made by global reference.

Device-dependent routines can access the entire DCB. Device type-dependent code can access the device type-dependent and device type-independent sections, but cannot refer to the private device section because it not aware of the layout. Similarly, the device type-independent code can access only the device type-independent section of the DCB.

Data and routines provided by a lower layer in the device driver are located in the DCB section that requires the access. These fields are generic to all lower-level code and must be supported by all lower-level code.

Operational Considerations

This appendix provides operational considerations pertaining to the performance of a pen device driver.

Support Level Control

The level of Pen for OS/2 system extension support is passed to the pen device driver with the START_LOGICAL_DEVICE IDC request. The support level can be used to distinguish old versions of the Pen for OS/2 system extension with fewer capabilities and different structure layout from the expected level. The pen device driver can choose to support back levels by disabling functions and supplying the expected control block layouts, or the pen device driver can decline to register its devices.

Likewise, the pen device driver identifies its level to Pen for OS/2 in the driver-specific capabilities packet (driver unit 0 capabilities packet), so Pen for OS/2 can interpret the pen device driver's communication or can choose not to identify its Pen for OS/2 Device Driver Services.

The driver-specific capabilities packet identifies the level of the IOCtl interface, Pen for OS/2 Device Driver Service IDC interface, Pen for OS/2 extended information packet interface, and version of the pen device driver .

Configuration Limitations

A pen device driver is limited to one button and one display device. There can be four locator devices of any mix of locator types. There can be only one display device per system. Pen for OS/2 Device Driver Services will not issue START_LOGICAL_DEVICE to logical devices that would cause these limits to be exceeded.

There can be one pen device driver in the system.

Stand-Alone Operation

Pen device drivers created with the Pen for OS/2 Developer's Toolkit are not intended to be used in a system without the Pen for OS/2 system extension. The OS/2 2.1 MOUSE.SYS, without the Pen for OS/2 Device Driver Services, supports only a single device-dependent driver with a single locator device and no extended information packet. Other logical device types are not supported.

It is possible for a pen device driver to run without the Pen for OS/2 system extension. The locator Pen for OS/2 Device Driver Service interface is similar to the OS/2 2.1 MOUSE.SYS IDC interface. The MOUSE.SYS statement in the CONFIG.SYS must include a TYPE= for the pen device driver. The TYPE= in the MOUSE.SYS statement in the CONFIG.SYS must not be present on a Pen for OS/2 system if the device driver has registered with DevHlp_ RegisterDeviceClass. The pen device driver's AttachDD IDC entry point must be used for the standard MOUSE.SYS protocol. Being called at the AttachDD entry point by MOUSE.SYS can be used to determine the device driver's mode of operation. An AttachDD to MOUSE.SYS must be performed during READ_ ENABLE to locate the MOUSE.SYS IDC entry point. The MOUSE.SYS interrupt packet must be used instead of the extended information packet.

DevHlp_RegisterDeviceClass can be called on an OS/2 2.1 system without the Pen for OS/2 system extension, but it will be ignored, and the driver entry point will not be called. The Pen for OS/2 device driver is not supported in previous versions of the OS/2 operating system.

If the pen device driver has multiple locator devices, either they must share the MOUSE.SYS interrupt packet or only one device can be supported. The IDC entry point, as defined in the device driver header, must fan out the calls to all locator device entry points if the interrupt packet is shared.

There is no requirement for interrupt packet sharing, and it will require additional programming in the device driver. Supporting both interfaces might be useful if the device driver will be used on OS/2 systems without the Pen for OS/2 system extension.

Multiple Device Drivers

A pen device driver can be composed of a complex number of physical device drivers connected by private IDC calls. One driver should register on behalf of the collection of drivers. This driver will be called by the Pen for OS/2 system extension for IOCtls. The other physical device drivers are invisibleto Pen for OS/2. Pen for OS/2 Device Driver Services must be called from the device driver that registered with Pen for OS/2 Device Driver Services.

Resource Utilization

The sample pen device driver uses statically allocated memory in its device driver data segment. You can allocate dynamic memory, but this is not required by the device driver model. There will be no per-process data requirements.

Resources required by the device objects are similar to all Workplace Shell objects.

Video Mode Changes

The pen device driver can request to be informed of video mode and session changes. The ability to report these events is identified with the READ_ENABLE request. See Pen Device Driver IDC Interface. By default, events are not reported to the device driver. If events are desired, the STYLE_ NOTIFY_VMCHANGE style bit must be reset and returned by way of READ_ENABLE.

Events are reported to the pen device driver with the VIDEO_MODE_CHANGE IDC request. This is a global call to the device driver, not to a specific logical device. If the visible portion of the LCD changes for different video modes, the device driver must modify the extents to reflect the new dimensions and inform Pen for OS/2 with the capabilities update Pen for OS/ 2 Device Driver Service (UPDATE_CAPS).

Glossary

This glossary contains terms and definitions that are, for the most part, used specifically with the Pen for OS/2 products. This is not a complete dictionary of computer terms.

Introduction

This glossary includes terms and definitions from:

�The American National Dictionary for Information Systems, ANSI X3.172-1990 , copyright 1990 by the American National Standards Institute (ANSI). Copies may be purchased from the American National Standards Institute, 11 West 42 Street, New York, New York 10036. Definitions are identified by the symbol (A) after the definition.

�The Information Technology Vocabulary, developed by Subcommittee 1, Joint Technical Committee 1, of the International Organization for Standardization and the International Electrotechnical Commission (ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are identified by the symbol (I) after the definition; definitions from draft international standards, committee drafts, and working papers being developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the definition, indicating that final agreement has not yet been reached among the participating National Bodies of SC1.

Glossary Listing

Select a starting letter of glossary terms:

Glossary - A

A

American National Standard Code for Information Interchange (ASCII) -The standard code, using a coded character set consisting of 7-bit coded characters (8-bits including parity check), that is used for information interchange among data processing systems, data communication systems, and associated equipment. The ASCII set consists of control characters and graphic characters. (A)

API -Application programming interface.

application programming interface (API) -A functional interface supplied by the operating system or by a separately orderable licensed program that allows an application program written in a high-level language to use specific data or functions of the operating system or the licensed program.

ASCII -American National Standard Code for Information Interchange

ASCIIZ format -A string of ASCII characters ending with a null character.

assignment -A unique setting that can be changed. See also button assignmentand gesture assignment.

Glossary - B

B

backlight -The fluorescent lighting on a device such as a liquid crystal display (LCD).

barrel buttons -Buttons on the side of a pen device, used to request or initiate an action.

bezel buttons -Buttons built into the case (bezel) of a pen-based computer or peripheral device, used to request or initiate an action.

button -A mechanism used to request or initiate an action. See also barrel buttonsand bezel buttons.

button assignment -An assignment that defines the action or actions performed as a result of activating a button or combination of buttons.

Glossary - C

C

calibration -The adjustment of a piece of equipment so that it meets normal operational standards. For example, calibration could refer to adjusting the alignment of a pen.

call -(1) The action of bringing a computer program, a routine, or a subroutine into effect, usually by specifying the entry conditions and jumping to an entry point. (I) (A) (2) To transfer control to a procedure, program, routine, or subroutine.

cathode ray tube display (CRT display) -(1) A device that presents data in visual form by means of controlled electron beams. (A) (2) The data display produced by the device in (1). (A)

child class -See subclass.

child process -A process, started by a parent process, that shares the resources of the parent process.

class -The description of a set of objects and their behavior. New classes can be defined in terms of existing classes through a technique known as inheritance.

class method -An action that can be performed on a class object. Class methods also are called factory methods.

configure -To describe to a system the devices, optional features, and programs installed on the system.

control ball -In computer graphics, a ball, rotatable about its center, that is used as an input device, normally as a locator. (I) (A) Synonymous with track ball.

CRT display -Cathode ray tube display.

Glossary - D

D

DCB -Device control block.

debug -To detect, diagnose, and eliminate errors in programs. (T)

descendant -See subclass.

device control block (DCB) -A data structure that contains data and addresses for indirect calls for a logical device.

device driver -A program that enables the computer to communicate with a specific peripheral device such as a pen, videodisc player, or CD drive.

device helper (DevHlp) functions -Kernel services (memory, hardware interrupts, software interrupts, queuing, semaphores, and so forth) provided to physical device drivers.

device ID -A unique ID number assigned to a logical device. A device ID is unique across an entire system.

device object -An object that provides a means of communication between a computer and another piece of equipment, such as a pen or display.

digitizer -An electronic device that transmits coordinate data to software running on a computer.

display bezel -The case surrounding the display of a pen-based computer.

DLL -Dynamic link library.

double-tap -To touch a sensor twice in rapid succession within a small area.

drag -To use a pen or another pointing device to move an object.

dynamic link library (DLL) -A file containing executable code and data bound to a program at load time or run time, rather than during linking. The code and data in a dynamic link library can be shared by several applications simultaneously.

dynamic link module -A module that is linked at load time or run time.

Glossary - E

E

emulation -The use of one system to imitate another system so that the imitating system accepts the same data, runs the same programs, and achieves the same results as the imitated system.

Glossary - F

F

flag -(1) A variable indicating that a certain condition holds. (T) (2) A character that signals the occurrence of some condition, such as the end of a word. (A)

function -(1) In a programming language, a block, with or without formal parameters, whose execution is invoked by means of a call. (2) A set of related control statements that cause one or more programs to be performed.

Glossary - G

G

gesture -A hand-drawn symbol or uppercase letter which, when recognized by the system, invokes an action or a series of actions. Gestures denote an action and a target for the action.

gesture assignment -An assignment that defines the action or actions performed as a result of a gesture.

group -A collection of files that can be presented to the user as an installation option.

Glossary - H

H

header -(1) System-defined control information that precedes user data. (2 ) The portion of a message that contains control information for the message, such as one or more destination fields, name of originating station, input sequence number, character string indicating the type of message, and priority level for the message.

hot key -(1) The key combination used to change from one session to another on the workstation. (2) To jump, or hot key, from a host session to an application on the workstation, or from the workstation to the host session.

hot spot -The area of a display screen that is activated to accept user input. Synonymous with touch area.

Glossary - I

I

IDC -Inter-device-driver communication.

ink -The trail resulting from writing with the pen.

inheritance -(1) In the OS/2 Presentation Manager interface, the technique of specifying the shape and behavior of one window (called a child window) as incremental differences from another window (called a parent window). ( 2) In System Object Model, implications of derivation of new classes from existing classes. Child classes inherit methods from parent and ancestor classes.

input/output control (IOCtl) -A system service that provides a way for an application to send device-specific control commands to a device driver.

instance -A specific object belonging to a class.

instance method -Actions that can be performed on instances of class objects.

inter-device-driver communication (IDC) -A mechanism that enables a physical device driver to communicate with another physical device driver.

IOCtl -Input/output control.

Glossary - J

J

joy stick -In computer graphics, a lever that can pivot in all directions and that is used as a locator device. (T)

Glossary - K

K

kernel -The part of an operating system that performs basic functions, such as allocating hardware resources.

Glossary - L

L

LCD -Liquid crystal display.

line feed -(1) The movement of the print or display position to the corresponding position on the next line. (T) (2) The incremental relative movement between the paper carrier and the type carrier in a direction perpendicular to the writing line.

liquid crystal display (LCD) -A display device that creates characters by means of the action of reflected light on patterns formed by a liquid that becomes opaque when it is energized.

logical device -(1) A file for conducting input or output with a physical device. (2) A file for mapping user I/O between virtual and real devices. A logical device can be accessed using the file system API.

Glossary - M

M

metaclass -A class of a class. In System Object Model, a metaclass defines class methods for a class object.

method -An action that can be performed on an object.

mouse-emulation mode -An input mode in which the system interprets pen input as mouse input.

Glossary - N

N

There are no glossary terms for this initial letter.

Glossary - O

O

object -(1) A graphic symbol that a user works with to perform a task. (2) In System Object Model, a set of data and the actions that can be performed on that data.

object definition -See class.

object instance -See instance.

OEM -Original equipment manufacturer.

Original equipment manufacturer (OEM) -A manufacturer of equipment that may be marketed by another manufacturer.

Glossary - P

P

parallax -A condition that occurs when a gap exists between the locator position and the displayed trail resulting from writing with the pen. Parallax differs in both the horizontal and vertical views by how a user looks at the display.

parent class -A class from which another class inherits. See inheritance.

parent process -A process that creates other processes. Contrast with child process.

path -The part of a file specification that lists the drive name and a series of directory names that give the location of the file. Each directory name is separated by the backslash character. In the specification C:\MYFILES\MISC\GLOSSARY.SCR, the path consists of C:\MYFILES \MISC\.

pause -An action where the pen remains motionless for an interval of time while it is in the proximity zone or touching a touch-sensitive surface. This interval of time starts a new action (for example, mouse-emulation mode).

pel -Picture element.

pen -A pointing and input device used with a touch-sensitive device.

pen-aware programs -Programs that are written or modified to use a pen or a finger as the standard input device rather than a keyboard or a mouse.

pen-unaware programs -Programs that are written to use a keyboard or a mouse and are not written to use a pen.

picture element -In computer graphics, the smallest element of a display surface that can be independently assigned color and intensity. (T)

pixel -Picture element.

privilege level -A protection method supported by the hardware architecture of IBM personal computer systems. This method consists of four privilege levels know as rings (numbered 0 through 3). Only certain types of programs are allowed to execute at each privilege level.

program-file object -An object that starts a program. Program files commonly have extensions of .EXE, .COM, .CMD, or .BAT.

program object -An object representing the file that starts a program. A user can change the settings for a program object to specify the gesture assignments for a particular program.

proximity zone -An area where action is sensed by a touch-sensitive device without the input device touching the touch-sensitive surface. The zone varies depending on the technology of the digitizer in the device, but it is usually no more than 6.35 mm (0.25 in.) from the surface.

Glossary - Q

Q

There are no glossary terms for this initial letter.

Glossary - R

R

return code -(1) A code used to influence the execution of succeeding instructions. (2) A value returned to a program to indicate the results of an operation requested by that program.

ring level -See privilege level.

Glossary - S

S

screen -The physical surface of a display device upon which information is shown to a user.

settings -Characteristics of objects that the user can view and sometimes alter.

shift -An action during mouse-emulation mode in which the default mouse button 1 downaction emulates another button or combination of buttons for the duration of the stroke.

shutdown -The procedure required before the computer is switched off to ensure that data is not lost.

SOM -System Object Model.

source directory -The directory from which information is read. Contrast with target directory.

stroke -The collection of points between the point where the pen touches a touch-sensitive surface and the point where the pen is removed from the surface.

subclass -A class that is derived from another class. The subclass inherits the data and methods from the parent class and can define new methods or override existing methods to define new behavior not inherited from the parent class. See inheritance.

System Object Model -A mechanism for language-neutral, object-oriented programming for the OS/2 environment.

Glossary - T

T

tap -To briefly touch a touch-sensitive surface with a pointing device and then quickly remove it.

target -The location to which the information is destined.

target directory -The directory to which information is written. Contrast with source directory.

tick count -A value registered with the Pen for OS/2 extension that causes the Pen for OS/2 timer handler to be called on every ntimer ticks instead of every timer tick.

toggle -To switch between two modes; for example, to switch between selected and deselected mode.

touch area -Synonym for hot spot.

touch-down point -Location, plotted by a digitizer, on screen where contact is made with touch-sensitive surface.

touch screen -A display device that allows the user to interact with a computer system by touching an area on its screen.

touch-sensitive -Pertaining to a device such as a keypad or screen that generates coordinate data when a pointing device approaches or contacts the surface, thereby allowing a user to interact directly with a computer without entering commands from a keyboard.

track ball -Synonym for control ball.

Glossary - U

U

unit number -A number used by a device driver to select a specific logical device. A unit number is unique only within the scope of the driver.

Glossary - V

V

VGA -Video graphics array.

Glossary - W

W

window -An area of the screen with visible boundaries within which information is displayed. A window can be smaller than or the same size as the screen. Windows can appear to overlap on the screen.

window class -The grouping of windows whose processing requirements conform to the services provided by one window procedure.

Glossary - X

X

There are no glossary terms for this initial letter.

Glossary - Y

Y

There are no glossary terms for this initial letter.

Glossary - Z

Z

There are no glossary terms for this initial letter.

Trademarks

Trademark of the Microsoft Corporation.

'Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation'