The server process and its threads can examine a queue element by calling DosPeekQueue. This function is not available to client processes.
Unlike DosReadQueue, DosPeekQueue does not remove the element from the queue.
DosPeekQueue can either examine elements in the order that was specified when the queue was created (FIFO, LIFO, or priority), or it can examine the next element in the queue after a previous DosPeekQueue request has been called. By making multiple DosPeekQueue requests, the server process can search through a queue, examining each element in turn. When it locates the element it is searching for, the server process can remove the element from the queue by calling DosReadQueue.
If several threads are using the same queue, the process writing to the queue can use the ulData field of the REQUESTDATA data structure to indicate that an element is directed to a particular thread. The thread can peek at the queue whenever data is available and read any elements containing the appropriate value in the ulData field.
The following code fragment shows how a thread can use DosPeekQueue to examine the elements in a queue. Assume that a previous call to DosOpenQueue provided the queue handle that is contained in QueueHandle. Assume that the identifier of the process that owns the queue has been placed into OwningPID already.
#define INCL_DOSQUEUES /* Queue values */
#define INCL_DOSPROCESS /* needed for DCWW_WAIT */
#include <os2.h>
#include <stdio.h>
HQUEUE hqQueueHandle; /* Queue handle */
REQUESTDATA rqRequest; /* Request-identification data */
ULONG ulDataLength; /* Length of examined element */
PVOID pDataAddress; /* Address of examined element */
ULONG ulElementCode; /* Indicator of examined element */
BOOL32 bNoWait; /* No wait if queue is empty */
BYTE bElemPriority; /* Priority of examined element */
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 peek should start */
/* at the front of the queue */
bNoWait = DCWW_WAIT; /* Indicate that the peek call should */
/* wait if the queue is currently empty */
hevSemHandle = 0; /* Unused since this is a call that */
/* synchronously waits */
ulrc = DosPeekQueue(hqQueueHandle,
&rqRequest,
&ulDataLength,
&pDataAddress,
&ulElementCode,
bNoWait,
&bElemPriority,
hevSemHandle);
if (ulrc != 0) {
printf("DosPeekQueue 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, ElementCode has been updated to indicate the next queue element, 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), DosPeekQueue 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 DosPeekQueue parameter. The first time an event semaphore handle is supplied in a DosPeekQueue or DosReadQueue 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 DosPeekQueue and DosReadQueue requests that are called for that queue; if a different handle is supplied, ERROR_INVALID _ PARAMETERisreturned .
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 DosPeekQueue again to examine the newly added queue element.
If QUE_CONVERT_ADDRESS is specified in the call to DosCreateQueue, OS/2 will automatically convert 16-bit addresses to 32-bit addresses.