Input/Output Device Driver Reference

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

About This Book

The Input/Output Device Driver Reference for OS/2 contains specific character device drivers that are shipped with OS/2. A generic discussion of character and block device drivers can be found in the Physical Device Driver Reference for OS/2 and the Storage Device Driver Reference for OS/2.

How This Book is Organized

Advanced Power Management Architecture describes the Advanced Power Management specification, a component of the OS/2 operating system that is used to manage power (AC/DC) consumption and utilization for PC systems.

APM IOCtl Device Driver Test Tool explains the test tool and its various test cases.

Asynchronous (RS232-C) Communications Device Driver presents the physical asynchronous (RS232-C) communications device driver and describes how it enables OS/2 applications to utilize the RS232-C device hardware.

CLOCK$ Device Driver describes the physical clock device driver.

Joystick Device Driver describes the Advanced OS/2 Joystick Device Driver.

Keyboard Device Driver describes the KBD$ (device-independent) driver.

Keyboard Inter-Device-Driver Communication Interfaces describes the IBMKBD (device-dependent) driver.

Keyboard Device Driver Test Tool describes how to use the keyboard Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of keyboard device drivers.

Mouse Device Driver describes a physical mouse device driver (MOUSE.SYS) whose job it is to detect the types of pointing devices currently installed on the OS/2 operating system. When a pointing device is identified, support for it is set up dynamically.

Mouse (DOS) Device Driver Test Tool describes how to use the mouse Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of mouse device drivers.

Parallel Port Device Driver describes the parallel port device driver, which supports the parallel port device interface for OS/2, Versions 2.0 and later.

Physical Bidirectional Parallel Port Device Driver describes the function the new PAR1284.SYS device driver provides.

Parallel Port Device Driver Test Tool describes how to use the parallel port Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of parallel port device drivers.

PCMCIA Architecture contains a description of the PCMCIA architecture as it applies to the OS/2 operating system. Also included is a list of the supported functions and information on deviations from the PCMCIA standard.

PCMCIA Socket Services Device Driver Test Tool describes how to use the PCMCIA Functional Verification Tests (FVTs) that exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of PCMCIA device drivers.

Touch Display Device Driver introduces and describes the IBM Touch Display device driver, which, in addition to the video cable connection to a VGA/ XGA port, has a touch data cable that attaches to the IBM PS/2 Mouse (pointing device) port on the system unit. OS/2 protect-mode and DOS real-mode applications are supported by the touch component.

Touch Inter-Device-Driver Communication Interfaces describes the IBM interfaces for the Touch Display device driver.

USB Device Driver Stack for OS/2 Warp briefly describes OS/2 USB stack implementation and gives guidelines for host controller driver and class/client driver implementation together with stack driver communication API specification.

Notices contains legal notices and lists the trademarks of the IBM Corporation and trademarks of other companies.

A glossary and an index are included at the back of this book.

Conventions

Double-Byte Character Set

Throughout this publication, there are references to specific values for character strings. These values are for the Single-Byte Character Set (SBCS). When using the Double-Byte Character Set, note that one DBCS character equals two SBCS characters.

Version

Unless otherwise stated, "OS/2" as used in this book refers to the Warp Version of the IBM Operating System/2.

Assistance

Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS). You are encouraged to use the DDSC 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 DDSC BBS, 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

In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, it 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)

What's New

A new chapter, #APM IOCtl Device Driver Test Tool is provided. This chapter explains the Advanced Power Management test tool.

A new chapter, #Physical Bidirectional Parallel Port Device Driver was added which describes the PAR1284.SYS device driver.

For information on any items discussed in this reference that have been added to OS/2 beginning with OS/2 Warp Version 3.0 and their compatibility with different versions of OS/2, see #OS/2 Version Compatibility Considerations.

Introduction

Device drivers are software modules that act as an interface between OS/2 (or its applications) and physical devices. In DOS, applications are responsible for knowing and managing all the differences between different devices of like types. The device drivers of OS/2 enable applications to focus on the logic of the actual application and treat devices in a device-independent way.

This device-independence is a fundamental benefit of the OS/2 programming environment. For example, drawing a circle on the screen or on a printer is as easy as opening a device context for the correct output device and performing the drawing operations. By placing the drawing operation into the device context, the programmer does not have to be concerned about whether the device is a printer or a display.

Types of OS/2 Device Drivers

Three types of device drivers are used in OS/2 Version 3:

Physical device drivers
Virtual device drivers
Presentation drivers

Physical Device Drivers

Physical device drivers, in most cases, resolve device-independent input and output (I/O) requests from the operating system and its applications with the device-dependent physical attributes of the device. The physical device drivers shipped with OS/2 Version 3 include support for the following:

Advanced Power Management
Asynchronous Communication (RS-232C)
CD-ROM
Hard Disk and Diskette
Keyboard
Mouse
Parallel Port Printer
PCMCIA
System Clock
Touch Screen
Video

Virtual Device Drivers

The virtual device driver is an installable module that virtualizes a particular piece of hardware and associated ROM BIOS in the manner expected by a DOS application. This device driver achieves virtualization by emulating I/O port and device memory operations. Virtual device drivers are 32-bit device drivers that operate at Ring 0. To achieve a certain level of hardware independence, a virtual device driver usually communicates with a physical device driver in order to interact with hardware.

Further information on virtual device drivers, virtual device driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Virtual Device Driver Reference.

Presentation Drivers

The Presentation Manager* I/O interface for output devices is a high-level interface. This interface is similar to the API call interface, which uses the program stack to communicate with, or pass parameters to, the presentation drivers. These drivers are special purpose I/O routines operating with I/O privilege at privilege level 2 (Ring 2) or level 3 (Ring 3). Their main function is to process function calls made by the Presentation Manager interface on behalf of Presentation Manager applications. Hardcopy presentation drivers communicate with OS/2 device drivers through the file system emulation functions. Display presentation drivers interface directly with the hardware.

Presentation drivers are dynamic link library modules that are supplied as files and identified by the extension DRV. When the Presentation Manager interface is initialized, the display presentation driver is loaded and enabled automatically. Other presentation drivers (for example, the hardcopy presentation drivers) are loaded and enabled when an application calls the DevOpenDC function to open the device.

Presentation drivers service requests only from applications running in Presentation Manager sessions in the OS/2 mode. Output data and requests for information are passed to the presentation driver as function calls to the presentation driver interface. The definition of the call interface is given in terms of the codes and data passed to the presentation driver interface through the program stack.

Header and include files are shipped with OS/2 to provide support for building presentation drivers that are written in C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions. Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Presentation Device Driver Reference.

Keyboard Inter-Device-Driver Communication Interfaces

This chapter describes the inter-device-driver communication (IDC) interfaces for the IBM keyboard device drivers provided by the OS/2 operating system - both device-independent to device-dependent and device-dependent to device-independent.

The division of the keyboard device driver has allowed new functions to be included that were not previously available. These functions are found in the following IDC functions.

Note: If an independent-device driver changes the state of one of the drivers by making an IDC call, it is not always reflected in the other driver. For example, if a driver changes the state of the LEDs in the device-dependent (DD) driver, the change will not be reflected in the device-independent (DI) driver and the device-independent driver might change the LEDs to another state at any time.

Device-Independent Supplied IDC's

The following are the device-independent IDC functions.

Note: For compatibility purposes, the data segment should not be changed by the dependent-device driver. The device-independent driver will load up the correct data segment required.

The following are the device-independent IDC functions that are currently available.

00 Open

01 Close

02 Process Keystroke

03 Process Reinit

04 Pen Functions

Open

This function registers the device-dependent driver with the device-independent driver. The independent-device driver will use this registry to notify device-dependent drivers of updates (such as LED, type rate/delay, and so on). If a driver does not want to be notified of updates, then it sends in a 0000h Code Segment value.

Input:

 Func: Open_IDC code (0000h)
 Var1: Code Offset of DD IDC routine
 Var2: Data Segment of DD Driver
 Var3: Code Segment of DD IDC routine

Output:

AX = Handle (0FFFFh=error, could not open)

Close

This function deletes the driver from the registry.

Input:

 Func: Close_IDC code (0001h)
 Var1: NULL
 Var2: Data Segment of DD Driver
 Var3: Handle from Open Call

Output:

If the handle or data segment are incorrect, AX=0FFFFh is returned.

Process Keystroke

This function is called by the device-dependent driver when it has a complete keystroke to report to the device-independent driver. The buffer may be reused immediately after this call.

Input:

 Func: Process_Keystroke code (0002h)
 Var1: Data Offset of keystroke buffer
 Var2: Data Segment of keystroke buffer and DD Driver
 Var3: Handle from Open Call

Output:

If the handle or data segment are incorrect, AX=0FFFFh is returned.

Process Reinit

This IDC informs the device-independent driver that a reinit/hot-plug condition has occurred. The device-independent driver now checks the attached keyboard type (and all that a keyboard change entails), and resends the appropriate LED state to the device-dependent driver.

Input:

 Func: Process_Reinit Code (0003h)
 Var1: NULL
 Var2: Data Segment of DD Driver
 Var3: Handle from Open call

Output:

If the handle or data segment are incorrect, AX=0FFFFh is returned.

Pen Functions

This function allows the keyboard device driver to create system keyboard events on behalf of the Pen for OS/2 subsystem.

Input:

 Func: Pen_Functions code (04XXh)
 Var1: Index to SINFO data structure
 Var2: Data Segment
 Var3: Internal Pen function variable

Output:

Carry set if error occurs.

Device-Dependent Supplied IDC's

The following are the device-dependent IDC functions.

00 Open

01 Close

02 Query Capabilities

03 Query Typematic & Delay

04 Query LEDs

05 Query ID codes

06 Query Disabled

07 Disable Keyboard

08 Enable Keyboard

09 Reset Hardware

0A Set Typematic & Delay

0B Set LEDs

0E Send Generic Command

0F Query Keyboard Ready

10 Flush Partial Keys

12 Save State

13 Restore State

87 Disable Keyboard (Interrupt Time)

88 Enable Keyboard (Interrupt Time)

89 Reset Hardware (Interrupt Time)

8A Set Typematic & Delay (Interrupt Time)

8B Set LEDs (Interrupt Time)

Open

The open function is not a prerequisite for implementing other functions within this device driver.

Input:

     Func: Open Device Driver code (0000h)
     Var1: NULL
     Var2: NULL

Output:

     AX = 0:  Keyboard is ready for any command.
     0FFFFh:  Keyboard is busy.  OK to query, but thread will be
                    blocked or unexecuted (if interrupt time) if an
                    attempt is made to send a command to the keyboard
                    hardware.

Close

This function is null and is used for compatibility purposes only.

Input:

     Func: Close Device Driver code (0001h)
     Var1: NULL
     Var2: NULL

Output:

None.

Query Capabilities

This request is issued by the device-independent driver to find out what capabilities the attached driver has.

Input:

     Func: Query_Capabilities code (0002h)
     Var1: CapStruc buffer address offset
     Var2: CapStruc buffer address segment

Output:

     AX = 0 (and structure is filled in)

struct CapStruc {
     USHORT  DevFlags;
     USHORT  KeyCount;
     USHORT  MaxTypa;
     USHORT  MinTypa;
     USHORT  MaxDelay;
     USHORT  MinDelay;
}

     Device Flags:  0000 0000 0ccc 00ba
                                 │   ││
                                 │   │└─ True Keyboard
                                 │   └── Hotplug Detection
                                 └───── Number of LEDs (0-7)
     Device Flags:  0000 0000 0ccc 00ba
                                 │   ││
                                 │   │└─ True Keyboard
                                 │   └── Hotplug Detection
                                 └───── Number of LEDs (0-7)

Query Typematic Rate and Delay

This function queries the current type rate and delay of the keyboard hardware.

Input:

     Func: Query_Typematic code (0003h)
     Var1: NULL
     Var2: NULL

Output:

     AX = Bits 15-7 -> Reserved
          Bits 6-5  -> Delay value in milliseconds
                        (values in binary)
                        00 - 250
                        01 - 500
                        10 - 750
                        11 - 1000
          Bits 4-0  -> Rate value in characters per second
                          (values in binary)
                          00000 - 30.0         10000 - 7.5
                          00001 - 26.7         10001 - 6.7
                          00010 - 24.0         10010 - 6.0
                          00011 - 21.8         10011 - 5.5
                          00100 - 20.0         10100 - 5.0
                          00101 - 18.5         10101 - 4.6
                          00110 - 17.1         10110 - 4.3
                          00111 - 16.0         10111 - 4.0
                          01000 - 15.0         11000 - 3.7
                          01001 - 13.3         11001 - 3.3
                          01010 - 12.0         11010 - 3.0
                          01011 - 10.9         11011 - 2.7
                          01100 - 10.0         11100 - 2.5
                          01101 - 9.2          11101 - 2.3
                          01110 - 8.6          11110 - 2.1
                          01111 - 8.0          11111 - 2.0

Query LEDs

This function queries the current LED state of the keyboard hardware.

