Receive Data Queue Entry

Main Menu

Programming Services

Do you need a program written?

Bruce Vining Services can provide highly experienced IBM i developers to supplement your staff with short term contracts. We don't do general ledger but if you are looking for custom solutions involving system functions such as database, communications, security, encryption, print, and work management you will find your answers at Bruce Vining Services.

Receive Data Queue Entry

PDF

Print

E-mail

Receive Data Queue Entry (RCVDTAQXCL)

Where allowed to run:

Batch program (*BPGM)
Interactive program (*IPGM)

Threadsafe: Yes

Parameters
Examples
Error messages

The Receive Data Queue Entry (RCVDTAQXCL) command receives an entry from a data queue. The entry received can be removed from the data queue or left on the queue.

This function is also available with command RCVDTAQE in library VC2XCL. Any use of this alternative command name should be library qualified in case the i operating system were to use this command name in a future release.

Restrictions:

You must have *EXECUTE authority to the library where the data queue is located.
You must have *OBJOPR and *READ authority to the data queue.

Parameters

Keyword	Description	Choices	Notes
DTAQ	Data queue	Qualified object name	Required, Positional 1
	Qualifier 1: Data queue	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
DTA	Data	Character value	Required, Positional 2
DTALEN	Data length to receive	Decimal number, *DTA	Optional
RCV	Receive	NXT, BYKEY	Optional
RMV	Remove	YES, NO	Optional
WAIT	Wait time in seconds	Decimal number, NOWAIT, MAX	Optional
DTALENRTN	Data length returned (5 0)	Decimal number	Optional
KEYRTN	Key value returned	Character value	Optional
KEYLENRTN	Key length returned (3 0)	Decimal number	Optional
SNDRJOBNAM	Sender job name (10)	Character value	Optional
SNDRJOBUSR	Sender job user (10)	Character value	Optional
SNDRJOBNBR	Sender job number (6)	Character value	Optional
SNDRCURUSR	Sender current user (10)	Character value	Optional
KEYCMP	Key comparison	EQ, NE, GT, LT, GE, LE, ' '	Optional
KEY	Key data	Character value	Optional

Data queue (DTAQ)

Specifies the qualified name of the data queue to be used.

This is a required parameter.

Qualifier 1: Data queue

*LIBL: The library list for the job is used.
*CURLIB: The current library for the job is used. If no current library entry exists in the library list, QGPL is used.
name: Specify the name of the library.

Data (DTA)

Specifies the CL variable to receive the data queue entry.

This is a required parameter.

character-value: Specify the name of the CL variable to receive the data queue entry.

Data length to receive (DTALEN)

Specifies the size of the CL variable identified by the DTA parameter.

*DTA: The size of the CL variable is the declared length of the variable.
decimal-number: Specify the number of bytes of the DTA variable that are to be used to receive the data queue message. If this value is less than the declared length of the DTA variable then only the DTALEN specified number of bytes will be used. If this value is greater than the declared length of the DTA variable then only the declared length of the DTA variable will be used.

Receive (RCV)

Specifies how the data queue entry is to be accessed.

*NXT: The next data queue entry is read. For FIFO queues this will be the oldest entry. For LIFO queues this will be the most recently added entry.
This special value can only be used for non-keyed data queues.
*BYKEY: The data queue entry to read is identified by the key comparision (KEYCMP) and key (KEY) value parameters.
This special value can only be used for keyed data queues.

Remove (RMV)

Specifies if the received data queue entry should be removed from the data queue.

*YES: The data queue entry is removed.
*NO: The data queue entry is not removed. The data queue entry can later be removed using either the RCVDTAQXCL command with RMV(*YES) or the Remove Data Queue Entry (RMVDTAQXCL) command.

Wait time in seconds (WAIT)

Specifies the number of seconds to wait for a data queue entry if none are currently available.

*NOWAIT: The RCVDTAQXCL command is to return immediately if no entries are available on the data queue. If no entry is available the DTALENRTN parameter value will be set to 0.
*MAX: The RCVDTAQXCL command is to wait indefinitely for an entry to be sent to the data queue.
decimal-number: Specify the number of seconds to wait for an entry to be sent to the data queue. If no entry is available during the specified time interval the DTALENRTN parameter value will be set to 0.

Data length returned (5 0) (DTALENRTN)

Specifies the CL variable to receive the length of the data queue entry received in the DTA parameter.

decimal-number: Specify the name of a CL variable defined as TYPE(*DEC) LEN(5 0).

Key value returned (KEYRTN)

Specifies the CL variable to receive the key value associated with the data queue entry received. The key value may not be the same as the KEY specified depending on the KEYCMP specified value.

character-value: Specify the CL variable to receive the key value.

Key length returned (3 0) (KEYLENRTN)

Specifies the CL variable to receive the length of the key value associated with the data queue entry received.

decimal-number: Specify the name of a CL variable defines as TYPE(*DEC) LEN(3 0).

Sender job name (10) (SNDRJOBNAM)

Specifies the name of the CL variable to receive the job name of the sender of the data queue entry received. A value of blanks will be returned if the data queue was not created with SENDERID(*YES).

character-value: Specify the name of a CL variable defined as TYPE(*CHAR) LEN(10).

Sender job user (10) (SNDRJOBUSR)

Specifies the name of the CL variable to receive the user profile name of the sender of the data queue entry received. A value of blanks will be returned if the data queue was not created with SENDERID(*YES).

