## Physical Device Driver Reference

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

### DosMonRead

After an application has registered as a monitor for a device, it can take data from the data stream for filtering by calling DosMonRead. DosMonRead has three primary actions:

1.Wait (optionally) for a signal from the monitor dispatcher that data is available to be read.
2.Move that data from the data stream into a private data area where it can be accessed freely by the monitor for filtering.
3.Signal the monitor dispatcher that data has been removed from the data stream.

The parameters for DosMonRead are shown in the table below. The address parameters are selector:offset addresses of the following data areas within its address space:

The input buffer address previously registered with the monitor chain for the device
A private data area into which the data record read from the data stream is to be placed
A Byte Count variable that on entry indicates the size of the private data area, and on exit indicates the size of the data record read from the data stream

In addition, the application can specify whether to block (wait) if no data is available in the data stream

    /-------------------------------------------------------------\

    |Parameter Description         |Size                          |

    |------------------------------+------------------------------|

    |Address of Monitor's Input    |DWORD                         |

    |Buffer                        |                              |

    |------------------------------+------------------------------|

    |Waitflag                      |WORD                          |

    |------------------------------+------------------------------|

    |Address of Private Data Area  |DWORD                         |

    |------------------------------+------------------------------|

    |Address of Byte Count Variable|DWORD                         |

    \-------------------------------------------------------------/

For each DosMonRead call, a single data record is taken from the data stream and is placed into the monitor's private data area for filtering. A monitor data record is constructed by the physical device driver. It consists of a flag WORD, that can be followed by actual device data. Monitor data records are variable length (that is, some consist only of a flag WORD, while some consist of a flag WORD followed by actual device data of differing lengths). The maximum length of a monitor data record passing through a monitor chain is the length of the device driver's monitor chain buffer minus 2 bytes.

The physical device driver uses flags within the flag WORD to indicate the type of data that is part of this data record. The device driver also uses flags to indicate the action it expects its monitors to take when this data record is received. In addition, physical device drivers have specific requirements for the return of data records to the data stream. Because of this, character device monitors must not indiscriminately consume data records from the data stream. See the chapters on the individual character device drivers for descriptions of their monitor records and expected actions.

Flushing a data stream is an important operation. At certain times it is necessary to guarantee that all data is removed from the data stream. At these times, a specially marked record called a flush record is placed into the data stream by the physical device driver and must pass through all monitors in the chain. The flush data record consists of a single flag WORD, with the third bit of the first byte set. It is the only data record created by the monitor dispatcher, and it is placed into a monitor chain by the monitor dispatcher for the physical device driver. See MonFlush for more information. When a flush record is received by a monitor, the monitor must return the record to the data stream by calling DosMonWrite after taking the appropriate action. The action to be taken in response to the flush record varies with the type of device and type of support required. To guarantee that all data has been removed from all buffers in the monitor chain, the monitor dispatcher prevents the character device driver from placing additional data into the data stream until the flush record has passed through all monitors in the monitor chain.

Note: If the flush record is not returned to the data stream, the data stream will be severely and permanently affected.

Separate monitor threads from the same application can call DosMonRead to take data from the data stream. To protect the data stream during data movement, the monitor dispatcher guarantees that only one thread at a time from a single process can take data from the data stream. Therefore, the application does not have to synchronize calls to DosMonRead made by its separate threads.

If a monitor thread calls DosMonRead during monitor termination (for example, DosMonClose has been called from another thread belonging to the same application), it will receive an error return indicating that there is no data present in the data stream. If a monitor thread is blocked on a call to DosMonRead when monitor termination begins, it will be awakened and receive the same error return. In both cases, the monitor thread must handle the error return code. The application is responsible for the orderly termination of its individual monitor threads.