Input:

     Func: Query_LEDs code (0004h)
     Var1: NULL
     Var2: NULL

Output:

     AX = Bits 15 to  3 - Reserved
          Bit 2         - CapsLock
          Bit 1         - NumLock
          Bit 0         - ScrollLock

Query ID Codes

This function queries the current ID of the keyboard hardware.

Input:

     Func: Query_ID (0005h)
     Var1: IDstruc buffer address offset
     Var2: IDstruc buffer address segment

Output:

     AX = key count (88/101/122/etc), 0=undetermined (IDstruc buffer is
filled in, also).

struc IDstruc {
     USHORT idlen;          /* length of returned ID code        */
     UCHAR idbytes[8];      /* buffer for ID bytes               */
 }

Query Disabled

This function queries if the keyboard hardware is disabled.

Input:

     Func: Query_Disabled (0006h)
     Var1: NULL
     Var2: NULL

Output:

     AX = Disabled Flag (0 enabled, 0FFFFh disabled)

Disable Keyboard

This function disables the keyboard and does not allow keystrokes to be accepted.

Input:

     Func: Disable_Keyboard (0007h)+[Interrupt Time +80h]

     Var1: NULL
     Var2: NULL

Output:

     AX = Disable Function (0 was already disabled, 1 disabled)

Enable Keyboard

This function enables the keyboard and allows keystrokes to be accepted.

Input:

     Func: Enable_Keyboard (0008h)+[Interrupt Time +80h]
     Var1: NULL
     Var2: NULL

Output:

     AX=0FFFFh if error occurs.

Reset Hardware

This function is issued when the device-independent portion wants to place the physical hardware into a known, reset state. This call should reset the physical keyboard and the attaching device (Kbd section of 8042).

Input:

     Func: Reset_Hardware (0009h)+[Interrupt Time +80h]
     Var1: NULL
     Var2: NULL

Output:

     AX=0FFFFh if error occurs.

Set Typematic Rate and Delay

This function sets the keyboard hardware to a specified type rate and delay.

Input:

     Func: Set_Typematic code (000Ah)+[Interrupt Time +80h]
     Var1: Parameter word
     Var2: NULL

Parameter word:
     AX = Bits 15-7 -> Reserved (must be set to zero)
          Bits 6-5  -> Delay value in milliseconds
                        (values in binary)
                        00 - 250
                        01 - 500
                        10 - 750
                        11 - 1000
          Bits 4-0  -> Rate value in characters per second
                          (values in binary)
                          00000 - 30.0         10000 - 7.5
                          00001 - 26.7         10001 - 6.7
                          00010 - 24.0         10010 - 6.0
                          00011 - 21.8         10011 - 5.5
                          00100 - 20.0         10100 - 5.0
                          00101 - 18.5         10101 - 4.6
                          00110 - 17.1         10110 - 4.3
                          00111 - 16.0         10111 - 4.0
                          01000 - 15.0         11000 - 3.7
                          01001 - 13.3         11001 - 3.3
                          01010 - 12.0         11010 - 3.0
                          01011 - 10.9         11011 - 2.7
                          01100 - 10.0         11100 - 2.5
                          01101 - 9.2          11101 - 2.3
                          01110 - 8.6          11110 - 2.1
                          01111 - 8.0          11111 - 2.0

Output:

     AX=0FFFFh if error occurs.

Set LEDs

This function sets the state of the keyboard LEDs. Bits 0-2 must set the LEDs labeled below. The other bits of BL are reserved for future support of keyboards with greater LED counts.

Input:

     Func: Set_LEDs code (000Bh)+[Interrupt Time +80h]
     Var1: Parameter word
     Var2: NULL

Parameter word:
          bit 15 - bit  3 - Reserved
                   bit  2 - CapsLock
                   bit  1 - NumLock
                   bit  0 - ScrollLock

Output:

     AX=0FFFFh if error occurs.

Send Generic Command

This function will send any command to the keyboard.

Input:

     Func: Send_Generic code (000Eh)
     Var1: CmdStruc buffer address offset
     Var2: CmdStruc buffer address segment

struc CmdStruc {
     USHORT wait;             /* 1 wait for ACK between bytes, 0 no wait   */
     USHORT strlen;           /* length of following string                */
     UCHAR bytes[strlen];     /* string of bytes to send to keyboard       */
}

Output:

     AX=0FFFFh if error occurs.

Query Keyboard Ready

This function determines if the keyboard is currently executing a command or ready for input.

Input:

     Func: Query_Kbd_Rdy code (000Fh)
     Var1: NULL
     Var2: NULL

Output:

     AX = Ready Flag (0=No, 0FFFFh=Yes)

Flush Partial Keys

This request instructs the device-dependent keyboard driver to flush any partial keys it has accumulated and return to a quiescent state. Because most physical drivers will be implemented using a finite state machine, this is a forced transition to the start state.

Input:

     Func: Flush_Partial code (0010h)
     Var1: NULL
     Var2: NULL

Output:

     AX=0.

Save State

This function informs device-dependent drivers to save all hardware state information for a later time. This function is used for Advanced Power Management (APM) support.

Input:

     Func: Save_State code (0012h)
     Var1: NULL
     Var2: NULL

Output:

     AX=0FFFFh if error occurs.

Restore State

This function restores all hardware state information from the last save. If a Save State has not receded this call, the keyboard defaults to no LEDs lit, and a 0 type rate and delay. This function is used for Advanced Power Management (APM) support.

Input:

     Func: Save_State code (0013h)
     Var1: NULL
     Var2: NULL

Output:

AX=0FFFFh if error occurs.

Keyboard Device Driver Test Tool

This chapter explains how to use the keyboard Device Driver Test Tool.

Overview

The keyboard Functional Verification Tests (FVTs) exercise the Inter-Device-Driver Communication (IDC)interfaces defined for the keyboard device drivers. The tests are implemented with the Device Driver Test Tool (DDTT) and a test device driver (TEST KBD.SYS). Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. The test scripts give the user a repeatable set of tests that demonstrate keyboard function and performance. Errors are reported and isolated to a specific test sequence and API.

User input and output from each keyboard test is performed by way of a separate Presentation Manager window. Test cases log all information to a log files, clearly indicating the actual execution sequence in the event of errors.

Keyboard Test Architecture

The DDTT provides a common front-end parser for test-case scripts and also tests several devices and APIs. The following DDTT keyboard-specific files are required:

DDTKBD.DLL
KBD.GRA
TESTKBD.SYS

The C++ source code for DDTKWD.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc.

The following required, common components of the DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE:

DDTT.EXE
DDTT.DLL
GLOBAL.DLL
GLOBAL.GRA

Installation

There are two directory structures utilizing test suites in the IBM Developer Connection Device Driver Kit for OS/2. The TESTCERT substructure contains the executables and test cases; the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL.

The following procedure describes installation for running test cases:

Copy the executable and parallel port test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TESTKBD. Test case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TESTKBD and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the parallel port test suite:
[C:\]md testkbd [C:\]cd testkbd [C:\testkbd]copy e:\ddk_x86\testcert\inputout\function\keyboard\* [C:\testkbd]copy e:\ddk_x86\testcert\general\ddtt\*
Add C:\TESTKBD to the LIBPATH and PATH in the CONFIG.SYS file.
To install the device driver, edit your system's CONFIG.SYS file and add the following line:
DEVICE=c:\testkbd\testkbd.sys
Reboot your machine so the new LIBPATH entry and DEVICE statement take effect.

Test Case-Execution

To run one script file at a time, refer to #Description of Test Cases for a description of each script file. Then, after determining which script file to run, type in DDTT followed by the script file name:

 [C:\TESTKBD]DDTT QUERY.SCR

After the script has finished executing, CONTROL will transfer back to the OS/2 Window.

KBDDD.SYS Test Grammar Function Calls

The following is a list of the KBDDD.SYS Test Grammar Function Calls:

KBD_OPEN
KBD_CLOSE
KBD_QUERY_CAPS
KBD_QUERY_TYPEMATIC
KBD_QUERY_LEDS
KBD_QUERY_IDS
KBD_QUERY_DISABLED
KBD_SEND_CMD
KBD_FLUSH
KBD_SAVE_STATE
KBD_RESTORE_STATE
KBD_DISABLE and KBD_DISABLE_I
KBD_ENABLE and KBD_ENABLE_I
KBD_RESET and KBD_RESET_I
KBD_OPEN_DI
KBD_CLOSE_DI
KBD_PROCESS_KEY
KBD_PROCESS_REINIT
KBD_PRINT_LAST_IDC

KBD_OPEN

This function opens the TESTKBD.SYS device driver and sends an open IDC to IBMKBD.SYS.

Input Parameter Keywords

None.

Output Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Logged Data

None.

KBD_CLOSE

This function sends a close IDC to KBDDD.SYS and closes the TESTKBD.SYS device driver.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

None.

Logged Data

None.

KBD_QUERY_CAPS

This function queries the capabilities of the keyboard.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

Keyword	Type	Description
MAXTYPA	NUM	Max typematic rate selector (0-31)
MINTYPA	NUM	Min typematic rate selector (0-31)
MAXDELAY	NUM	Max delay value selector (0-3)
MINDELAY	NUM	Min delay value selector (0-3)
KEYCOUNT	NUM	Number of keys
NUMLEDS	NUM	Number of LEDs

Logged Data: Max typematic rate selector (0-31); Min typematic rate selector (0-31); Max delay value selector (0-3); Min delay value selector (0-3); Number of keys; Number of LEDs; (No) Hotplug Detection; (Not) True keyboard

KBD_QUERY_TYPEMATIC

This function queries the current typematic rate and delay of the keyboard.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

Keyword	Type	Description
TYPASEL	NUM	Typematic rate selector (0-31)
DELAYSEL	NUM	Delay value selector (0-3)

Logged Data: Typematic rate selector (0-31); Delay value selector (0-3)

KBD_QUERY_LEDS

This function queries to determine which LEDs are lit.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

None.

Logged Data: Scroll Lock is ON/OFF; Num Lock is ON/OFF; Caps Lock is ON/OFF

KBD_QUERY_IDS

This function queries the ID value and keycount of the keyboard.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

Keyword	Type	Description
KEYCOUNT	NUM	Number of keys
ID	NUM	ID code for keyboard hardware

Logged Data: Number of keys; ID code for keyboard hardware

KBD_QUERY_DISABLED

This function queries to determine if the keyboard has been disabled.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

None.

Logged Data

Keyboard enabled or disabled

KBD_QUERY_READY

This function queries whether the keyboard is ready.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

None.

Logged Data

Keyboard ready or not ready

KBD_SEND_CMD

This function sends a generic command to the keyboard.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS
COMMAND	STRING	Command string
ACK	NUM	Nonzero if acknowledgement is required

Output Parameter Keywords

None.

Logged Data

None.

KBD_FLUSH

This function flushes partial keystrokes and returns the keyboard to a start state.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

None.

Logged Data

None.

KBD_SAVE_STATE

This function saves the keyboard state and is used by the Advanced Power Management System.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

None.

Logged Data

None.

KBD_RESTORE_STATE

This function restores the keyboard's saved state. This function is used by the Advanced Power Management System.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

None.

Logged Data

None.

Paired Functions

The following functions are paired according to interrupt-mode processing and non-interrupt mode processing. If the function is an interrupt-mode function, it has a _I suffix. The functionality of the pairs of functions is identical whether the _I suffix is there or not.

KBD_DISABLE and KBD_DISABLE_I

These functions disable the keyboard.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

None.

Logged Data

None.

KBD_ENABLE and KBD_ENABLE_I

These functions enable the keyboard.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

None.

Logged Data

None.

KBD_RESET and KBD_RESET_I

These functions reset the keyboard.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS

Output Parameter Keywords

None.

Logged Data

None.

KBD_SET_TYPEMATIC and KBD_SET_TYPEMATIC_I

These functions set the typematic rate and delay of the keyboard.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS
TYPASEL	NUM	Typematic rate selector (0-31)
DELAYSEL	NUM	Delay value selector (0-3)

Output Parameter Keywords

None.

Logged Data

None.

KBD_SET_LEDS and KBD_SET_LEDS_I

These functions set the LEDs.

Input Parameter Keywords

Keyword	Type	Description
HANDLE	NUM	Handle for TESTKBD.SYS
LEDS	NUM	THE LEDS KEYWORD IS A 3-BIT BINARY NUMBER, where: Bit 0 = Scroll Lock Bit 1 = Num Lock Bit 2 = Caps Lock

Output Parameter Keywords

None.

Logged Data

None.

Description of Test Cases

Each of the keyboard test cases can be executed individually as previously described. The corresponding test scripts are described below. The user can create additional tests or combine tests into multi-threaded test cases after becoming familiar with the DDTT and the keyboard grammar files.

All test scripts close the channels opened to the keyboard device and verify successful status returns from every exercised API. All test scripts log information to a log file with the same file name and a file name extension .LOG. When current status is queried (for example, track, channel, or drive), this data is written to the DDTT's output windows and to the log file. Log files can be examined after the test case has been completed.

