DosCreateQueue
From EDM2
Creates a queue.
Syntax
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.
- Priority-algorithm flag
- 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 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;
}
