## Physical Device Driver Reference

[prev][next][parent][TOC]

### Monitor Buffers

Applications allocate their own monitor input and output buffers. A monitor input/output buffer pair must be allocated from the same segment. Before registering the monitor with a monitor chain belonging to a character device driver, the application is required to provide the size of its private data area (plus 20 bytes) in the first WORD of each buffer.

If ERROR_MON_BUFFER_TOO_SMALL is returned from the call to DosMonReg, the second WORD will contain the size of the character monitor buffer of the physical device driver.

The registered input and output buffers must be at least two WORDs (4 bytes ) in length. These buffers can be discarded after the call to DosMonReg. The monitor dispatcher does not use the registered input and output buffers after monitor registration, but their addresses must be passed as parameters to the DosMonRead and DosMonWrite API functions. The address is used as a handle to determine which monitor is calling the API.

More than one application can monitor the same data stream. Monitors belonging to separate applications can have private buffers of various sizes. To guarantee data movement through a monitor chain, the monitor dispatcher defines a minimum monitor buffer length. This length is defined as the length of the character device driver's monitor chain buffer. The length specified in a monitor's input and output buffers must be at least this length plus 20 bytes. This is the recommended length of the private data area specified on a call to DosMonRead.

Because a monitor chain buffer is defined and owned by a character device driver, its length is documented in the descriptions of the individual device drivers that support monitors. Refer to the OS/2 Input/Output Device Driver Reference for more information about the physical keyboard device driver, the physical mouse device driver, and the physical parallel port device driver for this information.

A character device driver will be called with a deinstall request packet if another device driver with the same name is loaded. Character device drivers are deinstalled by a loadable device driver when specified with a DEVICE= statement in CONFIG.SYS. The new loadable device drivers can implement the monitor buffer with a different size than the base physical device drivers. Character monitors must know the size of the character monitor buffer of the physical device driver in order to allocate their private data areas. The private data areas must be at least as large as the character monitor buffer of the physical device driver.

The character device monitor can issue DosMonReg first with a 4-byte buffer (the first two bytes containing the total length 4, and the second two bytes initialized to zero). On return from the call to DosMonReg, the second WORD of the 4-byte buffer will contain the size of the character monitor buffer of the physical device driver. The advantage of this approach is that the physical device driver can optimize the size of the character monitor buffer, and the character monitor can dynamically determine the buffer size. The character monitor then allocates the buffer size of the device driver, and re-issues the call to DosMonReg, replacing the first WORD of the input and output buffer with the length of the private data area plus 20 bytes.