INTERACT.SCR Human interaction script - This script tests the enable/ disable feature of the keyboard driver. When the keyboard is disabled, the user is asked to type at a prompt. If the disable is successful, the keyboard re-enables after a timeout of five seconds.

SET.SCR LED and Typematic selection script - This script sets the typematic rate and delay, as well as playing with the LEDs. It allows the user to verify that the rate and delay have been changed by allowing typing at the prompt. If no input is received, the prompt times out after 10 seconds.

QUERY.SCR This is a multi-threaded test that attempts to run some IDCs in parallel.

Mouse (DOS) Device Driver Test Tool

This chapter explains how to use the mouse (DOS) Device Driver Test Tool.

Overview

The mouse Functional Verification Tests (FVTs) exercise the Int86() DOS interface for mouse functions. The tests are implemented with a special variation of the Device Driver Test Tool (called DOSMOUSE), which uses much of the Device Driver Test Tool code; however, DOSMOUSE does not use the multithread capability. Specific mouse function code is included in the DOSMOUSE.EXE, not in a DLL, as is it done for the DDTT running in OS/2.

These tests run in a DOS window. Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. The test scripts give the user a repeatable set of tests that demonstrate mouse functions.

Test cases log all information to a log file, clearly indicating the actual execution sequence.

Mouse Test Architecture

DOSMOUSE uses the DDTT common front-end parser code for test case scripts. DOSMOUSE is specific to test mouse functions. The mouse grammar file is required:

DOSMOUSE.EXE
MOUSE.GRA.

The following required, common component of the DDTT allows use of the DDTT's common test functions such as SET, LOOP, and PAUSE:

GLOBAL.GRA

Installation

The mouse test files reside on the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc. These files utilize the test suites in the TESTCERT substructure, which also contain the executables and test cases.

The following procedure describes the installation process for running test cases:

1. Copy the executable and mouse test case files from the IBM Developer Connection Device Driver Kit for OS/2CD-ROM disc to the hard drive. The executable (DOSMOUSE.EXE) files can reside in one directory (for example, \MOUSE). Test case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\MOUSE and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the mouse test suite:

 [C:\]md mouse
 [C:\]cd mouse
 [C:\mouse]copy e:\ddk_x86\testcert\inputout\function\mouse\*
 [C:\mouse]copy e:\ddk_x86\testcert\general\ddtt\GLOBAL.GRA

Test Case Execution

To run one script file at a time, refer to #Description of Test Cases for a description of each script file. Then, after determining which script file to run, type in DOSMOUSE followed by the script file name:

[C:\MOUSE]DOSMOUSE ALL.SCR

After the script has finished executing, control will transfer back to the DOS window. Results are logged in the file identified following the @THREAD line.

DDTT Mouse Test Grammar Function Calls

The following is a list of the DDTT Parallel Port Test Grammar Function Calls:

MOUSE_RESETANDSTATUS
MOUSE_SHOWCURSOR
MOUSE_HIDECURSOR
MOUSE_GETBUTTONMPOS
MOUSE_SETCURPOS
MOUSE_GETBPRESS
MOUSE_GETBRELEASE
MOUSE_SETMINMAXHCPOS
MOUSE_SETMINMAXVCPOS
MOUSE_READMCOUNT
MOUSE_GETDRVVERTYPIRQ
MOUSE_GETGENINFO
MOUSE_GETMAXVCOOR
MOUSE_GETCURMSKMCNT
MOUSE_GETCURHSPT
MOUSE_HDWRESET
MOUSE_SETGETBPT
MOUSE_GETMINMAX
MOUSE_GETADVFCN
MOUSE_GETSWSET

MOUSE_RESETANDSTATUS

Mouse Function 0

This function returns the current status of the mouse hardware and software.

Input Parameter Keywords: None.
Output Parameter Keywords: None.
Logged Data: M1% Mouse status (found and reset = -1, otherwise = 0)
M2% Number of buttons (if mouse found and reset = 2)

MOUSE_SHOWCURSOR

Mouse Function 1

This function increments the internal cursor flag and if the value of the flag is 0, displays the cursor on the screen.

Input Parameter Keywords: None.
Output Parameter Keywords: None.
Logged Data: None.

MOUSE_HIDECURSOR

Mouse Function 2

This function removes the cursor from the screen, decrements the internal cursor flag, and hides the cursor. The mouse driver continues to track the motion of the mouse, changing the cursor's position as the mouse changes position.

Input Parameter Keywords: None.
Output Parameter Keywords: None.
Logged Data: None.

MOUSE_GETBUTTONMPOS

Mouse Function 3

This function returns the state of the left-hand and right-hand mouse buttons and also returns the state of the cursor's horizontal and vertical virtual screen coordinates.

Input Parameter Keywords: None.
Output Parameter Keywords: None.
Logged Data: Button status
Horizontal cursor coordinates
Vertical cursor coordinates

MOUSE_SETCURPOS

Mouse Function 4

This function sets the cursor position at the location of the specified horizontal vertical virtual coordinates.

Input Parameter Keywords

Keyword	Type	Description
HORIZC	NUM	Horizontal cursor coordinate
VERTC	NUM	Vertical cursor coordinates

Output Parameter Keywords: None.

Logged Data: None.

MOUSE_GETBPRESS

Mouse Function 5

This function returns the current status of both buttons, counts the number of times the specified button was pressed since the last call to this function, and reports the cursor's horizontal and vertical coordinates the last time the specified button was pressed.

Input Parameter Keywords

Keyword	Type	Description
BUTTON	NUM	Left hand button=0 or right hand button =1

Output Parameter Keywords: None.

Logged Data: Button status; Number of button presses; Horizontal coordinate; Vertical coordinate

MOUSE_GETBRELEASE

Mouse Function 6

This function returns the current status of both buttons, counts the number of times the specified button was released since the last call to this function, and reports the cursor's horizontal and vertical coordinates the last time the specified button was released.

Input Parameter Keywords

Keyword	Type	Description
BUTTON	NUM	Left hand button=0 or right hand button =1

Output Parameter Keywords: None.

Logged Data: Button status Button releases; Horizontal coordinate; Vertical coordinate

MOUSE_SETMINMAXHCPOS

Mouse Function 7

This function sets the position of the minimum and maximum horizontal cursor coordinates on the screen.

Input Parameter Keywords

Keyword	Type	Description
HMIN	NUM	Horizontal minimum position
HMAX	NUM	Horizontal maximum position

Output Parameter Keywords: None.

Logged Data: None.

MOUSE_SETMINMAXVCPOS

Mouse Function 8

This function sets the position of the minimum and maximum vertical cursor coordinates on the screen.

Input Parameter Keywords

Keyword	Type	Description
VMIN	NUM	Vertical minimum position
VMAX	NUM	Vertical maximum position

Output Parameter Keywords: None.

Logged Data: None.

MOUSE_READMCOUNT

Mouse Function 11

This function returns the horizontal and vertical mickey counts since the last call of this function.

Input Parameter Keywords

None.

Output Parameter Keywords: None.

Logged Data: Horizontal mickey count; Vertical mickey count

MOUSE_GETDRVVERTYPIRQ

Mouse Function 36

This function returns the version number of the mouse driver, reports the type of mouse the driver requires, and returns the number of the interrupt request type (IRQ).

Input Parameter Keywords: None.
Output Parameter Keywords: None.

Logged Data: Major version; Minor version; Mouse type; IRQ number

MOUSE_GETGENINFO

Mouse Function 37

This function returns general information about the mouse.

Input Parameter Keywords: None.
Output Parameter Keywords: None.

Logged Data: General information
fCursorLock
fInMouseCode
fMouseBusy

MOUSE_GETMAXVCOOR

Mouse Function 38

This function returns a flag indicating whether the mouse driver is disabled and indicates maximum virtual coordinates.

Input Parameter Keywords: None.
Output Parameter Keywords: None.

Logged Data: Mouse-disabled flag; Maximum virtual x; Maximum virtual y

MOUSE_GETCURMSKMCNT

Mouse Function 39

This function returns cursor information and accumulated raw mickey counts.

Input Parameter Keywords: None.
Output Parameter Keywords: None.

Logged Data: Screen-mask or Scan-line start; Cursor-mask or Scan-line stop; Horizontal mickey count; Vertical mickey count

MOUSE_GETCURHSPT

Mouse Function 42

This function returns the cursor hot-spot location, reports the type of mouse in use, and returns the internal counter that controls cursor visibility.

Input Parameter Keywords: None.
Output Parameter Keywords: None.

Logged Data: fCursor; Horizontal cursor hot spot; Vertical cursor hot spot; Type of mouse

MOUSE_HDWRESET

Mouse Function 47

This function returns cursor information and accumulated raw mickey counts

Input Parameter Keywords: None.
Output Parameter Keywords: None.

Logged Data: Success flag

MOUSE_SETGETBPT

Mouse Function 48

This function sets or returns cursor ballpoint-orientation and buttonmask information.

Input Parameter Keywords

Keyword	Type	Description
ROTANGLE	NUM	Rotation angle
CMDINFO	NUM	Command

Output Parameter Keywords: None.

Logged Data: Status; Rotation angle; Button mask

MOUSE_GETMINMAX

Mouse Function 49

This function returns the minimum and maximum horizontal and vertical coordinates for the current video mode.

Input Parameter Keywords: None.
Output Parameter Keywords: None.

Logged Data: Status; Virtual xminimum; Virtual yminimum; Virtual xmaximum; Virtual ymaximum

MOUSE_GETADVFCN

Mouse Function 50

This function returns the flags that indicate active advanced functions.

Input Parameter Keywords: None.
Output Parameter Keywords: None.

Logged Data: Active function flags

MOUSE_GETSWSET

Mouse Function 51

This function returns the current settings of switch values that can be passed to the mouse driver.

Input Parameter Keywords: None.
Output Parameter Keywords: None.

Logged Data: Mouse type; Mouse port; Language; Horizontal sensitivity; Vertical sensitivity; Double threshold; Ballistic curve; Interrupt rate; Cursor Override Mask; Laptop adjustment; Memory type; Super VGA support; Rotation angle; Primary button; Secondary button; Clip lock enabled; Acceleration curve data

Description of Test Cases

Each of the mouse test cases can be executed individually as previously described. The test scripts are described below. The user can create additional tests or combine tests into test cases after becoming familiar with DOSMOUSE and the MOUSE grammar file.

ALL.SCR: This runs all the mouse functions.
BUTTON.SCR: This tests button press and release functions.

Evaluation of Test Case Results

Unless otherwise stated in the test case descriptions, all test cases are expected to succeed. If a test case fails in a mode detectable by DOSMOUSE, then the token "ERROR" will be written to the corresponding log file.

Parallel Port Device Driver

The OS/2 parallel port device driver is a base physical device driver that supports the parallel port device interface for OS/2. There are two distinct versions of the parallel port device driver:

PRINT01.SYS: Supporting parallel port adapters on ISA/EISA bus machines
PRINT02.SYS: Supporting parallel port adapters on Micro Channel machines (machines containing Micro Channel architecture).

PRINT01.SYS manipulates the hardware ports through I/O instructions. The Micro Channel parallel port device driver does not access the hardware ports. Advanced BIOS (ABIOS), which executes on Micro Channel machines, replaces the hardware port manipulation done on the ISA/EISA bus machines.

Only one of these physical device drivers will be resident for each machine running in OS/2. Because the parallel port device driver is a base physical device driver, OS/2 determines the system's hardware configuration and automatically installs and initializes the appropriate physical device driver. OS/2 adds a BASEDEV= statement for the device driver to the CONFIG. SYS file.

Overview

The parallel port device drivers service parallel port requests from DOS, WIN-OS/2, and OS/2 applications (including those running under the Presentation Manager). Requests are serialized by the spooler so that mixed printer output will not occur. Printer requests include:

Initializing a parallel port device
Sending characters to a parallel port device
Returning the status of a parallel port device
Handling IOCtl function calls, including the setting of the parallel port device's frame control (characters per line and lines per inch)

In addition, the parallel port device drivers include character device monitor support. The parallel port device driver sends data to a character device monitor, if one is installed.

The primary method of communicating with the parallel port device driver is through a request packet. When the parallel port device driver receives a request packet, it determines which device the request is for. If a request is not already in progress, the physical device driver calls an appropriate routine to handle the request. If a request is in progress, the physical device driver blocks the caller's thread until the in-progress request has completed. Once the in-progress request has been serviced, the physical device driver will run the caller's thread and process the waiting request.

To make a request of the printer, an OS/2 application pushes parameters ( for example, the address of characters to be written) onto its stack, and calls the file system API (for example, DosWrite). The file system:

Determines that the request is for the parallel port device driver (based on the specified device handle)
Creates a request packet
Issues a call to the parallel port device driver strategy routine

