DosWriteQueue

From EDM2
Jump to: navigation, search

Adds an element to a queue.

Syntax

DosWriteQueue(hq, request, cbData, pbData, priority)

Parameters

hq (HQUEUE) - input 
The handle of the queue to which an element is to be added.
request (ULONG) - input 
A value to be passed with the queue element.
It is used by an application to code an event. The data is understood by the thread that is adding the element to the queue, as well as by the thread that receives the queue element. There is no special meaning to this data, and the operating system does not alter it.
This value is the same as the data in pRequest field of DosPeekQueue operation for examining a queue element.
cbData (ULONG) - input 
The length, in bytes, of the data that is being sent to the queue.
pbData (PVOID) - input 
A pointer to the buffer that contains the data to be placed into the queue.
priority (ULONG) - input 
The priority value of the element that is being added to the queue.
This parameter is valid only for queues that were created as priority-based queues, as specified in the priority parameter of DosCreateQueue. priority is a numerical value in the range of 0 to 15, with 15 being the highest priority.
  • If the priority value is 15, the element is added to the top of the queue.
  • If the priority value is 0, the element is added as the last element in the queue.
  • Elements with the same priority value are grouped together in FIFO (first in, first out) order.
If you assign a value greater than 15 to priority, the system sets priority to 15. No error code is returned for this condition.

Return Code

ulrc (APIRET) - returns
DosWriteQueue returns one of the following values:
  • 0 NO_ERROR
  • 334 ERROR_QUE_NO_MEMORY
  • 337 ERROR_QUE_INVALID_HANDLE

Remarks

DosWriteQueue adds an element to the specified queue. A client process must request access to the queue by calling DosOpenQueue before it can issue this function. The server process and its threads do not need to issue DosOpenQueue because they already have access to the queue.

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

If the server process has closed the queue before this request is issued, ERROR_QUE_INVALID_HANDLE is returned.

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