DevHelp MonitorCreate

This service creates an empty chain of monitors or removes an empty chain of monitors.

Syntax

C

USHORT APIENTRY DevHelp_MonitorCreate (USHORT  MonitorHandle,
                                       PBYTE   FinalBuffer,
                                       NPFN    NotifyRtn,
                                       PUSHORT MonitorChainHandle);

Assembler

LES   SI,final_buffer     ; Address of device driver's monitor chain buffer
LDS   DI,notify_rtn       ; Address of notification routine
MOV   AX,Handle           ; Handle for this chain
                          ;  0 = create new monitor chain
                          ; !0 = specifies chain to be removed
                                  (returned from previous create call)
MOV   DL,DevHlp_MonitorCreate

CALL  [Device_Help]

Parameters

C

MonitorHandle (USHORT)  

input - 0 if new handle

FinalBuffer (PBYTE)  

input - Far pointer to final buffer

NotifyRtn (NPFN)  

input - Near pointer to notification routine

MonitorChainHandle (PUSHORT)  

output- Returned chain handle

Assembler

LES   SI,final_buffer     ; Address of device driver's monitor chain buffer
LDS   DI,notify_rtn       ; Address of notification routine
MOV   AX,Handle           ; Handle for this chain
                          ;  0 = create new monitor chain
                          ; !0 = specifies chain to be removed
                                  (returned from previous create call)
MOV   DL,DevHlp_MonitorCreate

Return Code

C

Success indicator: 0

Possible errors:

  ERROR_MON_INVALID_HANDLE (381)
  ERROR_NOT_ENOUGH_MEMORY  (8)
  ERROR_MON_INVALID_PARMS  (379)

Invalid parms error is returned if the monitor chain is not empty.

Assembler

   'C' Clear if successful.
       AX = Monitor chain handle, if Handle was "0".
       AX = 0, if handle was not "0".

   'C' Set if error.
       AX = Error code.
            Possible errors:
               ERROR_MON_INVALID_HANDLE (381)
               ERROR_NOT_ENOUGH_MEMORY  (8)
               ERROR_MON_INVALID_PARMS  (379)
               Invalid parms error is returned if the monitor chain
               is not empty.

Remarks

This service can be called only at task time in the OS/2 mode. If this function is called in a DOS session context, an invalid parameter error is returned to the physical device driver.

The monitor chain buffer, final_buffer, is owned by the physical device driver. When MonitorCreate is called, the first WORD of this buffer is the length of the buffer in bytes (including the first WORD). When the monitor chain handle specified is 0, a new monitor chain is created. When the monitor chain handle specified is a handle that was previously returned from a call to MonitorCreate (that is, the handle does not equal 0), the monitor chain referenced by that handle is destroyed.

A monitor chain is a list of monitors, with a device driver monitor chain buffer address and code address as the last element on this list. Data is placed into a monitor chain through the MonWrite function. The monitor dispatcher feeds the data through all registered monitors, putting the resulting data, if any, into the specified device driver monitor chain buffer. When data is placed in this buffer, the physical device driver's notification routine is called at task time. The physical device driver should initiate any necessary action in a timely fashion and return from the notification entry point without delay.

Note: If MonWrite is called at interrupt time and the monitor chain is empty, the device driver notification routine is called at interrupt time. Under all other circumstances, it is called at task time.

MonitorCreate establishes one of these monitor chains. The chains are created empty so that data written into them is placed immediately into the buffer of the physical device driver. This service can also destroy a monitor chain if the handle parameter (AX) is nonzero. The nonzero value is the handle of the chain to remove. If the monitor chain to be removed is not empty (that is, all monitors registered with this chain have not been previously deregistered), an invalid parameter error is returned to the physical device driver.

A call to MonitorCreate must be made before a monitor can be registered (using the Register DevHlp service) with the chain. This can be done at any time, including during the installation of the device driver at system initialization.

The following are notification routine considerations:

• The physical device driver's notification routine, notify_rtn, is called by the monitor dispatcher when a data record has been placed in the monitor chain buffer of the device driver. The monitor dispatcher sets ES:SI to the address of the device driver's monitor chain buffer and DS to the physical device driver's DS, before calling the notification routine.

• The physical device driver must process the contents of the monitor chain buffer before returning to the monitor dispatcher. This entry point is called in the OS/2 mode only.

• When notify_rtn is called, the first WORD of the buffer is filled in with the length of the record just sent to the device driver. There is one notification routine call for each record.

• final_buffer must reside within the first data segment of the physical device driver (that is, the physical device driver's header segment). notify_rtn must reside in the first code segment of the physical device driver.

Example Code

C

#include  "dhcalls.h"

USHORT APIENTRY DevHelp_MonitorCreate (USHORT  MonitorHandle,
                                       PBYTE   FinalBuffer,
                                       NPFN    NotifyRtn,
                                       PUSHORT MonitorChainHandle);