To make a request of the printer from a DOS session, an application moves the parameters into predefined registers and issues an INT 17h or INT 21h. The INT 17h is intercepted by the virtual parallel port device driver. Refer to OS/2 Virtual Device Driver Referencefor more information. The INT 21h request is converted into a request packet and issued to the device driver strategy routine.

Replacing the Parallel Port Device Driver

The parallel port device drivers contain four device headers in their data segments with the reserved device names PRN, LPT1, LPT2, and LPT3. These device names correspond to the three physical devices supported by this physical device driver. Notice that the names PRN and LPT1, although logically appearing different, correspond to the same physical device.

The parallel port device driver is replaceable. It is uninstalled by creating another parallel port device driver with the device name in the device header identical as the one listed above. It can then be reinstalled by specifying the new parallel port device driver in a DEVICE= statement in CONFIG.SYS.

Note: Installation of the files associated with the new device driver, and the addition of the corresponding DEVICE= statement in the CONFIG.SYS file, is accomplished through the DDINSTAL utility and the Device Driver Profile (DDP) for the new device driver.

When the DEVICE= statement for the new parallel port device driver is encountered in CONFIG.SYS during system initialization, the system generates a DEINSTALL request packet and sends it to the parallel port device driver. The OS/2 parallel port device driver receives the DEINSTALL request packet and releases its resources. Refer to the strategy command, "14h / DEINSTALL" in the OS/2 Physical Device Driver Reference for more information.

If the parallel port device driver successfully releases its resources, it returns a successful completion on the Deinstallation request. When the parallel port device driver has been deinstalled, the system then generates an INSTALL request packet and sends it to the new device driver. Refer to the strategy command, "0h /INIT" in the OS/2 Physical Device Driver Reference for more information.

Parallel Port IRQ Performance

The Programmable Interrupt Controller (PIC) under OS/2 2.1, IRQ3 (serial port) has the highest priority in the system. This has given IRQ7 (parallel port) a much higher priority than it would otherwise have. It is now higher in priority than the keyboard or the mouse. A system unit running multiple parallel port devices, that can receive data quickly on a combination of serial/parallel port devices at a high rate of speed (for example, a laser printer with several megabytes of memory) can experience slow user input performance from the mouse and keyboard.

Several alternatives exist to improve user input performance. One alternative, for attended print servers, is to ensure the system unit supports a direct memory access (DMA) parallel or serial port. The parallel port device driver takes advantage of DMA, which reduces the number of hardware interrupts in the system. Fewer high priority interrupts in the system allow the processor to spend more time processing lower priority interrupts.

Another alternative is to convert a parallel port device to run using the serial port and to reduce the bit rate to the serial device. The ASYNC adapter must support extended hardware buffering. For more information on this approach, refer to the Physical ASYNC Communications Device Driver in the OS/2 Physical Device Driver Reference.

A last alternative for those situations where user responsiveness is extremely important is to reduce the number of print files being sent to the print server by moving some of the devices to other system units (thus balancing the workload among several system units available) or to reduce the user installable memory within the device.

DMA Parallel Port Support

The OS/2 2.1 (and later) parallel port device driver for PS/2 systems supports DMA parallel ports using the ABIOS parallel port functions found on those system units.

Using the parallel port in a Programmed I/O (PIO) methodology causes the processor to be involved on each byte transmitted. This prevents the processor from performing other operations.

Using the parallel port in a DMA methodology causes the processor to be involved on each buffer transmitted. The larger the buffer, the fewer interrupts to the CPU, and the more time the CPU can spend doing other useful work.

Code Page Support

The parallel port device driver provides code page support through the OS/2 character device monitor mechanism (for example, the spooler). In addition, three printer IOCtl commands support code page and font switching so that an application has the ability to change the active code page and font in the middle of its print job.

Because the spooler is no longer a character monitor, code page and font switching is handled before the parallel port device driver receives the data. This section remains for compatibility.

Parallel Port (Printer) Monitors

The parallel port device driver defines a data stream for each parallel port device. In addition, each printer data stream can be monitored by parallel port device monitor applications, registered with one of two monitor chains. Character device monitor support is provided by the parallel port device driver, therefore, for each parallel port device.

To register a monitor for one of the parallel port devices, an application issues the DosMonOpen and DosMonReg monitor function calls. DosMonReg generates an IOCtl request for the application to the parallel port device driver to register a monitor on one of the two monitor chains associated with the device. See Category 0Ah, "Register Monitor" (Function 40h), which can be found in the OS/2 Physical Device Driver Reference. When the parallel port device driver receives this request, it:

Creates a monitor chain for that device by calling the DevHlp_MonitorCreate, if none was previously created as the result of another register monitor IOCtl request.
Registers the monitor with the monitor chain by calling the DevHlp_Register.

By setting the DosMonReg index parameter appropriately, the application specifies on which of the two monitor chains its monitors are registered. The first monitor chain (specified by the application by setting Index=1) is considered to be the data chain, and is used by the parallel port device driver to send data to a monitor. The second monitor chain (specified by the application by setting Index=2) is considered to be the code page chain.

To ensure that printer requests are processed in order, the parallel port device driver places all data and code page requests into only the first monitor chain (referred to as the data chain). That is, the parallel port device driver issues MonWrite calls only to the data chain. The parallel port device driver does not place data into the code page chain by calling MonWrite.

To improve performance, the second monitor chain (code page chain) is used by the parallel port device driver primarily to receive the results of a code page request. Processes that issue code page requests are blocked until they receive an indication that their request is valid. Since the number of code page requests is negligible compared to the number of data requests, parallel port monitors can respond more quickly and efficiently to the physical device driver through the code page chain.

In summary, parallel port monitors:

Receive all data and code page requests from the first monitor chain (see DosMonRead)
Return data requests to the first monitor chain (see DosMonWrite)
Return code page requests to the first or the second monitor chain (see DosMonWrite), depending on the position of the monitor when other monitors are registered with the chain (see below)

Note: The parallel port device driver expects to receive the monitor responses to code page requests on the code page chain. If monitor responses to code page requests are not received from any monitor on the code page chain, unpredictable results can occur.
The spooler is an example of an application that registers a parallel port monitor with both the data chain and the code page chain for a parallel port device. When the spooler registers the monitor with the second chain (see DosMonReg, with Index=2) the monitor input buffer specified is not used because no requests are placed into the second monitor chain by the parallel port device driver.

Parallel port monitors must be designed with extreme care. They must be positioned carefully when other parallel port monitors, in particular the spooler, are registered:

If an application monitor wishes only to process character data, it registers a parallel port monitor only on the data chain (Index=1) when:
1. It is the only monitor in the monitor chain (for example, the spooler is not loaded).
2. It is registered in a position to process the data after the spooler. This monitor never sees code page requests from the spooler, because the spooler automatically sends these requests back to the physical device driver through the code page chain.
If an application wishes to process both character data and code page requests, it registers a parallel port monitor on the data chain (Index=1) and a parallel port monitor on the code page chain (Index=2) when:
1. It is the only monitor in the monitor chain. It must expect to receive both data and code page requests on the data chain. It must respond to the code page requests on the code page chain as quickly as possible.
2. It is registered in a position to process data after the spooler. It must expect to receive character data from the spooler on the data chain and the code page requests from the spooler on the code page chain.

Because the spooler passes the code page results along the code page chain before all the data has been spooled and released to be printed, a parallel port monitor cannot easily synchronize the code page requests with the data requests.

If a parallel port monitor wishes to process character data and code page requests, and it is registered in a position to process data before the spooler, it registers on the data chain (Index=1) only.

All data and code page requests are sent to the first (nonspooler) monitor on the data chain. Because the spooler receives data and code page requests from the data chain only, this monitor must pass on to the spooler through the data chain all the information it receives in the order that it is received.

IOCtl Support of Code Page and Font Switching

The parallel port device driver has three printer-specific IOCtl commands to support the code page and font switching provided in OS/2 2.1 (and later). In order to support these IOCtl calls, there are Font Monitor Buffer command/responses in the monitor interface between the parallel port device driver and the spooler.

All of the actual code page and font switching functions for printers are provided by the code page switcher or OS/2 printer drivers. When the spooler is started, it checks to see if code page support is required. If it is, the spooler causes the code page switcher to be loaded and initialized. The spooler interfaces with the code page switcher through the DosPFSxxx API functions. If a DEVINFO= statement is not specified in the CONFIG.SYS file, the spooler redirects code page requests to the Presentation Manager device drivers.

The following illustrates the dialog between the parallel port device driver and the spooler when the parallel port device driver receives one of these special IOCtl requests from an application:

The parallel port device driver receives an IOCtl request from an application to activate a code page.
If the spooler is loaded, the parallel port device driver sends a Font Monitor Buffer command to the spooler in the form of a special monitor record placed into the data monitor chain (refer to MonWrite in the OS/2 Physical Device Driver Reference).
The spooler calls DosMonRead to receive this special monitor record from its monitor input buffer registered with the data monitor chain.
When the spooler receives this special monitor record, it either calls DosPFSActivate to get information from the Define Code Page (DCP) system files, or it calls the appropriate Presentation Manager routines to get the code page information pertaining to the particular printer. This information is placed into a temporary spooler file.
The spooler sends a return code back to the parallel port device driver by calling DosMonWrite to place a special monitor record (that is, a Font Monitor Buffer response) into its monitor output buffer registered with the code page chain.

The three printer specific IOCtl commands to support code page and font switching are:

Activate Font: When an application issues a DosOpen for a printer (that is, PRN, LPT1, LPT2, or LPT3), the file system issues an Activate Font IOCtl to the parallel port device driver to set the active code page and font, according to the active code page of the process making the Open request. At any time, an application can also issue the IOCtl, "Activate Font" (Function 48h), to the parallel port device driver by using the handle returned from the DosOpen call to open the device. This allows the application to change the active code page and font in the middle of its print job.

If the parallel port device driver receives the Activate Font IOCtl, and the spooler or another monitor is registered, the parallel port device driver sends a Font Monitor Buffer command (in this case, an Activate Font command) to the monitor on the data chain. The monitor calls DosMonRead to receive this special monitor record from its monitor input buffer registered on the data chain. The monitor sends a Font Monitor Buffer response to this command and to the parallel port device driver by calling DosMonWrite. The monitor then places a special monitor record into its monitor output buffer registered on the code page chain. If the spooler or another monitor is not registered, the parallel port device driver returns the appropriate return code to the caller of the Activate Font IOCtl.

Query Active Font: When the parallel port device driver receives the Query Active Font IOCtl request, and if the spooler or another monitor is registered, the parallel port device driver sends a Font Monitor Buffer command (in this case, a "Query Active Font", Function 69h) to the monitor on the data chain. The monitor calls DosMonRead to receive this special monitor record from its monitor input buffer registered on the data chain. The monitor calls DosMonWrite to send a Font Monitor Buffer response to this command to the parallel port device driver. This places a special monitor record into its monitor output buffer registered on the code page chain. The parallel port device driver then returns the active code page and font information to the caller of the Query Active Font IOCtl. If the spooler or another monitor is not registered, the parallel port device driver returns the appropriate return code to the caller of the Query Active Font IOCtl.

Verify Font: If the parallel port device driver receives the Verify Font IOCtl request, and if the spooler or another monitor is registered, the parallel port device driver sends a Font Monitor Buffer command (in this case, "Verify Font", Function 6Ah, which can be found in the OS/2 Physical Device Driver Reference) to the monitor on the data chain. The monitor receives this special monitor record, from its monitor input buffer registered on the data chain, by calling DosMonRead. The monitor sends a Font Monitor Buffer response to this command to the parallel port device driver by calling DosMonWrite. This places a special monitor record into its monitor output buffer registered on the code page chain. The parallel port device driver then returns the return code to the caller of the Verify Font IOCtl. If the spooler or another monitor is not registered, the parallel port device driver returns the appropriate return code to the caller of the Verify Font IOCtl.

Refer to "Generic IOCtl Interface" and "Monitor Dispatcher Notification Interface", which can be found in the OS/2 Physical Device Driver Reference for specific interface parameters.

Character Monitor Performance

The character monitor buffer of the parallel port device driver has a size of 134 bytes. The PRINTMONBUFSIZE= command, within CONFIG.SYS, provides a method for character monitors to increase this size, and thereby increase performance of data to devices connected to the parallel port. The parallel port device driver allocates and registers its monitor chain buffer based upon the value specified.

The format of this command is:

 PRINTMONBUFSIZE=xxxx,xxxx,xxxx

 Where:
        xxxx corresponds to LPT1, LPT2, and LPT3 character monitor
        buffer size, respectively.

The minimum value allowed for compatibility with existing character monitors is 134 bytes. The maximum value is 2048 bytes. If a value that is out of the valid range is specified, a default value of 134 bytes is used.

Character monitors can dynamically determine the size of a device driver's monitor buffer by issuing a DosMonReg call with a 2-WORD buffer:

The first WORD consists of the length of the buffer (4).
The second WORD (on return from the call) contains the size of the device driver's monitor chain buffer.

DosMonReg returns with the return code ERROR_MON_BUFFER_TOO_SMALL. The character monitor then allocates the monitor buffer to the correct size and reissues the call to DosMonReg.

