cwbDQ_Peek

Purpose

Read a record from the iSeries™ data queue object that is identified by the specified handle. When a record is peeked from a data queue, it remains in the data queue. You may wait for a record if the data queue is empty by specifying a wait time from 0 to 99,999 or forever (-1). A wait time of zero will return immediately if there is no data in the data queue.

Syntax

 
unsigned int CWB_ENTRY cwbDQ_Peek(
                             cwbDQ_QueueHandle   queueHandle,
                             cwbDQ_Data          data,
                             signed long         waitTime,
                             cwbSV_ErrHandle     errorHandle);

Parameters

cwbDQ_QueueHandle queueHandle - input

Handle that was returned by a previous call to the cwbDQ_Open API. This identifies the iSeries data queue object.

cwbDQ_Data data - input

The data object to be read from the iSeries data queue.

signed long waitTime - input

Length of time in seconds to wait for data, if the data queue is empty. A wait time of -1 indicates to wait forever.

cwbSV_ErrHandle errorHandle - output

Any returned messages will be written to this object. It is created with the cwbSV_CreateErrHandle API. The messages may be retrieved through the cwbSV_GetErrText API. If the parameter is set to zero, no messages will be retrieved.

Return Codes

The following list shows common return values.

CWB_OK

Successful completion.

CWBDQ_INVALID_TIME

Invalid wait time.

CWBDQ_INVALID_QUEUE_HANDLE

Invalid queue handle.

CWBDQ_INVALID_SEARCH

Invalid search order.

CWBDQ_DATA_TRUNCATED

Data truncated.

CWBDQ_TIMED_OUT

Wait time expired and no data returned.

CWBDQ_REJECTED_USER_EXIT

Command rejected by user exit program.

CWBDQ_QUEUE_DESTROYED

Queue was destroyed.

CWBDQ_CANNOT_CONVERT

Unable to convert data.

Usage

This function requires that you have previously issued cwbDQ_Open or cwbDQ_OpenEx and cwbDQ_CreateData.