character-value: Specify the name of a CL variable defined as TYPE(*CHAR) LEN(10).

Sender job number (6) (SNDRJOBNBR)

Specifies the name of the CL variable to receive the job number of the sender of the data queue entry received. A value of blanks will be returned if the data queue was not created with SENDERID(*YES).

character-value: Specify the name of a CL variable defined as TYPE(*CHAR) LEN(6).

Sender current user (10) (SNDRCURUSR)

Specifies the name of the CL variable to receive the current user profile of the sender of the data queue entry received. A value of blanks will be returned if the data queue was not created with SENDERID(*YES).

character-value: Specify the name of a CL variable defined as TYPE(*CHAR) LEN(10).

Key comparison (KEYCMP)

Specifies the comparison criteria to be used with the KEY parameter and the keys of data queue entries when determining the entry to receive. If duplicate key values are found, the oldest entry is received.

Key value comparisons are performed based on hexadecimal key values.

*EQ: Receive the first entry with a key value equal to the KEY parameter value.
*NE: Receive the first entry with a key value not equal to the KEY parameter value.
*GT: Receive the first entry with a key value greater than the KEY parameter value.
*LT: Receive the first entry with a key value less than the KEY parameter value.
*GE: Receive the first entry with a key value greater than or equal to the KEY parameter value.
*LE: Receive the first entry with a key value less than or equal to the KEY parameter value.

Key data (KEY)

Specifies the key value to be used when determining the data queue entry that is to be received. If the length of the key value is less than the length of the key defined when creating the data queue the KEY value will be blank padded. If the length of the key value is greater than the length of the key defined when creating the data queue the KEY value will be truncated.

character-value: Specify the key value.

Examples for RCVDTAQXCL

Example 1: Receiving From *FIFO Data Queue

Dcl        Var(&Entry) Type(*Char) Len(100)
CrtDtaQ    DtaQ(QTEMP/FIFO) MaxLen(100)
SndDtaQXCL DtaQ(QTEMP/FIFO) Dta(XYZ)
SndDtaQXCL DtaQ(QTEMP/FIFO) Dta(ABC)
SndDtaQXCL DtaQ(QTEMP/FIFO) Dta(KLM)
RcvDtaQXCL DtaQ(QTEMP/FIFO) Dta(&Entry)

The RCVDTAQXCL command will receive the entry with the value 'XYZ' as the data queue is created as first-in first-out (FIFO).

Example 2: Receiving from *LIFO Data Queue

Dcl        Var(&Entry) Type(*Char) Len(100)
CrtDtaQ    DtaQ(QTEMP/LIFO) MaxLen(100) Seq(*LIFO)
SndDtaQXCL DtaQ(QTEMP/LIFO) Dta(XYZ)
SndDtaQXCL DtaQ(QTEMP/LIFO) Dta(ABC)
SndDtaQXCL DtaQ(QTEMP/LIFO) Dta(KLM)
RcvDtaQXCL DtaQ(QTEMP/LIFO) Dta(&Entry)

The RCVDTAQXCL command will receive the entry with the value 'KLM' as the data queue is created as last-in first-out (LIFO).

Example 3: Receiving from *Keyed Data Queue With *EQ Key Comparison

Dcl        Var(&Entry) Type(*Char) Len(100)
CrtDtaQ    DtaQ(QTEMP/Keyed) MaxLen(100) +
             Seq(*Keyed) KeyLen(5)
SndDtaQXCL DtaQ(QTEMP/Keyed) Dta(XYZ) Key(X)
SndDtaQXCL DtaQ(QTEMP/Keyed) Dta(ABC) Key(A)
SndDtaQXCL DtaQ(QTEMP/Keyed) Dta(KLM) Key(K)
RcvDtaQXCL DtaQ(QTEMP/Keyed) Dta(&Entry) +
             Rcv(*ByKey) KeyCmp(*Eq) Key(A)

The RCVDTAQXCL command will receive the entry with the value 'ABC' as the data queue is created as keyed and the entry received is the entry with a key value equal to 'A'.

Example 4: Receiving from *Keyed Data Queue With *GT Key Comparison

Dcl        Var(&Entry) Type(*Char) Len(100)
CrtDtaQ    DtaQ(QTEMP/Keyed) MaxLen(100) +
             Seq(*Keyed) KeyLen(5)
SndDtaQXCL DtaQ(QTEMP/Keyed) Dta(XYZ) Key(X)
SndDtaQXCL DtaQ(QTEMP/Keyed) Dta(ABC) Key(A)
SndDtaQXCL DtaQ(QTEMP/Keyed) Dta(KLM) Key(K)
RcvDtaQXCL DtaQ(QTEMP/Keyed) Dta(&Entry) +
             Rcv(*ByKey) KeyCmp(*GT) Key(A)

The RCVDTAQXCL command will receive the entry with the value 'KLM' as the data queue is created as keyed and the entry received is the first entry with a key value greater than 'A'.

Error messages for RCVDTAQXCL

*ESCAPE Messages

XCL800D: KEY not specified but data queue is keyed. Specify a KEY value.
XCL800F: RCV(*BYKEY) specified but data queue is not keyed. Specify RCV(*NXT).
XCL9002: Function did not complete. See previously listed messages related to possible user errors.
XCL9003: Function did not complete. See previously listed messages for possible cause.
XCL9004: Function did not complete. See previously listed messages for possible cause.
XCL9005: Function did not complete. Contact your service provider.

Joomla 1.5 Templates by Joomlashack