Parallel Port IRQ Timeout Processing

The parallel port device driver sets a 120-second timer after receiving a Write request and sending the first byte to the parallel port. If a hardware interrupt is not generated after 120 seconds, the timer expires and a timeout occurs.

There are two different mechanisms for processing timeouts:

If infinite retry is enabled, the parallel port device driver does not terminate the request and indefinitely continues to try to send the data to the printer.
If infinite retry is disabled, the parallel port device driver terminates the Write request, returning the number of actual bytes sent to the device.

When a monitor is registered, infinite retry is always enabled. The parallel port device driver sends a status monitor packet through the data chain (Index=1) when a timeout error occurs. This activity alerts all monitors of the error.

If a hardware interrupt does occur, the parallel port device driver resets the timer to 120 seconds and sends the next byte to the device. This activity continues until all data has been sent to the device. Once the parallel port device driver determines that all characters have been sent, it turns the timer OFF.

Parallel Port Device Driver Interfaces

The parallel port device driver has several interfaces:

Request Packet interface (referred to as the Strategy interface)
INT 21h interface
Generic IOCtl interface
Hardware Interrupt interface
Monitor Dispatcher Notification interface

Request Packet Interface

The file system is the primary component that interfaces with the parallel port device driver. In response to a function call, the file system creates a request packet containing the information required by the parallel port device driver to process the request. The file system then calls the parallel port device driver's strategy entry point, with the registers ES: BX containing the address of the request packet.

The Strategy interface uses the Call/Far return model and must preserve the caller's registers. The strategy entry point routes all IOCtl requests and all Open, Read, Write, Close, and Status requests to the appropriate internal parallel port device driver routines to handle the requests. For a description and format of a request packet, refer to the physical device driver strategy commands, which can be found in the OS/2 Physical Device Driver Reference.

Request Packet Command Summary

The command code field of a request packet contains the function requested of the physical device driver. The parallel port device driver is a character device driver and supports all character device driver functions.

A detailed description of these commands can be found in the OS/2 Physical Device Driver Reference.

Request Packet Status Description

On the call to the parallel port device driver, the status code is set to 0. On return from the physical device driver, the status code contains the results of the request (for example, done or error). The parallel port device driver sets the error bit, busy bit, done bit, and error code, when necessary.

Return Codes

The error codes that the parallel port device driver returns are listed below:

8102h Device not ready
8103h Unknown command
8109h Printer out of paper
810Ah Write fault
810Ch General failure
8111h Character I/O call interrupted
8113h Invalid parameter

If the parallel port device driver does not support a request, a status of 8103h (unknown command) is returned.

INT 21h Interface

An application running in a DOS session can access the parallel port device driver through INT 21h. The file system creates a request packet from the parameters and calls the parallel port device driver at its strategy entry point. This interface maintains compatibility with DOS applications. As in the Request Packet interface, the parallel port device driver preserves the caller's registers ES:BX and points to the request packet. The strategy entry point follows the Call/Far return model.

Generic IOCtl Interface

The parallel port device driver supports a set of generic IOCtl functions. Refer to the parallel port control IOCtl commands in the OS/2 Physical Device Driver Reference for a list and detailed description of these functions.

Note: From the command line, a user can start the MODE command to perform the parallel port control functions Set/Query Frame Control and Set/Query Infinite Retry. See the description of the MODE command in the OS/2 Command Reference.

Parallel Port Device Driver Support

All the Category 05h IOCtl commands are supported by the parallel port device driver. Additionally, the following IOCtls are also supported by the parallel port device driver:

Category 0Ah Character Monitor Control. Supported by the physical keyboard, mouse, and parallel port device drivers.

Function 40h Register (A character monitor)

Category 0Bh General Device Control. Supported by all the character device drivers.

Function 01h Flush input buffer

Function 02h Flush output buffer

Function 60h Query monitor support

Character Monitor Control

The IOCtl Category 0Ah "Register Monitor" (Function 40h), which can be found in the OS/2 Physical Device Driver Reference, is supported by the physical keyboard and mouse device drivers, as well as by the parallel port device driver. The index field of the data packet received on this call is device specific. That is, it is defined differently for each physical device driver. The index field generally indicates on which monitor chain an application wishes to register a monitor.

As previously discussed, the parallel port device driver creates two monitor chains for each parallel port device - a data chain and a code page chain. An application issuing this IOCtl function call to a specified parallel port device sets the index parameter as follows:

Index=1Registers a monitor with the data chain.
Index=2Registers a monitor with the code page chain.

Hardware Interrupt (8259) Interface

When a hardware interrupt is pending on an interrupt level owned by the parallel port device driver, the hardware interrupt manager calls the parallel port device driver's hardware interrupt entry point for that interrupt level. PRINT01.SYS runs parallel port devices using hardware interrupt levels IRQ 7 and IRQ 5. PRINT02.SYS runs parallel port devices on hardware interrupt level IRQ 7. The parallel port device driver for Micro Channel machines shares the hardware interrupt level IRQ 7.

Each of the parallel port device driver's hardware entry points call a parallel port device driver general interrupt routine. This routine sends the next character to the port, issues an EOI (End-Of-Interrupt), and completes a strategy request when the last character has been received by the device.

The hardware interrupt manager saves all registers before calling the parallel port device driver interrupt entry points. On return to the hardware interrupt manager, the parallel port device driver's general interrupt routine clears the carry flag, signalling the interrupt manager that the parallel port device driver owns the interrupt. If the parallel port device driver does not own the hardware interrupt, it sets the carry flag. The parallel port device driver's hardware interrupt routine follows the Call/Return Far model and does not handle nested interrupts.

Monitor Dispatcher Notification Interface

The OS/2 parallel port device driver supports character device monitors. For a description of how that support is provided, see #Parallel Port (Printer) Monitors.

Data sent to each parallel port device can be monitored before reaching the device by parallel port monitor applications registered with one of two monitor chains. When a parallel port monitor is registered, the parallel port device driver calls the MonWrite device helper runtime to place all requests (in the form of monitor records or packets) into its monitor chains. Each parallel port monitor registered on the monitor chain can monitor the data destined for the parallel port. Parallel port data that has passed through all monitors registered on the monitor chain is placed into a parallel port device driver monitor chain buffer by the OS/2 monitor dispatcher.

A monitor chain for a parallel port device is created when the parallel port device driver calls MonitorCreate. For each monitor chain, the parallel port device driver must provide:

A device driver monitor chain buffer, into which the monitor dispatcher places the filtered parallel port data after it has passed through all the parallel port monitors in the monitor chain.

The length of the parallel port device driver's monitor chain buffer is 134 bytes. This length is specified by the parallel port device driver in the first WORD of the buffer when MonitorCreate is called. The length of parallel port monitor input and output buffers, registered with a parallel port monitor chain, must be greater than or equal to 134 bytes plus 20 bytes.

The address of a notification routine that is called by the monitor dispatcher when it has placed filtered data into the monitor chain buffer.

Before the monitor dispatcher calls the parallel port device driver's notification routine, it:

1.Places a data record in the parallel port device driver's monitor chain buffer starting at the second WORD of the buffer

2.Places the length of the data record (in bytes) in the first WORD of the parallel port device driver's monitor chain buffer

3.Sets the register pair ES:SI to point to the parallel port device driver 's monitor chain buffer

The general monitor packet format for code page processing is described in the following table.

Field	Length
Monitor Flags	WORD
System File Number	WORD
Command Byte	BYTE
Reserved. Set to 0.	BYTE
Reserved. Set to 0.	BYTE
Reserved. Set to 0.	BYTE
Return Code	WORD
Code Page	WORD
Font ID	WORD

The general monitor packet format for Open, Write, Close, Status, and Print -Job-Title monitor requests is described in the following table.

Field	Length
Monitor Flags	WORD
System File Number	WORD
Data to be Monitored (optional)	128 BYTES

Data items included in these data structures are defined in the descriptions of the corresponding request packet data structures. The parallel port device driver communicates with parallel port monitors using the monitor protocol.

Parallel Port Monitor Buffer Command

Each monitor record can be of variable length and contain a WORD of flags defining the type of monitor packet.

Note:Monitor packets that parallel port monitors do not understand should be returned to the parallel port device driver on the monitor chains from which they were received.

  Monitor Flags       Device-Driver Dependent

  Byte 0               Byte 1
 /---------------\    /---------------\
 |7|6|5|4|3|2|1|0|    |7|6|5|4|3|2|1|0|
 \---------------/    \---------------/
  | | | | | | | |      | | | | | | | |
  | | | | | | | \-Open | | | | | | | \-Printer Font Monitor
  | | | | | | \-Close  | | | | | | |    Buffer Command Response
  | | | | | \-Flush    | | | | | | \-Code Page Command Response
  | | | | \-Reserved   | | | | | \-INT 17H Code Page Request
  | | | \-Reserved     | | | | \-Status
  | | \-Reserved       | | | \-Reserved
  | \-Reserved         | | \-Job Title
  \-Reserved           | \-Reserved
                       \-Reserved

Monitor Open Packet

When the Open bit (byte 0, bit 0) is set to 1, the monitor buffer contains an open packet from the parallel port device driver. In this case, the next two bytes are:

Field	Length
System File Number	WORD

Monitor Close Packet

When the Close bit (byte 0, bit 1) is set to 1, the monitor buffer is a close packet from the parallel port device driver. In this case, the next two bytes are:

Field	Length
System File Number	WORD

Monitor Write Packet

When the Close bit (byte 0, bit 1) is set to 0, and the Open bit (byte 0, bit 0) is set to 0, the monitor buffer is a write data packet from the parallel port device driver. In this case, the next bytes are:

Field	Length
System File Number	WORD
Data to be Monitored	128 BYTES

Font Monitor Packet

When the Font Monitor Buffer Command/Response bit (byte 1, bit 0) is set to 1, the monitor buffer is a Font Monitor Buffer command. In this case, the next six bytes are:

Field	Length
System File Number	WORD
Command Byte	BYTE
Reserved. Set to 0.	BYTE
Reserved. Set to 0.	BYTE
Reserved. Set to 0.	BYTE

Byte 2-3 System File Number

Byte 4 Font Monitor Buffer Command byte, which indicates the type of command or response

Byte 5 Reserved. Must be set to 0

Byte 6-7 Reserved. Must be set to 0

When the Code Page Command Processed bit (byte 1, bit 1) is set to 1, the Font Monitor Buffer command has been processed by the spooler.

The parallel port device driver sends Font Monitor Buffer commands to its monitors through the data monitor chain (Index=1). A parallel port monitor, which services the Font Monitor Buffer command, sets the Code Page command processed bit and uses DosMonWrite to place the Font Monitor Buffer response into the code page monitor chain (Index=2). Data to be printed continues to flow on the data monitor chain. The code page monitor chain is used only for the Font Monitor Buffer responses, so the parallel port device driver does not block a program issuing a code page and font IOCtl request when print data monitor buffers are already queued ahead of the IOCtl request.

Font Monitor Buffer Commands:The valid Font Monitor Buffer commands, along with the remainder of the buffer contents for the responses, are as follows:

Byte 4 = 01h Activate Font. Command data, starting at byte 8:

Field	Length
Return Code	WORD
Code Page	WORD
Font ID	WORD

Return Code A value returned, starting at byte 8, which includes the following values:

0000h Successful completion

0002h Code page is not available

0003h No code page function, because spooler not started

0004h Font ID is not available (verify)

0009h Error caused by switcher error, not by input parameters

000Ah Error caused by invalid printer name as input

000Dh Received code page request, when code page switcher not initialized

000Fh SFN table full cannot activate another entry

0013h DASD error reading font file

0015h DASD error reading font file definition block

0017h DASD error, while writing to temporary spool file

0018h Disk full error, while writing to temporary spool file

0019h Spool file handle was bad Code Page. The value to assign to the currently active code page.

0000h If the Code Page value and Font ID are specified as 0, set printer to hardware default code page and font.

0001h-FFFFh Valid code page numbers.

Font ID The ID value of the font to make currently active.

0000h If the Code Page value and Font ID are specified as 0, set printer to hardware default code page and font.

If only the Font ID is 0 and the Code Page is a valid nonzero, then any font within the specified code page is acceptable.

0001h-FFFFh Valid Font ID numbers, which are font types defined by the font file definitions as fonts that can be downloaded. For cartridge fonts, Font IDs are the numbers on the cartridge label. They are also entered in the DEVINFO statement for the printer.

The parallel port device driver passes the Font Monitor Buffer command to the monitor on the data monitor chain (Index=1). The monitor returns the Font Monitor Buffer response to the parallel port device driver on the code page monitor chain (Index=2).

Byte 4 = 02h Query Active Font. There is no additional command data. Data returned from this function call includes:

Field	Length
Return Code	WORD
Code Page	WORD
Font ID	WORD

Return Code A value returned, starting at byte 8, which includes the following values:

0000h Successful completion

