Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►  ◄Changes►               ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSQUEUES
 
USHORT DosWriteQueue(hqueue, usRequest, cbBuf, pbBuf, usPriority)
HQUEUE hqueue;       /* target-queue handle                     */
USHORT usRequest;    /* request/identification data             */
USHORT cbBuf;        /* number of bytes to write                */
PBYTE pbBuf;         /* pointer to buffer with element to write */
UCHAR usPriority;    /* priority of element to write            */
 
The DosWriteQueue function writes an element to the specified queue. The
position of the element in the queue is determined by the value specified in
the fQueueOrder parameter of the DosCreateQueue function when the queue was
created; if this parameter was set to 0x0002 (priority queue), the
usPriority parameter of the DosWriteQueue function can be used to set the
priority of the element. After the element is written, the process that owns
the queue can read the element by using the DosPeekQueue or DosReadQueue
function.
 
Parameter   Description
────────────────────────────────────────────────────────────────────────────
 
hqueue      Identifies the queue to be written to. This handle must have
            been created or opened by using the DosCreateQueue or
            DosOpenQueue function.
 
usRequest   Specifies a program-supplied event code. MS OS/2 does not use
            this field; it is reserved for the program's use. The queue
            owner can retrieve this value by using the DosPeekQueue or
            DosReadQueue function.
 
cbBuf       Specifies the number of bytes to be copied from the buffer
            pointed to by the pbBuf parameter.
 
pbBuf       Points to the buffer that contains the element to be written to
            the queue.
 
usPriority  Specifies the element priority. This parameter can be any value
            from 0 through 15; 15 is the highest priority.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_QUE_INVALID_HANDLE
     ERROR_QUE_NO_MEMORY
 
Comments
 
The DosWriteQueue function returns an error value if the queue has been
closed by the process that owns it.
 
If the queue owner uses a RAM semaphore to notify it when elements are added
to the queue, the semaphore must be shared. If the notifying semaphore is a
system semaphore, the writing process must have opened the semaphore by
using the DosOpenSem function.
 
Example
 
This example opens a queue called \queues\queuename. In order to write to
the queue, the process allocates shared memory, gives the memory to the
queue owner, copies data to the shared memory, and calls DosWriteQueue. The
process then frees the shared memory. The queue owner must also free the
shared memory before it becomes available to the system again. For more
information, see DosReadQueue.
 
PID pidOwner;
SEL sel, selRecipient;
 
DosOpenQueue(&pidOwner, &hqueue,
    "\\queues\\queuename");                /* opens queue             */
DosAllocSeg(512, &sel, SEG_GIVEABLE);      /* allocates shared memory */
DosGiveSeg(sel, pidOwner, &selRecipient);  /* gives it to queue owner */
    .
    . /* Copy the data to the shared memory segment. */
    .
       DosWriteQueue(hqueue,    /* queue handle                */
           0,                   /* request data                */
           11,                  /* length of data              */
    MAKEP(selRecipient, 0),     /* data buffer                 */
           0);                  /* element priority            */
       DosFreeSeg(sel);         /* frees shared memory segment */
 
See Also
 
DosCreateQueue, DosOpenQueue, DosOpenSem, DosPeekQueue, DosReadQueue
 
                                      ♦