DosReadQueue - Parameters

hq (HQUEUE) - input

The handle of the queue from which an element is to be removed.

pRequest (PREQUESTDATA) - output

A pointer to a REQUESTDATA that returns a PID and an event code.

The data in the ulData field of the REQUESTDATA structure is the same as the data that was furnished in the request parameter of DosWriteQueue for the corresponding queue element.

pcbData (PULONG) - output

A pointer to the length, in bytes, of the data that is being removed.

ppbuf (PPVOID) - output

A pointer to the element that is being removed from the queue.

(This field may or may not be the same as the value of pbData that was specified with DosWriteQueue when the element was added to the queue. If QUE_CONVERT_ADDRESS was specified when the queue was created, the addresses of any elements that are written to the queue by the 16-bit DosWriteQueue function are converted to 32-bit addresses.)

element (ULONG) - input

An indicator that specifies whether to remove the first element in the queue or the queue element that was previously examined by DosPeekQueue.

Possible values are shown in the following list:

• This field is set to 0 by the application to indicate "remove the first element in the queue," according to the order that was specified when the queue was created (FIFO, LIFO, or priority).

  Any other value

  The field is set to the value that was returned by a previous DosPeekQueue operation to indicate "remove the element that was examined by DosPeekQueue."

  wait (BOOL32) - input

  The action to be performed when no entries are found in the queue.

  Possible values are shown in the following list:

  • DCWW_WAIT The requesting thread waits for an element to be added to the queue.

  • DCWW_NOWAIT
    The requesting thread does not wait, and DosReadQueue returns with ERROR_QUE_EMPTY.

  ppriority (PBYTE) - output

  The address of the element's priority value.

  This is the value that was specified for ppriority by DosWriteQueue when it added the element to the queue. ppriority is a numerical value in the range of 0 to 15, with 15 being the highest priority.

  hsem (HEV) - input

  The handle of an event semaphore that is to be posted when data is added to the queue and wait is set to 1.

  This parameter is ignored if wait is set to 0.

  The event semaphore may be shared or private, depending on whether the queue is shared across processes.

  Note: The first time an event-semaphore handle is supplied in a DosReadQueue or DosPeekQueue request for which wait is set to 1, the handle is saved by the system. The same handle must be supplied in all subsequent DosReadQueue and DosPeekQueue requests that are issued for that queue.

  ulrc (APIRET) - returns

  Return Code.

  DosReadQueue returns one of the following values:

  • NO_ERROR 87
    ERROR_INVALID_PARAMETER
    330
    ERROR_QUE_PROC_NOT_OWNED
    333
    ERROR_QUE_ELEMENT_NOT_EXIST
    337
    ERROR_QUE_INVALID_HANDLE
    342
    ERROR_QUE_EMPTY
    433
    ERROR_QUE_INVALID_WAIT
    For a full list of error codes, see Errors.

  ---

  [Back: DosReadQueue Return Value - ulrc]
  [Next: DosReadQueue - Remarks]