0003h No code page function, because spooler not started

0009h Error caused by switcher error, not by input parameters

000Ah Error caused by invalid printer name as input

000Dh Received code page request, when code page switcher not initialized

0010H Received request for SFN not in SFN table.

Code Page On return, is set to currently active code page:

0000h If the Code Page value and Font ID are returned as zero, the printer is set to the hardware default code page and font.

0001h-FFFFh Valid code page numbers.

Font ID On return, is the ID value of the Font, which is currently active:

0000h If the Code Page value and Font ID are specified as zero, the printer is set to the hardware default code page and font. A Font ID value of zero can indicate the default font of a particular code page.

0001h-FFFFh Valid Font ID numbers, which are font types defined by the font file definitions as fonts that can be downloaded. For cartridge fonts, Font IDs are the numbers on the cartridge label. They are also entered in the DEVINFO statement for the printer.

The parallel port device driver passes the Font Monitor Buffer command to the monitor on the data monitor chain (Index=1). The monitor returns the Font Monitor Buffer response to the parallel port device driver on the code page monitor chain (Index=2).

Byte 4 = 03h Verify Font. Command Data, starting at byte 8:

Field	Length
Return Code	WORD
Code Page	WORD
Font ID	WORD

Return Code A value returned, starting at byte 8, which includes the following values:

0000h Successful completion

0002h Code page is not available

0003h No code page function, because spooler not started

0004h Font ID is not available (verify)

000Ah Error caused by invalid printer name as input

000Dh Received code page request, when code page switcher not initialized.

Code Page The Code Page number to validate.

0000h-FFFFh Valid code page numbers.

Font ID The Font ID value to validate.

0000h-FFFFh Valid Font ID numbers.

The parallel port device driver passes the Font Monitor Buffer command to the monitor on the data monitor chain (Index=1). The monitor returns the Font Monitor Buffer response to the parallel port device driver on the code page monitor chain (Index=2).

Monitor Status Packet

When the Status bit (byte 1, bit 3) is set to 1, this indicates that the monitor buffer is a status packet from the parallel port device driver. In this case, the next four bytes are:

Field	Length
System File Number	WORD
Error Code	BYTE
Reserved	BYTE

The parallel port device driver sends either device not ready (02h), printer out of paper (09h), or write fault (0Ah) as the error code.

Monitor-Job Title Packet

A print-monitor job title packet passes the name of the file being printed to all monitors registered with the parallel port device driver.

When the job title bit (byte 1, bit 5) is set to 1, it indicates the monitor buffer is a job title packet from the parallel port device driver. In this case, the next bytes are:

Field	Length
System File Number	WORD
Job Title Length	WORD
Job Title Buffer	BYTES

The Job Title Length field includes the null character. The Job Title Buffer is terminated with the null character. The Job Title Buffer field contains bytes 6-131.

Sharing the Parallel Port With Other Device Drivers

The OS/2 parallel port device driver provides two functions in its physical device driver to physical device driver inter-device-driver communication ( PDD-PDD IDC) interface - request exclusive access and release exclusive access to the parallel port. The request exclusive access IDC function is used by device drivers to request sole ownership of the parallel port. The release exclusive access IDC function is used by device drivers to release sole ownership of the parallel port. Parameter passing is register-based and not stack-based.

Client device drivers use the DevHlp_AttachDD to obtain the OS/2 parallel port device driver IDC entry point. The client device driver requests sole ownership of the parallel port once it has work to perform and should release ownership of the parallel port once the work has completed. Client device drivers obtain and release sole ownership to the parallel port by loading the general purpose registers with the appropriate parameters and calling the OS/2 parallel port device driver.

After obtaining sole ownership of the parallel port, the client device driver should then obtain the resources it needs to perform the request ( including the hardware interrupt levels, DMA channels, and other shareable system resources). Prior to releasing ownership of the parallel port, the client device driver should release these other sharable system resources so that other client device drivers can obtain them. At a minimum, the client device driver should release ownership of the parallel port at the completion of a kernel write request packet. The process of sharing the parallel port only works when client device drivers cooperate with each other.

Exclusive port access can be overridden with the share access option in the parallel port settings dialog box of a print object. When this option is selected, all client device drivers requesting sole access to the parallel port are granted access. The parallel port device driver does not perform the serialization of access to the port. Users must perform the serialization by not trying to access two devices connected to the parallel port simultaneously. Otherwise, unpredictable results will occur.

The parallel port sharing feature is not available in the OS/2 2.1 (or later) product. It is available through the OS/2 Driver Development Support group and the IBM Developer Connection Device Driver Kit for OS/2.

Request Exclusive Access

Request Exclusive Access grants the calling device driver sole ownership of the parallel port until a Release Exclusive Access is issued.

Parameters

 AX = Function Code           ; 0 = Request Exclusive Access
 BX = Request Flags           ; Bit 0 = 0 Do not block
                              ; Bit 0 = 1 Block until available
 CX = Port ID                 ; LPT1 = 0, LPT2 = 1, LPT3 = 2
 DS = Data Selector           ; OS/2 PPDD Data Selector
 ES = Data Selector of caller ; DS of caller

Returns

No error

Carry Flag clear
AX = 0

Error

Carry Flag set
AX = Error code

Possible errors:

ERROR_I24_INVALID_PARAMETER
ERROR_I24_DEVICE_IN_USE
ERROR_I24_CHAR_CALL_INTERRUPTED

Release Exclusive Access

Release Exclusive Access releases the calling device driver from sole ownership to the parallel port. Sole ownership was granted when a Request Exclusive Access was issued.

Parameters

 AX = Function Code           ; 1 = Release Exclusive Access
 CX = Port ID                 ; LPT1 = 0, LPT2 = 1, LPT3 = 2
 DS = Data Selector           ; OS/2 PPDD Data Selector
 ES = Data Selector of caller ; DS of caller

Results

        No error
           Carry Flag clear
           AX = 0

        Error
           Carry Flag set
           AX = Error code
                Possible errors:
                ERROR_I24_INVALID_PARAMETER
                ERROR_I24_DEVICE_IN_USE

Physical Bidirectional Parallel Port Device Driver

The OS/2 base device driver, PAR1284.SYS, is a bus-independent device driver that supports bidirectional communication across the parallel port to bidirectional capable peripherals. The protocol is described as half-duplex (either the host or peripheral can transmit at a given point in time) in a master-slave relationship (the host determines who can transmit and when).

Overview

The OS/2 bidirectional parallel port device driver supports the Standard Parallel Port (SPP) in compatible, FIFO, and extended mode and supports the Extended Capabilities Port (ECP) in standard, PS/2, FIFO and ECP FIFO modes.

The enhanced parallel port modes, while maintaining compatibility with the "classic" IBM PC parallel port, also provide FIFO buffer capability for improved performance, several modes which enable bidirectional data transfer (nibble mode, byte mode, and ECP mode), and a mode that enables hardware controlled handshaking of multiple data bytes in both directions ( ECP FIFO mode). The FIFO mode generates the lowest CPU overhead thus providing improved system response for the user while data is being transfered to/from the peripheral.

ECP mode also includes a method for addressing multiple devices attached to the same ECP capable port. This feature enables other software to be written to control multifunction office devices such as a FAX/scanner/ printer/copier machine attached with a single cable to an ECP parallel port on the computer.

The bidirectional parallel port device driver conforms to the Standard Signaling Method for a Bidirectional Parallel Peripheral Interface for Personal Computers (IEEE 1284-1994) for bidirectional communications. Bidirectional communication enables the host system (IBM PC compatible) to communicate with the peripheral and the peripheral to communicate with the host. The bidirectional communication protocols supported are nibble, byte , and ECP modes.

Typically, the host communicates with the peripheral for identification, configuration, and status information. The identification data can be used to auto configure the system with the correct device drivers for the specific device. Configuration data can be returned to the device driver so that the user can make decisions based upon actual configuration rather than possible configuration. Status data can be used to present real time information to the user by way of an interactive graphical application. A remote operator panel is an example of an interactive graphical application for a printer. The application can display a window in the likeness of the operator panel found on the front of a printer. The user is able to make menu selections from a remote system without having to be physically next to the printer.

Installation

The bidirectional parallel port device driver should be installed to the \OS2\BOOT directory of the OS/2 partition on your disk. The BASEDEV=PAR1284.SYS statement must exist in the CONFIG.SYS file. The BASEDEV=PRINT0?.SYS statement (where ? can be 1 or 2 as appropriate) must be removed from the CONFIG.SYS file. The OS/2 operating system must be shutdown and restarted for the bidirectional parallel port device driver to become active.

Functional Support

The bidirectional parallel port device driver is a functional replacement for the OS/2 parallel port device drivers (PRINT01.SYS and PRINT02.SYS). The bidirectional parallel port device driver supports the following strategy commands:

open
read
write
close
ioctl
input flush
output flush
initialize device driver
initialization complete

For more information on the IOCtl commands supported, refer to the Category 05h Parallel Port Control IOCtl Commands found in the Physical Device Driver Reference.

Character Monitors

The bidirectional parallel port device driver does not support character monitors and therefore does not support the category 0Ah and 0Bh monitor IOCtl commands. It also does not support the following category 05h Parallel Port Control IOCtl commands related to code page and font switching (previously performed by a character monitor).

Activate Font
Query Active Font
Verify Font

The PRINTMONBUFSIZE=CONFIG.SYS statement is not used by the bidirectional parallel port device driver.

Parallel Port Timeout Processing

The bidirectional parallel port device driver supports timeout processing on an inter-character and a request packet basis for both read and write requests. For more information on the timeout IOCtl commands supported, refer to the Category 05h Parallel Port Control IOCtl commands found in the Physical Device Driver Reference.

Sharing the Parallel Port With Other Device Drivers

Refer to #Sharing the Parallel Port With Other Device Drivers for details on how this function works. The bidirectional parallel port device driver provides this capability.

Parallel Port Device Driver Test Tool

This chapter explains how to use the parallel port Device Driver Test Tool.

Overview

The parallel port Functional Verification Tests (FVTs) exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of parallel port device drivers. The tests are implemented with the Device Driver Test Tool (DDTT). Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. The test scripts give the user a repeatable set of tests that demonstrate parallel port function and performance. Errors are reported and are isolated to a specific test sequence and API.

User input and output from each thread of the parallel port tests is performed by way of a separate Presentation Manager window. Test cases log all information to a log files, clearly indicating the actual execution sequence in the event of errors.

Parallel Port Test Architecture

The DDTT provides a common front-end parser for test-case scripts. The following DDTT parallel-specific files are required:

DDTPARA.DLL
PARALLEL.GRA
GEN.GRA - needed for test script file, REQEX.SCR
GENDRV.SYS - needed for test script file, REQEX.SCR

The C++ source code for DDTPARA.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2.

The following required, common components of the DDTT implement the DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE:

DDTT.EXE
DDTT.DLL
GLOBAL.DLL
GLOBAL.GRA

Installation

There are two directory structures that utilize test suites in the IBM Developer Connection Device Driver Kit for OS/2. The TESTCERT substructure contains the executables and test cases; the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL.

The following procedure describes installation for running test cases:

Copy the executable and parallel port test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TESTPARA. Test-case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TESTPARA and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the parallel port test suite:
[C:\]md testpara

[C:\]cd testpara

[C:\testpara]copy e:\ddk_x86\testcert\inputout\function\parallel\*

[C:\testpara]copy e:\ddk_x86\testcert\general\ddtt\*
Add the C:\TESTPARA to the LIBPATH and PATH in the CONFIG.SYS file.
For script testcase REQEX.SCR, which requests and releases exclusive access, a generic driver named GENDRV.SYS must be installed. Edit your system's CONFIG.SYS file and add the following line:
DEVICE=c:\testpara\gendrv.sys
Reboot your machine so the new LIBPATH entry and DEVICE statement take effect.

Test-Case Execution

The DDTT parallel port tests must be executed on a directly-attached printer device. These tests will not work when executed against a printer device accessed by way of a network connection.

There are two ways to run parallel port tests. To run the program from a command file, be sure the files are installed in the current directory. Then, execute the TESTFONT or TESTPARA command files. The command file will run a set of script files. The TESTFONT executes scripts related to font testing and requires the spooler to be enabled. The TESTPARA executes scripts using other printer functions that require the spooler to be disabled.

To run one script file at a time, see #Description of Test Cases of the file to get a description of each script file. Then, after determining which script file to run, type in DDTT followed by the script file name:

 [C:\TESTPARA]DDTT QFONT.SCR

After the script has finished executing, control will transfer back to the OS/2 Window. If the script files are run individually, and a TESTxxx command file has not been run first, then run SETINFO to set up your printer device.

There are three different sets of script files in the DDTT parallel port package. The first set is the font script files, the second set is the general printer script files, and the third is only one script file, REQEX. SCR, which requests and releases exclusive access. When TESTFONT or TESTPARA is run, it will ask for the printer device (such as LPT1 or LPT2).

