DosCreateQueue

Creates a queue.

Syntax

#define INCL_DOSQUEUES
#include <os2.h>

PHQUEUE  phq;      /* A pointer to the read/write handle of the queue that is being created. */
ULONG    priority; /* Priority-ordering algorithm flag. */
PSZ      pszName;  /* A pointer to the ASCIIZ name of the queue. */
APIRET   ulrc;     /* Return Code. */

ulrc = DosCreateQueue(phq, priority, pszName);

Parameters

phq (PHQUEUE) - output

A pointer to the read/write handle of the queue that is being created.

After DosCreateQueue returns, this handle may be used immediately by the requesting process; it is not necessary to issue DosOpenQueue.

priority (ULONG) - input

Priority-ordering algorithm flag.

A set of flags that indicate which priority-ordering algorithm to use when placing elements in the queue, and whether or not to convert to 32-bit addresses the addresses of elements that are placed in the queue by 16-bit processes. Possible values are a combination of the values of the following two flags:

Priority-algorithm flag

QUE_FIFO (0x00000000) FIFO queue.

QUE_LIFO (0x00000001) LIFO queue.

QUE_PRIORITY (0x00000002) Priority queue: the requesting process specifies priority 0 to 15, with 15 being the highest priority.

Address-conversion flag

QUE_NOCONVERT_ADDRESS (0x00000000)The data addresses of elements placed in the queue by 16-bit processes are not converted.

QUE_CONVERT_ADDRESS (0x00000004) The data addresses of elements placed in the queue by 16-bit processes are converted to 32-bit data addresses.

pszName (PSZ) - input

A pointer to the ASCIIZ name of the queue.

The name string must include \QUEUES\ as the first element of the path. For example, \QUEUES\RETRIEVE\CONTROL.QUE is a valid queue name. This name must be specified by a client process in a DosOpenQueue request before the client process can add an element to the queue.

Return Code

ulrc (APIRET) - returns

DosCreateQueue returns one of the following values:

• 0 NO_ERROR
• 87 ERROR_INVALID_PARAMETER
• 332 ERROR_QUE_DUPLICATE
• 334 ERROR_QUE_NO_MEMORY
• 335 ERROR_QUE_INVALID_NAME

Example Code

This example creates a FIFO queue named "SPECIAL.QUE". It also opens it, 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
• DosOpenQueue
• DosPeekQueue
• DosPurgeQueue
• DosQueryQueue
• DosReadQueue
• DosWriteQueue