Writing to a Queue

The server process and any of its threads can add an element to a queue simply by calling DosWriteQueue. A client process, however, must first request access to the queue by calling DosOpenQueue.

Processes that communicate by passing the addresses of shared memory objects through the queue must have a shared memory object that they each have access to. Once a process opens the queue, it can allocate shared memory by using DosAllocMem with the OBJ_GIVEABLE attribute and then give the shared memory to the queue owner with DosGiveSharedMem.

A process that has opened a queue can write to the queue by using DosWriteQueue. The writing process must create elements in a form that the queue owner can read.

The following code fragment adds an element to a queue. Assume that the caller has placed the handle of the queue into QueueHandle already. Assume also that DataBuffer has been set to point to a data element in shared memory, and that DataLength has been set to contain the length of the data element in shared memory.

    #define INCL_DOSQUEUES   /* Queue values */
    #include <os2.h>
    #include <stdio.h>

    HQUEUE   hqQueueHandle;   /* Queue handle                         */
    ULONG    ulRequest;       /* Request-identification data          */
    ULONG    ulDataLength;    /* Length of element being added        */
    PVOID    pDataBuffer;     /* Element being added                  */
    ULONG    ulElemPriority;  /* Priority of element being added      */
    APIRET   ulrc;            /* Return code                          */

    ulRequest = 0;            /* Assume that no special data is being */
                              /* sent along with this write request   */

    ulElemPriority = 0;       /* For priority-based queues: add the   */
                              /* new queue element at the logical end */
                              /* of the queue                         */

    ulrc = DosWriteQueue(hqQueueHandle,
                         ulRequest,
                         ulDataLength,
                         pDataBuffer,
                         ulElemPriority);

    if (ulrc != 0) {
        printf("DosWriteQueue error: return code = %ld",
               ulrc);
        return;
    }

Once the process has written to the queue, it frees the shared memory. However, the memory will not be freed until the queue owner also frees it.

If the queue was created as a priority-based queue (as specified in the QueueFlags parameter of DosCreateQueue), then the priority of the element that is being added must be specified.

If the server process has ended, or if it has closed the queue before DosWriteQueue is called, then ERROR_QUE_INVALID_HANDLE is returned.