DosReadQueue

DosReadQueue reads (removes) an element from a queue.

Syntax

DosReadQueue(hq, pRequest, pcbData, ppbuf, element, wait, ppriority, hsem)

Parameters

hq (HQUEUE) - input

The handle of the queue from which an element is to be removed.

pRequest (PREQUESTDATA) - output

A pointer to a REQUESTDATA that returns a PID and an event code.

The data in the ulData field of the REQUESTDATA structure is the same as the data that was furnished in the request parameter of DosWriteQueue for the corresponding queue element.

pcbData (PULONG) - output

A pointer to the length, in bytes, of the data that is being removed.

ppbuf (PPVOID) - output

A pointer to the element that is being removed from the queue.

(This field may or may not be the same as the value of pbData that was specified with DosWriteQueue when the element was added to the queue. If QUE_CONVERT_ADDRESS was specified when the queue was created, the addresses of any elements that are written to the queue by the 16-bit DosWriteQueue function are converted to 32-bit addresses.)

element (ULONG) - input

An indicator that specifies whether to remove the first element in the queue or the queue element that was previously examined by DosPeekQueue.

Possible values are shown in the following list:

0 : This field is set to 0 by the application to indicate "remove 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: The field is set to the value that was returned by a previous DosPeekQueue operation to indicate "remove the element that was examined by DosPeekQueue."

wait (BOOL32) - input

The action to be performed when no entries are found in the queue.

Possible values are shown in the following list:

0 DCWW_WAIT The requesting thread waits for an element to be added to the queue.

1 DCWW_NOWAIT The requesting thread does not wait, and DosReadQueue returns with ERROR_QUE_EMPTY.

ppriority (PBYTE) - output

The address of the element's priority value.

This is the value that was specified for ppriority by DosWriteQueue when it added the element to the queue. ppriority is a numerical 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 data is added to the queue and wait is set to 1.

This parameter is ignored if wait is set to 0.

The event semaphore may be shared or private, depending on whether the queue is shared across processes.

Note: The first time an event-semaphore handle is supplied in a DosReadQueue or DosPeekQueue request for which wait is set to 1, the handle is saved by the system. The same handle must be supplied in all subsequent DosReadQueue and DosPeekQueue requests that are issued for that queue.

Return Code

ulrc (APIRET) - returns

DosReadQueue 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
• 342 ERROR_QUE_EMPTY
• 433 ERROR_QUE_INVALID_WAIT

Remarks

This function can be issued only by the server process and its threads.

If the wait 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 DosReadQueue.

The first time an event-semaphore handle is supplied in a DosReadQueue or DosPeekQueue request for which wait has been set to 1, the handle is saved by the system. The same handle must be supplied in all subsequent DosReadQueue and DosPeekQueue 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 issue DosReadQueue again to remove the newly added queue element.

Example Code

This example creates and opens a queue named "SPECIAL.QUE", writes to it, reads from it, 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\\SPECIAL.QUE";
   HQUEUE      hqSpecialQue = NULLHANDLE; /* Queue handle                   */
   PSZ         DataBuffer   = "";         /* Data buffer for queue data     */
   REQUESTDATA Request      = {0};        /* Reques */
   PID         pidOwner     = 0;
   ULONG       ulDataLen    = 0;          /* Length of data returned        */
   BYTE        ElemPrty     = 0;          /* Priority of element (returned) */
   APIRET      rc           = NO_ERROR;   /* Return code                    */

   rc = DosCreateQueue(&hqSpecialQue,    /* 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;
   }

   rc = DosOpenQueue (&pidOwner,         /* PID of queue owner              */
                      &hqSpecialQue,     /* Handle for created queue        */
                      szQueueName);      /* Name of the queue to open       */
   if (rc!= NO_ERROR) {
      printf ("DosOpenQueue error: return code = %u\n", rc);
      return 1;
   }

   DataBuffer = "To be, or not to be.  That is the question...";
   rc = DosWriteQueue (hqSpecialQue,        /* Queue to write to           */
                       12345L,              /* 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 */
   Request.pid = pidOwner;           /* process ID for the DosReadQueue */
   rc = DosReadQueue (hqSpecialQue,          /* Queue to read from          */
                      &Request,              /* Request data from write     */
                      &ulDataLen,            /* Length of data returned     */
                      (PVOID) &DataBuffer,   /* The data                    */
                      0L,                    /* Remove first element        */
                      DCWW_WAIT,             /* Wait for available data     */
                      &ElemPrty,             /* Priority of data (returned) */
                      0L);             /* Semaphore to use when not waiting */

   if (rc!= NO_ERROR) {
      printf ("DosReadQueue error: return code = %u\n", rc);
      return 1;
   } else {
      printf ("DosReadQueue returns: '%s'\n", DataBuffer);
      printf ("      (Request data = %u)\n", Request.ulData);
   }

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

   return NO_ERROR;
}

Related Functions

• DosCloseQueue
• DosCreateQueue
• DosOpenQueue
• DosPeekQueue
• DosPurgeQueue
• DosQueryQueue
• DosWriteQueue