The SETINFO command file will set up the necessary information that is needed for the parallel port script files. The command file will ask the following question:

 PLEASE ENTER THE OUTPUT PORT OF YOUR PRINTER, SUCH AS LPT1

After this information is entered, the command file will store this information in the SYSINFO.TXT file. The contents of the file is

PARA SET DEVICENAME=LPT1

DDTT Parallel Port Test Grammar Function Calls

The following is a list of the DDTT Parallel Port Test Grammar Function Calls:

PARA_OPEN
PARA_CLOSE
PARA_SETRAMECTRL
PARA_SETRETRY
PARA_INIT
PARA_ACTIVATEFONT
PARA_SETTITLE
PARA_SETWRTTIMEOUT
PARA_QFRAMECTRL
PARA_QRETRY
PARA_QPORT
PARA_QACTIVEFONT
PARA_VERIFYFONT
PARA_QWRTTIMEOUT
PARA_READFILE
PARA_WRITEFILE

PARA_OPEN

This function opens the given parallel port.

Input Parameter Keywords

Keyword	Type	Description
DEVICENAME	STRING	Output port identification, such as LPT1

Output Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port

Logged Data

None.

PARA_CLOSE

This function closes the opened parallel port.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port

Output Parameter Keywords

None.

Logged Data

None.

PARA_SETFRAMECTRL

Category 05h - Function 42h

This function sets frame control (characters-per-line, lines-per-inch).

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port
CPL	NUM	Characters-per-line
LPI	NUM	Lines-per-inch

Output Parameter Keywords

None.

Logged Data

Frame Control Message with characters-per-line and lines-per-inch.

PARA_SETRETRY

Category 05h - Function 44h

This function sets infinite retry on/off (0=OFF, 1=ON).

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port
RETRY	NUM	ON or OFF setting

Output Parameter Keywords

None.

Logged Data

Retry state Message with Infinite Retry Disabled/Enabled

PARA_INIT

Category 05h - Function 46h

This function initializes parallel port.

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port

Output Parameter Keywords

None.

Logged Data

None.

PARA_ACTIVATEFONT

Category 05h - Function 48h

This function activates a font.

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port
CODEPAGE	NUM	Number of code page
FONTID	NUM	Number of font

Output Parameter Keywords

None.

Logged Data

Font information Message with CODEPAGE and FONTID

PARA_SETTITLE

Category 05h - Function 4Dh

This function sets job title.

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port
JOBTITLE	STRING	Job title identification

Output Parameter Keywords

None.

Logged Data

Job title information Length and address with job title information.

PARA_SETWRTTIMEOUT

Category 05h - Function 4Eh

This function sets write timeout.

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port
PPWRTTIMEOUT	NUM	Seconds for write timeout

Output Parameter Keywords

None.

Logged Data

Write time out value Parallel Port Write Time Out Value in seconds

PARA_QFRAMECTRL

Category 05h - Function 62h

This function queries frame control (characters-per-line, lines-per-inch).

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port

Output Parameter Keywords

None.

Logged Data

Frame Control Message with characters-per-line and lines-per-inch.

PARA_QRETRY

Category 05h - Function 64h

This function queries infinite retry.

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port

Output Parameter Keywords

None.

Logged Data

Retry state Message with Infinite Retry Disabled/Enabled

PARA_QPORT

Category 05h - Function 66h

This function queries port.

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port

Output Parameter Keywords

None.

Logged Data

Data Value in data field

PARA_QACTIVEFONT

Category 05h - Function 69h

This function queries active font.

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port

Output Parameter Keywords

None.

Logged Data

Font information Message with CODEPAGE and FONTID

PARA_VERIFYFONT

Category 05h - Function 6Ah

This function verifies font.

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port
CODEPAGE	NUM	Number of code page
FONTID	NUM	Number of font id

Output Parameter Keywords

None.

Logged Data

Font information Message with CODEPAGE and FONTID

PARA_QWRTTIMEOUT

Category 05h - Function 6Eh

This function queries write time out.

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port

Output Parameter Keywords: None.

Logged Data

Time out information Message with PP Write Time Out Value in seconds.

PARA_READFILE

This function reads a file.

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port
FILENAME	STRING	File to be read
BYTECOUNT	NUM	Number of bytes to read
$BUFFER	STRING	Buffer to hold data

Output Parameter Keywords: None.

Logged Data: None.

PARA_WRITEFILE

This function writes a file.

Required Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Handle number of output parallel port
FILENAME	STRING	Name of file to write
$BUFFER	STRING

Output Parameter Keywords: None.

Logged Data: None.

Description of Test Cases

Each of the parallel port test cases can be executed individually as previously described. The corresponding test scripts are described below. The user can create additional tests or combine tests into multi-threaded test cases after becoming familiar with the DDTT and the parallel grammar file.

All of the parallel port test cases use the DDTT @IMPORT command to include one script file:

SYSINFO.TXT
The content of the SYSINFO.TXT files is set by the SETINFO.CMD command file. SETINFO.CMD should be executed once to establish values for the following DDTT parameter keywords:
DEVICENAME - drive name of the parallel port device under test, such as LPT1.

All test scripts open and close the parallel port device and verify successful status return from every exercised API. All test scripts log information to a log file with the same file name and a file name extension .LOG. When current status is queried (for example, the font, timeout, or port), this data is written to DDTT's output windows and to the log file. Log files can be examined after the test case has completed.

ACTFONT.SCR: Activates and logs the font identified by the CODEPAGE and FONTID.
FRAMES.SCR: Sets and queries the frame controls for four combinations of characters-per-line and lines-per-inch.
INITPAR.SCR: Initializes the parallel port.
QFONT.SCR: Queries the activefont, logging, CODEPAGE, and FONTID.
QFRAME.SCR: Queries frame control, logging characters-per-line, and lines-per-inch settings.
QPARPORT.SCR: Queries the parallel port and logs the value in the data field.
QPPWTOUT.SCR: Queries write time out and logs time, in seconds.
QRETRY.SCR: Queries to determine if infinite retry is enabled.
REQEX.SCR: Requests exclusive access of LPT1 and displays Have exclusive access, pauses for two minutes, and then releases exclusive access. This process requires installation of the generic device driver, GENDRV.SYS.
RETRY.SCR: Enables infinite retry, queries retry, disables infinite retry, and queries retry, again.
SETFRAME.SCR: Sets frame control of 80 characters-per-line and 6 lines-per-inch.
SPPWTOUT.SCR: Sets parallel port write time out value to 10 seconds.
SRETRY.SCR: Sets infinite retry enabled.
TITLERD.SCR: Sets jobtitle to BIDI TEST JOB-TITLE, reads file READ.SCR, and writes file.
VFONT.SCR: Verifies font with CODEPAGE=34000 and FONTID=34000.

Evaluation of Test Case Results

Unless otherwise stated in the test-case descriptions, all test cases are expected to succeed. If a test case fails in a mode detectable by DDTT, then the token "ERROR" will be written to the corresponding log file.

The script files test all of the different parallel port functions. After each script file has finished executing, it will log all of the test information out to a log file. When all of the script files have finished executing, the command file will search all of the log files for any errors that have occurred. The results from this search are stored in the RESULTS.TXT file.

When the command file has completed searching the log files, it also displays the results on the screen. The command file is searching only for the word "ERROR".

PCMCIA Socket Services Device Driver Test Tool

This chapter explains explains how to use the Socket Services Device Driver Test Tool.

Overview

PCMCIA Socket Services Functional Verification Tests (FVTs) exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of PCMCIA Socket Services device drivers. The tests are implemented with the Device Driver Test Tool (DDTT). Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. The test scripts give the user a repeatable set of tests that demonstrate PCMCIA Socket Services function and performance. Errors are reported and are easily isolated to a specific test sequence and API.

User input and output from each thread of the PCMCIA Socket Services tests is performed by way of a separate Presentation Manager window. Multi- threaded test cases log all information to a single log file, clearly indicating the actual execution sequence in the event of errors.

PCMCIA Socket Services Test Architecture

The DDTT provides a common front-end parser for test case scripts. The following DDTT PCMCIA-specific files are required:

DDTPCMC.DLL
PCMC.GRA.
PCMCIATS.SYS

The C++ source code for DDTPCMC.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2.

The following required, common components of DDTT implement DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE:

DDTT.EXE
DDTT.DLL
GLOBAL.DLL
GLOBAL.GRA

Installation

There are two directory structures in the IBM Developer Connection Device Driver Kit for OS/2that utilize test suites. The TESTCERT substructure contains the executables and test cases; the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL.

The following procedure describes installation for running test cases:

1.Copy the executable and PCMCIA socket services test case files from the IBM Developer Connection Device Driver Kit for OS/2CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TESTPCMC. Test case script and command files can also be placed in this directory on the hard disk. If the target directory is C: \TESTPCMC and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2CD-ROM disc, then use the following commands to copy the PCMCIA socket services test suite:

[C:\]md testpcmc
[C:\]cd testkpcmc
[C:\testpcmc]copy e:\ddk_x86\testcert\storage\function\pcmcia\socket\*
[C:\testpcmc]copy e:\ddk_x86\testcert\general\ddtt\*

2.Copy the PCMCIATS.SYS file to your root system directory. If your system drive is C, execute the following:

[C:\testpcmc]copy PCMCIATS.SYS c:\

1.To install the test device driver, add BASEDEV=PCMCIATS.SYS immediately before the following two lines (which are used for a Think Pad system). Other systems use different names for the PCMCIA socket services and Resource Map Utility device drivers. These lines load the system's Resource Map Utility device driver and Socket Services device driver. The PCMCIATS. SYS test device driver enables an IOCtl interface for calling Socket Services from the DDTT script files.

BASEDEV=ICRMU01.SYS
BASEDEV=IBM2SS01.SYS

2.Next, make sure the following lines are commented out of the CONFIG.SYS file.

rem BASEDEV=PCMCIA.SYS
rem DEVICE=VPCMCIA.SYS
rem DEVICE=AUTODRV2.SYS AUTODRV2.INI
rem DEVICE=$ICPMOS2.SYS

Loading any of the above PCMCIA support drivers will interfere with Socket Services testing.

3.Add C:\TESTPCMC\BIN to the LIBPATH and PATH in CONFIG.SYS.

4.Reboot your machine so the new LIBPATH entry and CONFIG.SYS changes take effect.

Test-Case Execution

1.Change to the directory where the socket services test script files were copied, for example C:\TESTPCMC.

2.For machines with one socket, start SSSCR1.CMD. For machines with two sockets, start SSSCR2.CMD.

3.The output is written to the corresponding filenames with a .LOG extension. After executing the command file, all the log files are concatenated and written into the file SSLOG1.

DDTT PCMCIA Socket Services Test Grammar Function Calls

The following are the names of the PCMCIA Socket Services Test Grammar Function Calls:

PCMC_OPEN
PCMC_CLOSE
PCMC_GETADAPTERCOUNT
PCMC_ACKINTERRUPT
PCMC_PRIORHANDLER
PCMC_SSADDR
PCMC_ACCESSOFFSETS
PCMC_GETADAPTER
PCMC_GETSSINFO
PCMC_GETVENDORINFO
PCMC_INQADAPTER
PCMC_SETADAPTER
PCMC_VENDORSPECIFIC
PCMC_GETSOCKET
PCMC_GETSTATUS
PCMC_INQSOCKET
PCMC_RESETSOCKET
PCMC_SETSOCKET
PCMC_GETPAGE
PCMC_GETWINDOW
PCMC_INQWINDOW
PCMC_SETPAGE
PCMC_SETWINDOW
PCMC_GETEDC

PCMC_OPEN

This function opens the PCMCIA$ test device driver.

Input Parameter Keywords: None.

Output Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test

Logged Data: None.

PCMC_CLOSE

This function closes the PCMCIA$ test device driver.

Input Parameter Keywords

|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE         |NUM                 |Drive handle for    |
|                    |                    |PCMCIA device under |
|                    |                    |test                |

Output Parameter Keywords: None.

Logged Data: None.

PCMC_GETADAPTERCOUNT

This function gets the number of adapters supported by Socket Services and the signature "SS".

Input Parameter Keywords

|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|DRIVEHANDLE         |NUM                 |Drive handle for    |
|                    |                    |PCMCIA device under |
|                    |                    |test                |

Output Parameter Keywords: None.

Logged Data: Total number of adapters
Signature "SS"

PCMC_ACKINTERRUPT

This function gets the oldest status change interrupt information from the PCMCIA$ test device driver.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
SOCKET	NUM	Socket number

Output Parameter Keywords: None.

Logged Data: Number of interrupts

PCMC_PRIORHANDLER

This function gets or sets the prior Socket Services handler for the specified adapter.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
MODE	NUM	Function mode where 0 = function performs a GET 1 = function performs a SET

Output Parameter Keywords

Logged Data: Mode ( 0 = Get, 1 = Set )

PCMC_SSADDR

