DosOpenQueue

Gives a client process access to a queue.

Syntax

DosOpenQueue(ppid, phq, pszName)

Parameters

ppid (PPID) - output

A pointer to the process identification of the queue's server process.

phq (PHQUEUE) - output

A pointer to the write handle of the queue to be opened.

pszName (PSZ) - input

A pointer to the ASCIIZ name of the queue to be opened.

This is the name that was specified by the server process when it created the queue with DosCreateQueue. The name string must include \QUEUES\ as the first element of the path.

Return Code

ulrc (APIRET) - returns

DosOpenQueue returns one of the following values:

• 0 NO_ERROR
• 334 ERROR_QUE_NO_MEMORY
• 341 ERROR_QUE_PROC_NO_ACCESS
• 343 ERROR_QUE_NAME_NOT_EXIST

Remarks

DosOpenQueue opens a queue for a client process.

If the queue was created by a call to the 16-bit DosCreateQueue function, the queue is not accessible to 32-bit DosOpenQueue requests, and ERROR_QUE_PROC_NO_ACCESS 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

• DosCloseQueue
• DosCreateQueue
• DosPeekQueue
• DosPurgeQueue
• DosQueryQueue
• DosReadQueue
• DosWriteQueue