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