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.

Bindings

C

#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 */

MASM

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

Example

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 */