DosCreateQueue (OS/2 1.x)
This call creates a queue owned by a creating process.
Syntax
DosCreateQueue (RWHandle, QueuePrty, QueueName)
Parameters
- RWHandle (PHQUEUE) - output
- Address of read/write handle of the queue. The handle is used by the requestor on return.
- QueuePrty (USHORT) - input
- Values that indicate the priority ordering algorithm to use for elements placed in the queue.
- 0 - FIFO queue
- 1 - LIFO queue
- 2 - Priority queue (sender specifies priority zero to 15).
- QueueName (PSZ) - input
- Address of the name of the queue. The name string that specifies the name for the queue must include \QUEUES\ as the first element of the path. For example, \QUEUES\RETRIEVE\CONTROL.QUE is a valid queue name. The same name must be specified when calling DosOpenQueue for the process that adds elements to the queue.
Return Code
rc (USHORT) - return
Return code descriptions are:
- 0 NO_ERROR
- 332 ERROR_QUE_DUPLICATE
- 334 ERROR_QUE_NO_MEMORY
- 335 ERROR_QUE_INVALID_NAME
- 336 ERROR_QUE_INVALID_PRIORITY
- 337 ERROR_QUE_INVALID_HANDLE
Remarks
When specifying the name for a queue, the ASCIIZ name string must include the prefix \QUEUES\. Issuing DosCreateQueue creates a queue that can then be accessed by the creating process. When another process needs to access the queue, it issues DosOpenQueue with the queue's name.
The process that creates the queue owns it and has queue management privileges. Only the owner can peek at the elements in the queue with DosPeekQueue, remove them with DosReadQueue, or purge the queue of all its elements with DosPurgeQueue.
Any process that knows the queue name can open the queue after its creation with DosOpenQueue and place data in it with DosWriteQueue. It can also query the number of elements in the queue with DosQueryQueue and terminate its access to the queue with DosCloseQueue.
Whether a process gains access to the queue by creating or opening it, any thread in that process has access to the queue with equal authority. This provides the capability for multi-server queues.
A queue ceases to exist when its owner issues DosCloseQueue. If other processes use the queue handle for subsequent requests after the owner has closed the queue, ERROR_QUE_INVALID_HANDLE is returned.
Example Code
C Binding
#define INCL_DOSQUEUES USHORT rc = DosCreateQueue(RWHandle, QueuePrty, QueueName); PHQUEUE RWHandle; /* Address to put queue handle (returned) */ USHORT QueuePrty; /* Ordering to use for elements */ PSZ QueueName; /* Pointer to queue name string */ USHORT rc; /* return code */
This example creates a queue named special.que.
#define INCL_DOSQUEUES
#define QUE_FIFO 0
#define QUE_NAME "\\QUEUES\\special.que"
HQUEUE QueueHandle;
USHORT rc;
rc = DosCreateQueue(&QueueHandle, /* Queue handle */
QUE_FIFO, /* Ordering to use for
elements */
QUE_NAME); /* Queue name string */
MASM Binding
EXTRN DosCreateQueue:FAR INCL_DOSQUEUES EQU 1 PUSH@ WORD RWHandle ;Queue handle (returned) PUSH WORD QueuePrty ;Ordering to use for elements PUSH@ ASCIIZ QueueName ;Queue name string CALL DosCreateQueue Returns WORD