DosWriteQueue (OS/2 1.x)

This call adds an element to a queue.

Syntax

DosWriteQueue (QueueHandle, Request, DataLength, DataBuffer, ElemPriority)

Parameters

QueueHandle (HQUEUE) - input

Queue handle.

Request (USHORT) - input

A value to be passed with the queue element. This word is used for event encoding by the specific application.

DataLength (USHORT) - input

Length of the data being sent to the queue.

DataBuffer (PBYTE) - input

Address of the data buffer where data, that is to be placed in the queue, is located.

ElemPriority (UCHAR) - input

Priority of the element being added to the queue. If the priority is specified as 15, the element is added to the top of the queue (that is, in LIFO order). If the priority is specified as 0, the element is added as the last element in the queue (that is, in FIFO order). Elements with the same priority are in FIFO order. This parameter is valid for priority-type queues only.

Return Code

rc (USHORT) - return

Return code descriptions are:

• 0 NO_ERROR
• 334 ERROR_QUE_NO_MEMORY
• 337 ERROR_QUE_INVALID_HANDLE

Remarks

DosWriteQueue adds entries to a specified queue.

The Request, DataLength and DataBuffer parameters contain data understood by the thread adding the element to the queue and by the thread that receives the queue element. There is no special meaning to this data; applications may use these parameters for any purpose they wish. OS/2 does not alter this data; it simply copies this data intact. OS/2 does not validate the address of DataBuffer or the DataLength.

If the queue owner has defined a semaphore for use in its notification when elements are added to the queue and if that semaphore is a RAM semaphore, then that semaphore must be in a segment which is shared among both the queue owner's process and this process. If that semaphore handle is for a system semaphore, then that semaphore must be opened by this process before making a DosWriteQueue request to the queue.

If the owning process is terminated, or if the queue is closed before this request is issued, ERROR_QUE_INVALID_HANDLE is returned.

If the owning process invokes a system semaphore when DosReadQueue or DosPeekQueue is issued, other processes that issue DosWriteQueue must first issue DosOpenSem to access the system semaphore.

Example Code

C Binding

#define INCL_DOSQUEUES

USHORT  rc = DosWriteQueue(QueueHandle, Request, DataLength, DataBuffer,
                             ElemPriority);

HQUEUE           QueueHandle;   /* Queue handle */
USHORT           Request;       /* Request identification data */
USHORT           DataLength;    /* Length of element being added */
PBYTE            DataBuffer;    /* Element being added */
UCHAR            ElemPriority;  /* Priority of element being added */

USHORT           rc;            /* return code */

MASM Binding

EXTRN  DosWriteQueue:FAR
INCL_DOSQUEUES      EQU 1

PUSH   WORD    QueueHandle   ;Queue handle
PUSH   WORD    Request       ;Request identification data
PUSH   WORD    DataLength    ;Length of element being added
PUSH@  OTHER   DataBuffer    ;Element being added
PUSH   WORD    ElemPriority  ;Priority of element being added
CALL   DosWriteQueue

Returns WORD