## Physical Device Driver Reference

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

### Well-Behaved Monitor Applications

A monitor application should be well-behaved so that data loss is minimal and system performance is not affected. The following characteristics are typical of well-behaved monitor applications:

Separate threads intercept data from the data stream (call DosMonRead), and return filtered data to the data stream (call DosMonWrite).

Device monitor rules are followed, as defined by the monitor dispatcher and the individual character device driver whose data stream is being monitored. This includes definition of data streams, format of data records passing through the monitor chain, flags and expected actions, and consumption of data records.

Error handling procedures exist for each function call.

Semaphores and shared memory are used carefully so that blockages do not occur because of the monitor application. If not used carefully, the entire data stream can be blocked.

Data monitoring is terminated before DosMonClose is called (that is, all DosMonRead and DosMonWrite threads issue no more calls before DosMonClose).

Signal handler or exitlist routines are included to coordinate the closing of monitor threads in an orderly manner.

A well-behaved, multi-threaded character device monitor is represented by the pseudocode in the following three figures:

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

                    Application's Data

    Define device-specific data:

      Device name string (8 ASCII characters, with NULL at end)
      Index (indicating data stream to be monitored)
      Length of monitor chain buffer (minimum buffer size for all
        monitor buffers in monitor chain)
      Monitor input buffer (4 bytes)
      Monitor output buffer (4 bytes)

    Define monitor data areas (the size of each of these areas is
      based on the size of the device driver's monitor chain
      buffer for the data stream monitored):

      Private data area

    Define additional monitor data:

      Device handle (returned from DosMonOpen call)
      Byte count variable (size of data record received by
        DosMonRead and returned by DosMonWrite)
      Wait flag (wait for DosMonRead?)

    Define a RAM semaphore to synchronize monitor threads:

      Semaphore A

    Define a variable to track error returns from DosMonRead and
      DosMonWrite:

      SetError

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

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

              An Application's Main Routine:

      CALL DosMonOpen to open the device and get a monitor handle
        for the device.
      CALL DosSetPrty to set the priority of the monitor thread high.
      CALL DosMonReg to register a monitor for the data stream of
        the device.
      CALL DosSemSet to set RAM Semaphore A, which is used to
        synchronize termination of the application.
      CALL DosCreateThread to create a separate thread that
       executes the application's monitor routine.
      CALL DosSemWait to wait for RAM Semaphore A to be cleared by
        the application's child thread executing the monitor
        routine.
      CALL DosMonClose to terminate the monitor and close the
        device handle.
      CALL DosExit to terminate this application.

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

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

              An Application's Monitor Routine:

    WHILE SetError = 0, the application's child thread will
      execute as long as there are no errors returned from calls
      to DosMonRead or DosMonWrite

      CALL DosMonRead to take a data record from the data stream

      SetError = error returned from DosMonRead

        IF SetError = 0, THEN no error was returned from
          DosMonRead; continue.

           Filter the data.
           CALL DosMonWrite to return the filtered data to the
             data stream
           SetError = error return from DosMonWrite

        ENDIF

    END WHILE

      CALL DosSemClear to clear RAM Semaphore A to signal parent
        thread that monitoring of data stream has been completed
      CALL DosExit to terminate only this thread

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