This function gets or sets mode and data area descriptors.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
PROCMODE	NUM	Processor mode where: 00 = Real Mode 01 = 16:16 Protect 02 = 16:32 Protect 03 = 00:32 Protect
FUNCTION	NUM	Requested function where: 0 = Get code and main data segments 1 = Get additional data segments 2 = Set additional data segments (NEEDED FOR SET ONLY)
NUM_SEGS	NUM	Number of additional data segments to GET or SET (NEEDED FOR SET ONLY)

Output Parameter Keywords: None.

Logged Data: Requested function
Number of additional data segments to get or set

PCMC_ACCESSOFFSETS

This function gets an array of offsets for low-level, adapter-specific optimized PC card-access routines.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
PROCMODE	NUM	Processor mode where: 00 = Real Mode 01 = 16:16 Protect 02 = 16:32 Protect 03 = 00:32 Protect
FUNCTION	NUM	Requested function where: 0 = Get code and main data segments 1 = Get additional data segments 2 = Set additional data segments (NEEDED FOR SET ONLY)
NUM_DESIRED	NUM	Number of offsets to be reported, a value between 0 and 18

Output Parameter Keywords: None.

Logged Data: Number of offsets supported

PCMC_GETADAPTER

This function gets the current configuration of the specified adapter.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number

Output Parameter Keywords: None.
Logged Data: Adapter Attributes; IRQ level for status change interrupts

PCMC_GETSSINFO

This function gets the compliance level of the Socket Services interface supporting the specified adapter and identifies the adapters supported.

Input Parameter Keywords:
Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number

Output Parameter Keywords: None.
Logged Data: Compliance
Number of adapters
First adapter

PCMC_GETVENDORINFO

This function gets information about the vendor that implemented the Socket Services for the specified adapter.

Input Parameter Keywords:
Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number

Output Parameter Keywords: None.
Logged Data: Release Number
ASCII string describing the implementer

PCMC_INQADAPTER

This function gets the capability information for the specified adapter.

Input Parameter Keywords

|Keyword         |Type     |Description
|----------------+---------+-------------------
|DRIVEHANDLE     |NUM      |Drive handle for
|                |         |PCMCIA device under
|                |         |test
|----------------+---------+-------------------
|ADAPTER         |NUM      |Adapter number

Output Parameter Keywords: None.

Logged Data: Number of sockets
Number of windows
Number of EDCS
Contains the information on the adapter capabilities, the IRQ state and level, and the power management specifications.

PCMC_SETADAPTER

This function sets the configuration of the specified adapter.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
ADPSTATE	NUM	Adapter attributes where: Bit 0 = Reduce power consumption (1 = True) Bit 2 = Preserve State Information (1 = Preserve) All other bits are reserved and must be zero.
IRQ	ALNUM	IRQ level to use for status change interrupts (if bit 7 is enabled)

Output Parameter Keywords: None.
Logged Data: None.

PCMC_VENDORSPECIFIC

This function defines a vendor-specific function for implementing proprietary functions.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
SUBFUNCTION	NUM	Subfunction codes where: 1 = InquireBootSocket 2 = UnlockBootSocket

Output Parameter Keywords: None.
Logged Data: None.

PCMC_GETSOCKET

This function gets the current configuration of the specified socket.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
SOCKET	NUM	Socket Number

Output Parameter Keywords: None.
Logged Data: Interrupt Mask; Vcc Level; Vpp Level; Socket State variables; Socket Control Variables; IRQ level and status change interrupts

PCMC_GETSTATUS

This function gets the status of the card in the specified socket on the specified adapter.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
SOCKET	NUM	Socket Number

Output Parameter Keywords: None.
Logged Data: Card Attributes; Socket State; Control and Indicator State; IRQ level and status change interrupts

PCMC_INQSOCKET

This function gets the capability information for the specified socket.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
SOCKET	NUM	Socket Number

Output Parameter Keywords: None.

Logged Data: Interrupt Capabilities
Reporting Capabilities
Control Capabilities
Socket Characteristics

PCMC_RESETSOCKET

This function resets the PC card in the specified socket.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
SOCKET	NUM	Socket Number

Output Parameter Keywords: None.
Logged Data: None.

PCMC_SETSOCKET

This function sets the configuration for the specified socket.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
SOCKET	NUM	Socket Number
INTERRUPTMASK	ALNUM	Status change interrupt mask where: Bit 0 = Write Protect Change (must be zero) Bit 1 = Card Lock Change (must be zero) Bit 2 = Ejection Request (set = enable for PS/2-E) Bit 3 = Insertion Request (must be zero) Bit 4 = Battery Dead Change (set = enabled) Bit 5 = Battery Warning Change (set = enabled) Bit 6 = Ready Change (set = enabled) Bit 7 = Card Detect Change (set = enabled)
VCCLEVEL	NUM	Lower nibble - Vcc Level
VPPLEVEL	NUM	Upper Nibble - Vpp Level, Lower Nibble - Vpp2 Level
SOCKETSTATE	NUM	Socket state where: Bit 0 = Write Protect Change Bit 1 = Card Lock Change Bit 2 = Ejection Request(For PS/2-E) Bit 3 = Insertion Request(must be zero) Bit 4 = Battery Dead Change Bit 5 = Battery Warning Change Bit 6 = Ready Change Bit 7 = Card Detect Change
SOCKETCONTROL	NUM	Socket Control where: Bit 4 = Lock Control(PS/2-e only) Bit 6 = Busy Status All other bits are reserved and are set to zero
IFIRQ	ALNUM	IRQ Steering and Interface Type Control where: Bit 0..3 = IRQ Level (0..15) (16..19 must be zero) Bit 4 = Reserved (always zero) Bit 5 = Reserved (always zero) Bit 6 = IRQ Inverter enabled (set to one = enable) Bit 7 = IRQ Steering enabled (set to one = enable) Bit 8 = Memory only interface (mutually exclusive of I/O and Memory interface) Bit 9 = I/O and Memory interface (mutually exclusive of Memory only interface) All other bits are reserved and are set to zero

Output Parameter Keywords: None.
Logged Data: None.

PCMC_GETPAGE

This function gets the current configuration of the specified page in the specified window.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
WINDOW	NUM	Window Number
PAGE	NUM	Page number

Output Parameter Keywords: None.
Logged Data: Page Attributes; Offset

PCMC_GETWINDOW

This function gets the current configuration of the specified window on the specified adapter.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
WINDOW	NUM	Window Number

Output Parameter Keywords: None.
Logged Data: Socket; Window Size; Window Attributes; Access speed; Window Base Address

PCMC_INQWINDOW

This function gets the capability information for the specified window on the specified window.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
WINDOW	NUM	Window Number

Output Parameter Keywords: None.
Logged Data: Capabilities
Assignable Sockets

PCMC_SETPAGE

This function sets the configuration for the specified page in the specified window.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
WINDOW	NUM	Window Number
PGSTATE	NUM	Page Attributes where. Bit 0 set = Attribute Memory, reset = Common Memory Bit 1 set = Enable, reset = Disable All other bits are reserved and must be set to zero
OFFSET	NUM	4KB units

Output Parameter Keywords: None.
Logged Data: None.

PCMC_SETWINDOW

This function sets the configuration for the specified window.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
WINDOW	NUM	Window Number
SOCKET	NUM	Socket number
SIZE	ALNUM	Number of bytes for I/O, number of 4KB units for memory
WINSTATE	NUM	Window State where: Bit 0 set = Memory, reset = I/O Bit 1 set = Enabled, reset = Disabled Bit 2 set = 16-bit, reset = 8-bit All other bits are set to zero
SPEED	NUM	Actual access speed 1 = 250nSec Only speed supported
BASE	ALNUM	Base address where: 0x00A0 - First Byte addressable 0x00FF - Last Byte addressable

Output Parameter Keywords: None.
Logged Data: None.

PCMC_GETEDC

This function gets the current configuration of the specified EDC generator.

Input Parameter Keywords

Keyword	Type	Description
DRIVEHANDLE	NUM	Drive handle for PCMCIA device under test
ADAPTER	NUM	Adapter number
EDC	NUM	EDC generator number

Output Parameter Keywords: Socket
State
Type

Description of Test Cases

Each of the PCMCIA Socket Services test cases can be executed individually as previously described. The corresponding test scripts are described below. You can create additional tests or combine tests into multi- threaded test cases after becoming familiar with the DDTT and the PCMCIA grammar files.

All test scripts close the channels opened to the PCMCIA device and verify successful status return from every exercised API. All test scripts log information to a log file with the same file name and a file name extension .LOG. When current status is queried (for example, track, channel, or drive), this data is written to the DDTT's output windows and to the log file. Log files can be examined after the test case has completed.

ACKINT.SCR Gets the number of Status Change Interrupts from the test device driver since the last time ACKINT was called. The count is reset to zero.

ADAPTER.SCR Calls the SetAdapter function with different values for State and IRQ. SetAdapter sets the configuration for the specified adapter. Each time the SetAdapter function is called, the GetAdapter function is also called to verify the configuration.

GETAOFS.SCR Gets an array of offsets for low-level, adapter-specific, optimized PC-card access routines. Can return UNSUPPORTED FUNCTION.

GETADP.SCR Gets the current configuration of the specified adapter,

GTADPCT.SCR Gets the number of adapters supported by Socket Services and the Signature "SS".

GETEDC.SCR Gets the current configuration of the specified EDC generator. Can return UNSUPPORTED FUNCTION.

GETPAGE.SCR Gets the current configuration of the specified memory page in the specified window.

GETSOC.SCR Formats the information and sends it to the log file.

GTSSINF.SCR Gets the compliance level of the Socket Services interface supporting the specified adapter and identifies the adapters supported.

GETSTAT.SCR Gets the status of the card in the specified socket on a specified adapter.

GTVNINF.SCR Gets information about the vendor that implemented the Socket Services for the specified PCMCIA adapter.

GETWIN.SCR Gets the current configuration of the specified memory window on the specified adapter.

GSPRHND.SCR Gets the prior Socket Services handler for the specified socket . Can return UNSUPPORTED FUNCTION.

GSSSADR.SCR Gets or sets mode and data area descriptors.

INQADP.SCR Gets the capability information for the specified adapter.

INQSOC.SCR Gets the capability information for the specified socket.

INQWIN.SCR Gets the capability information for the specified window on the specified adapter.

INTRUPT.SCR Calls the AckInterrupts function after various combinations of insert and remove operations on the socket. The AckInterrupts function gets the oldest Status Change Interrupt information from the test version of the PCMCIA$ device driver.

Note:Each call to AckInterrupts from the test IOCtl resets the current count of interrupts. This count is kept and reported for diagnostic purposes only.

MAXPAGE.SCR Calls the GetPage function with different values for the Window number. GetPage gets the current configuration for the specified Page.

MAXWIN.SCR Calls the GetWindow function with different values for the Window number. GetWindow gets the current configuration for the specified Window.

RSETSOC.SCR Resets the PC card in the specified socket.

Note:There must be a card in the socket to call this function successfully.

SETADP.SCR Sets the configuration of the specified adapter.

SETPAGE.SCR Sets the configuration for the specified page in the specified window.

SETSOC.SCR Sets the configuration for the specified socket.

SETWIN.SCR Sets the configuration for the specified memory window.

SETWP.SCR Calls the SetWindow and SetPage functions with different values. After setting the values it calls GetWindow and GetPage to verify configuration.

VNSPEC.SCR Defines a vendor-specific function for implementing proprietary functions. Can return UNSUPPORTED FUNCTION.

WINDOW.SCR Calls the SetWindow function with different combinations of values for Base, Window and Size. SetWindow sets the configuration for the specified Window. Each time the SetWindow function is called, GetWindow function is called before and after the SetWindow to compare the configuration.

OS/2 Version Compatibility Considerations=

The following table lists any items discussed in this reference that have been added to OS/2 since OS/2 Warp Version 3.0 and discusses their compatibility with different versions of OS/2.

Item Added or Changed	Date Item Added or Changed	Compatibility of Addition or Change
Joystick Driver	November 1995	OS/2 Warp, Version 3.0 and Later

Notices

IBM Developer Connection Device Driver Kit for OS/2, Version 4.02 Edition ( September 1997)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.

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 1997. 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

Multimedia Presentation Manager/2

OS/2

Ultimotion

The following terms are trademarks of other companies:

Helvetica Linotype Company

MASM Microsoft Corporation

Mitsumi Mitsumi Denki Kabushki Kaisha

Panasonic Matsushita Electric Industrial Co., Ltd.

OPTi OPTi, Inc.

Pioneer Pioneer Electric Corporation

ProAudio Spectrum Media Vision, Inc.

ProAudio Spectrum 16 Media Vision, Inc.

QuickVia Jovian Logic Corp.

ReelMagic Sigma Designs, Inc.

Sound Blaster Creative Technology Ltd.

SuperVia Jovian Logic Corp.

Super VideoWindows New Media Graphics Corporation

Video Blaster Creative Technology, Inc.

Yamaha Yamaha Corporation

Windows is a trademark of Microsoft Corporation.

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited.

Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.

Glossary

IBM SDK/DDK Glossary