The queue owner (server process) and its threads can read an element from the queue by using DosReadQueue. The owner can read the first element in the queue by specifying 0 as the element number. Alternatively, the owner can read a particular element in the queue by specifying an element code returned from DosPeekQueue. This function is not available to client processes.
DosReadQueue can either remove queue elements in the order that was specified when the queue was created (FIFO, LIFO, or priority), or it can use an element identifier from DosPeekQueue as input to remove a previously examined element.
The following code fragment reads an element from the queue. Assume that the caller has placed the handle of the queue into QueueHandle already and that the identifier of the process that owns the queue has been placed into OwningPID already.
#define INCL_DOSQUEUES /* Queue values */ #include <os2.h> #include <stdio.h> HQUEUE hqQueueHandle; /* Queue handle */ REQUESTDATA rqRequest; /* Request-identification data */ ULONG ulDataLength; /* Length of element received */ PULONG pulDataAddress; /* Address of element received */ ULONG ulElementCode; /* Request a particular element */ BOOL32 bNoWait; /* No wait if queue is empty */ BYTE bElemPriority; /* Priority of element received */ HEV hevSemHandle; /* Semaphore handle */ PID pidOwningPID; /* PID of queue owner */ APIRET ulrc; /* Return code */ rqRequest.pid = pidOwningPID; /* Set request data block to indicate */ /* queue owner */ ulElementCode = 0; /* Indicate that the read should start */ /* at the front of the queue */ bNoWait = 0; /* Indicate that the read should wait */ /* if the queue is currently empty */ hevSemHandle = 0; /* Unused since this is a call that */ /* waits synchronously */ ulrc = DosReadQueue(hqQueueHandle, &rqRequest, &ulDataLength, (PVOID *) &pulDataAddress, ulElementCode, bNoWait, &bElemPriority, hevSemHandle); if (ulrc != 0) { printf("DosReadQueue error: return code = %ld", ulrc); return; }
On successful return, DataLength contains the size of the element on the queue that is pointed to by the pointer within DataAddress, ElemPriority has been updated to contain the priority of the queue element pointed to by DataAddress, and Request.ulData contains any special data that the DosWriteQueue caller placed into the queue.
If the queue is empty and NoWait is set to DCWW_WAIT (0), the calling thread waits until an element is placed in the queue. If the queue is empty and NoWait is set to DCWW_NOWAIT (1), DosReadQueue returns immediately with ERROR_QUE_EMPTY.
If NoWait is set to DCWW_NOWAIT, an event semaphore must be provided so that the calling thread can determine when an element has been placed in the queue. The semaphore is created by calling DosCreateEventSem, and its handle is supplied as a DosReadQueue parameter. The first time an event semaphore handle is supplied in a DosReadQueue or DosPeekQueue request for which DCWW_NOWAIT has been specified for a particular queue, the handle is saved by the system. The same handle must be supplied in all subsequent DosReadQueue and DosPeekQueue requests that are called for that queue; if a different handle is supplied, ERROR_INVALID_PARAMETER is returned.
When a client process adds an element to the queue, the system automatically opens the semaphore (if necessary) and posts it. The server can either call DosQueryEventSem periodically to determine whether the semaphore has been posted, or it can call DosWaitEventSem. DosWaitEventSem causes the calling thread to block until the semaphore is posted.
After the event semaphore has been posted, the calling thread must call DosReadQueue again to remove the newly added queue element.
If QUE_CONVERT_ADDRESS is specified in the call to DosCreateQueue, OS/2 will automatically convert 16-bitaddressesto32 - bitaddresses .