DevHelp MonWrite

This service passes data records to the monitors for filtering.

Syntax

C

USHORT APIENTRY DevHelp_MonWrite (USHORT MonitorHandle,
                                  PBYTE  DataRecord,
                                  USHORT Count,
                                  ULONG Time StampMS,
                                  USHORT WaitFlag)

Assembler

LDS   SI,data_record_offset     ; Offset of data record in DS
MOV   CX,count                  ; Byte count of data record
MOV   AX,monitor_handle         ; Handle for chain returned from
                                ; Previous MonitorCreate call
MOV   DI,millisecond_high       ; High word of milliseconds
MOV   BX,millisecond_low        ; Low word of milliseconds
MOV   DH,wait_flag              ; Wait/No-Wait/WAIT_TIMEOUT flag
MOV   DL,DevHlp_MonWrite
CALL  [Device_Help]

Parameters

C

MonitorHandle (USHORT)

Handle for chain returned from MonitorCreate.

DataRecord (PBYTE)

Offset of data record.

Count (USHORT)

Byte count of data record.

WaitFlag (USHORT)

Wait/No_WaitFlag -

0=Wait infinite timeout
2=No Wait

TimeStampMS (ULONG)

Input - Synchronization time in milliseconds for monitor dispatcher.

Assembler

LDS   SI,data_record_offset     ; Offset of data record in DS
MOV   CX,count                  ; Byte count of data record
MOV   AX,monitor_handle         ; Handle for chain returned from
                                ; Previous MonitorCreate call
MOV   DI,millisecond_high       ; High word of milliseconds
MOV   BX,millisecond_low        ; Low word of milliseconds
MOV   DH,wait_flag              ; Wait/No-Wait/WAIT_TIMEOUT flag
MOV   DL,DevHlp_MonWrite

Return Code

C

Success Indicator: 0

Possible errors:

              ERROR_MON_INVALID_HANDLE (381)
              ERROR_NOT_ENOUGH_MEMORY  (8)
              ERROR_INTERRUPT          (95)
              ERROR_SEM_TIMEOUT        (121)

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

Assembler

   'C' Clear if successful.
       AX = 0.

   'C' Set if error.
       AX = Error code.
            Possible errors:
               ERROR_MON_INVALID_HANDLE   (381)
               ERROR_NOT_ENOUGH_MEMOR     (8)
               ERROR_INTERRUPT            (95)
               ERROR_SEM_TIMEOUT          (121)
               Invalid parms error is returned if the monitor chain
               is not empty.

Remarks

MonWrite can be called at task time or interrupt time, in either the OS/2 session or DOS session. Wait_flag is set to 0 if the MonWrite request occurs at task or user time and the device driver indicates that the monitor dispatcher does the synchronization. That is, the physical device driver waits until the data can be placed into the monitor chain before the monitor dispatcher returns to the physical device driver. If wait_flag is set to 1, the physical device driver does not wait, and if the data cannot be placed into the monitor chain, the monitor dispatcher returns immediately with the appropriate error. Wait_flag must be set to 1 if the MonWrite request occurs at interrupt time. Wait_flag is set to 2 if the MonWrite request occurs at task or user time and the physical device driver indicates that the monitor dispatcher will do the synchronization for the time (in milliseconds) specified in DI:BX.

The DS register must be set to the data segment of the physical device driver.

The error ERROR_NOT_ENOUGH_MEMORY is returned to the physical device driver when the MonWrite call is made and the monitors are not able to receive the data. If this condition occurs at interrupt time, an overrun occurred. If it occurs at task (or user) time, the process can block. This error is also returned to the physical device driver when a flush record, sent to the monitors by a previous MonFlush call, is not returned to the physical device driver.

If the thread on which the physical device driver calls MonWrite blocks and is awakened because the process that owns the thread is terminating, a call-interrupted error is returned to the physical device driver. The physical device driver must return the error to the calling process so that the process can complete its termination processes.

Each call to MonWrite sends a single complete record. The data sent by this call is considered to be a complete record. A data record must not be longer than two bytes minus the length of the device driver's monitor chain buffer.

The state of the interrupt flag is not preserved across calls to DevHlp_MonWrite.

Example Code

C

#include  "dhcalls.h"

USHORT APIENTRY DevHelp_MonWrite (USHORT MonitorHandle,
                                  PBYTE  DataRecord,
                                  USHORT Count,
                                  ULONG Time StampMS,
                                  USHORT WaitFlag)