DosPeekQueue

From EDM2
Jump to: navigation, search

Examines a queue element without removing it from the queue.

Syntax

DosPeekQueue(hq, pRequest, pcbData, ppbuf, element,
             nowait, ppriority, hsem);

Parameters

hq (HQUEUE) - input 
The handle of the queue from which an element is to be examined.
pRequest (PREQUESTDATA) - output 
A pointer to the REQUESTDATA in which PID and event codes are returned.
pcbData (PULONG) - output 
A pointer to the length of the examined data.
This field is the same as the pcbData that was furnished by DosWriteQueue when the element was added to the queue.
ppbuf (PPVOID) - output 
A pointer to the address of the element that is to be examined.
This field may or may not be the same as the ppbuf that was returned by DosWriteQueue when the element was added to the queue. If QUE_CONVERT_ADDRESS was specified when the queue was created, then the addresses of any elements that are written to the queue by the 16-bit DosWriteQueue function are converted to 32-bit addresses.
element (PULONG) - in/out 
A pointer to an indicator that specifies whether to start at the beginning of the queue or at a particular element.
Possible values are described in the following list:
0: Set by the application to indicate "examine the first element in the queue", according to the order that was specified when the queue was created (FIFO, LIFO, or priority).
Any Other Value: Set by the DosPeekQueue function to identify the element that has been examined (output), or by the owner to indicate "examine the next element" (input). Note: By contrast, when a DosReadQueue request follows DosPeekQueue, DosReadQueue removes the same element that is identified by element, not the next element in the queue.
nowait (BOOL32) - input 
The action to be performed when there are no elements in the queue.
Possible values are shown in the following list:
0 DCWW_WAIT - The requesting thread waits until an element is placed in the queue.
1 DCWW_NOWAIT - The requesting thread does not wait, and DosPeekQueue returns with ERROR_QUE_EMPTY.
ppriority (PBYTE) - output 
A pointer to the element's priority value.
This is the value that was specified for ppriority when DosWriteQueue added the element to the queue. ppriority is a numeric value in the range of 0 to 15, with 15 being the highest priority.
hsem (HEV) - input
The handle of an event semaphore that is to be posted when the data is added to the queue and nowait is set to 1.
The semaphore may be either private or shared, depending on whether the queue is shared across processes.
hsem is ignored if nowait is set to 0.
Note
The first time an event-semaphore handle is supplied in a DosPeekQueue or DosReadQueue request for which nowait is set to 1, the handle is saved by the system. The same handle must be supplied in all subsequent DosPeekQueue and DosReadQueue requests that are issued for that queue.

Return Code

ulrc (APIRET) - returns
DosPeekQueue returns one of the following values:
  • 0 NO_ERROR
  • 87 ERROR_INVALID_PARAMETER
  • 330 ERROR_QUE_PROC_NOT_OWNED
  • 333 ERROR_QUE_ELEMENT_NOT_EXIST
  • 337 ERROR_QUE_INVALID_HANDLE
  • 340 ERROR_QUE_PREV_AT_END
  • 342 ERROR_QUE_EMPTY
  • 433 ERROR_QUE_INVALID_WAIT

Remarks

DosPeekQueue examines a queue element without removing it from the queue. This function can be used only by the queue's server process and its threads.

If the nowait parameter is set to 1, an event semaphore must be provided so that the calling thread can determine when an element has been placed into the queue. The semaphore is created by calling DosCreateEventSem, and its handle is supplied in the hsem parameter of DosPeekQueue.

The first time an event-semaphore handle is supplied in a DosPeekQueue or DosReadQueue request for which nowait has been set to 1, the handle is saved by the system. The same handle must be supplied in all subsequent DosPeekQueue and DosReadQueue requests that are issued for the same 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 and posts the semaphore. The server can either issue DosQueryEventSem periodically to determine whether the semaphore has been posted, or it can issue 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.

Example Code

This example creates and opens a named queue. It writes a message to it, peeks the message, and finally closes it.

#define INCL_DOSQUEUES   /* DOS Queue values */
#define INCL_DOSPROCESS  /* DOS thread and process values */
#define INCL_DOSERRORS   /* DOS error values */
#include <os2.h>
#include <stdio.h>
#include <string.h>

int main(VOID) {

   PSZ         szQueueName  = "\\QUEUES\\AnyQueueNameHere";
   HQUEUE      hqAnyQueue   = NULLHANDLE; /* Queue handle                   */
   PSZ         DataBuffer   = "";         /* Data buffer for queue data     */
   REQUESTDATA Request      = {0};        /* Request                        */
   ULONG       ulDataLen    = 0,          /* Length of data returned        */
               ulElemCode   = 0;          /* Element code (input/output)    */
   BYTE        ElemPrty     = 0;          /* Priority of element (returned) */
   APIRET      rc           = NO_ERROR;   /* Return code                    */
   rc = DosCreateQueue(&hqAnyQueue,      /* Queue handle                    */
             QUE_FIFO |                  /* First-In First-Out order        */
             QUE_CONVERT_ADDRESS,        /* Convert 16-bit addresses to 32  */
             szQueueName);               /* Name of the queue to create     */
   if (rc!= NO_ERROR) {
      printf ("DosCreateQueue error: return code = %u\n", rc);
      return 1;
   }

   DataBuffer = "Start of the data... Middle of data...  Data ends.";
   rc = DosWriteQueue (hqAnyQueue,          /* Queue to write to           */
                       87654321L,           /* Request data                */
                       strlen(DataBuffer),  /* Length of data to write     */
                       DataBuffer,          /* Pointer to data             */
                       0L);              /* Priority (not applicable here) */
   if (rc!= NO_ERROR) {
      printf ("DosWriteQueue error: return code = %u\n", rc);
      return 1;
   }

   DataBuffer = "";                          /* Clear the DataBuffer        */
   rc = DosPeekQueue (hqAnyQueue,            /* Handle of queue             */
                      &Request,              /* Request data for element    */
                      &ulDataLen,            /* Length of data returned     */
                      (PVOID) &DataBuffer,   /* Data returned               */
                      &ulElemCode,           /* Input: 0 reads next element
                                                Output:  peeked element id  */
                      DCWW_WAIT,             /* Wait for data               */
                      &ElemPrty,             /* Priority of element         */
                      0L);                   /* Semaphore (not used here)   */
  if (rc != NO_ERROR) {
     printf ("DosPeekQueue error : return code = %u\n", rc);
     return 1;
  } else {
     printf ("DosPeekQueue returns: '%s'\n", DataBuffer);
     printf ("  (Request data = %u)\n", Request.ulData);
  }

  rc = DosCloseQueue(hqAnyQueue);         /* Close the queue */
  if (rc!= NO_ERROR) {
     printf ("DosCloseQueue error: return code = %u\n", rc);
     return 1;
  }

  return NO_ERROR;
}

Related Functions