com.ibm.as400.access
Class UserQueue

java.lang.Object
  extended by com.ibm.as400.access.UserQueue

public class UserQueue
extends Object

The UserQueue class represents an IBM i user queue object. This class currently will only function when running on the IBM i using native Methods.

As a performance optimization, when running directly on IBM i, it is possible to use native methods to access the user space from the current job. To enable this support, use the setMustUseNativeMethods() method.


Field Summary
static byte QUEUE_TYPE_FIRST_IN_FIRST_OUT
          Queue type is first-in first-out
static byte QUEUE_TYPE_KEYED
          Queue type is keyed
static byte QUEUE_TYPE_LAST_IN_FIRST_OUT
          Queue type is last-in first-out
 
Constructor Summary
UserQueue(AS400 system, String path)
          Constructs a UserQueue object.
 
Method Summary
 void create(String extendedAttribute, byte queueType, int keyLength, int maximumMessageSize, int initialNumberOfMessages, int additionalNumberOfMessages, String authority, String description, String replace)
          Creates a user queue on the system.
 void delete()
          Deletes the user queue.
 String dequeue()
          Dequeues the next entry from a FIFO or LIFO queue as a string
 int dequeue(byte[] dequeueMessagePrefixBytes, byte[] outputBytes)
          Dequeues an entry from the user queue.
 void enqueue(byte[] enqueueMessagePrefixBytes, byte[] entryBytes)
          Enqueues an entry on the user queue using the ENQ MI instruction.
 void enqueue(String value)
          Enqueues a string on the user queue
static int getDequeueMessagePrefixBytesLength(byte[] deqMsgPrefixBytes)
          Returns the output length from the deqMsgPrefixBytes buffer
 boolean isMustUseNativeMethods()
          Indicates if the native methods will be used internally to perform user queue dequeue and enqueue requests.
static void resetDequeueMessagePrefixBytes(byte[] dequeueMessagePrefixBytes)
          Resets the dequeueMessagePrefixBytes to zero
static void resetEnqueueMessagePrefixBytes(byte[] enqueueMessagePrefixBytes)
          Resets the enqueueMessagePrefixBytes to zero The format of the enqueueMessagePrefix is the following Offset Dec Hex Field Name Data Type and Length 0 0 Size of message to be enqueued Bin(4) 4 4 Enqueue key value Char(key length) (ignored for FIFO/LIFO queues with key lengths equal to 0)
static void setEnqueueMessagePrefixBytesEnqueueKey(byte[] enqueueMessagePrefixBytes, byte[] keyBytes)
           
static void setEnqueueMessagePrefixBytesMessageSize(byte[] enqueueMessagePrefixBytes, int messageSize)
           
 void setMustUseNativeMethods(boolean useNativeMethods)
          Specifies whether native methods are used by the current job to perform user queue operations.
 String toString()
          Returns the String representation of this user queue object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

QUEUE_TYPE_FIRST_IN_FIRST_OUT

public static final byte QUEUE_TYPE_FIRST_IN_FIRST_OUT
Queue type is first-in first-out

See Also:
Constant Field Values

QUEUE_TYPE_KEYED

public static final byte QUEUE_TYPE_KEYED
Queue type is keyed

See Also:
Constant Field Values

QUEUE_TYPE_LAST_IN_FIRST_OUT

public static final byte QUEUE_TYPE_LAST_IN_FIRST_OUT
Queue type is last-in first-out

See Also:
Constant Field Values
Constructor Detail

UserQueue

public UserQueue(AS400 system,
                 String path)
          throws Exception
Constructs a UserQueue object.

Parameters:
system - The system object representing the system on which the user queue exists.
path - The fully qualified integrated file system path name of the user queue.
Throws:
Exception
Method Detail

create

public void create(String extendedAttribute,
                   byte queueType,
                   int keyLength,
                   int maximumMessageSize,
                   int initialNumberOfMessages,
                   int additionalNumberOfMessages,
                   String authority,
                   String description,
                   String replace)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   IOException,
                   IllegalObjectTypeException,
                   InterruptedException,
                   ObjectAlreadyExistsException,
                   ObjectDoesNotExistException
Creates a user queue on the system. The queue will be created with the attributes provided.

Parameters:
extendedAttribute - The extended attribute of the user queue to be created.
queueType - The type of the queue, which indicates the sequences in which messages are to be dequeued from the queue. Valid values are QUEUE_TYPE_FIRST_IN_FIRST_OUT, QUEUE_TYPE_KEYED, QUEUE_TYPE_LAST_IN_FIRST_OUT.
keyLength - The length in bytes of the message key from 1 to 256, if the type of the queue is QUEUE_TYPE_KEYED. Otherwise, the value must be 0.
maximumMessageSize - The maximum allowed size of messages to be placed on the queue. The maximum size allowed is 64,0000 bytes.
initialNumberOfMessages - The initial number of messages that the queue can contain.
additionalNumberOfMessages - The amount to increase the maximum number of messages value when the queue is full. If set to 0, the queue cannot be extended and an error message is returned when attempting to enqueue an additional entry.
authority - The public authority for the user space. This string must be 10 characters or less. Valid values are:
  • *ALL
  • *CHANGE
  • *EXCLUDE
  • *LIBCRTAUT
  • *USE
  • authorization-list name
Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
IOException - If an error occurs while communicating with the system.
IllegalObjectTypeException - If the object on the system is not the required type.
InterruptedException - If this thread is interrupted.
ObjectAlreadyExistsException - If the object already exists on the system.
ObjectDoesNotExistException - If the library does not exist on the system.

delete

public void delete()
Deletes the user queue.


dequeue

public String dequeue()
               throws Exception
Dequeues the next entry from a FIFO or LIFO queue as a string

Throws:
Exception

dequeue

public int dequeue(byte[] dequeueMessagePrefixBytes,
                   byte[] outputBytes)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   IOException,
                   IllegalObjectTypeException,
                   InterruptedException,
                   ObjectDoesNotExistException
Dequeues an entry from the user queue.

Parameters:
dequeueMessagePrefixBytes - A Dequeue Message Prefix byte array used by the DEQI MI instruction. This provides both input and output information for the dequeue operation. The format of this byte array is as follows. For more information, see http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/index.jsp?topic=/rzatk/DEQ.htm.
     Offset     
     Dec    Hex     Field Name                                  Data Type and Length
       0        0       Timestamp of enqueue of message         Char(8) ++
           8    8               Dequeue wait time-out value         Char(8) +
           16   10              Size of message dequeued                Bin(4) ++
           20   14      Access state modification option    Char(1) + 
                        indicator and message selection 
                        criteria        
       21       15          Search key (ignored for FIFO/LIFO  Char(key length) + 
                    queues but must be present for 
                    FIFO/LIFO queues with nonzero key 
                     length values)     
        *               Message key                         Char(key length) ++

     Note:      Fields shown here with one plus sign (+) indicate input to the instruction, 
     and fields shown here with two plus signs (++) are returned by the machine. 
     
outputBytes - Byte array to receive the bytes contained in the queue entry.
Returns:
Returns 1 if a message was dequeued, 0 if a message was not dequeued.
Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
IOException - If an error occurs while communicating with the system.
IllegalObjectTypeException - If the object on the system is not the required type.
InterruptedException - If this thread is interrupted.
ObjectDoesNotExistException - If the object does not exist on the system.

toString

public String toString()
Returns the String representation of this user queue object.

Overrides:
toString in class Object
Returns:
The String representation of this user queue object.

enqueue

public void enqueue(String value)
             throws Exception
Enqueues a string on the user queue

Throws:
Exception

enqueue

public void enqueue(byte[] enqueueMessagePrefixBytes,
                    byte[] entryBytes)
             throws Exception
Enqueues an entry on the user queue using the ENQ MI instruction.

Parameters:
enqueueMessagePrefixBytes - A byte array representing the message prefix passed to the ENQ MI instruction. A value of null may be passed when using a FIFO to LIFO queue.

The format of the message prefix is the following. For more information, see http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/index.jsp?topic=/rzatk/ENQ.htm

     Offset     
     Dec        Hex     Field Name                                              Data Type and Length
                0       0               Size of message to be enqueued  Bin(4)
                4       4               Enqueue key value (ignored for  Char(key length)  
                                FIFO/LIFO queues with key 
                                lengths equal to 0)     
     
The static method setEnqueueMessagePrefixBytesMessageSize() can be used to set the size. The static method setEnqueueMessagePrefixBytesEnqueueKey() can be used to set the size.
entryBytes - A byte array representing the entry to add to the queue.
Throws:
AS400SecurityException - If a security or authority error occurs.
ErrorCompletingRequestException - If an error occurs before the request is completed.
IOException - If an error occurs while communicating with the system.
IllegalObjectTypeException - If the object on the system is not the required type.
InterruptedException - If this thread is interrupted.
ObjectDoesNotExistException - If the object does not exist on the system.
Exception

isMustUseNativeMethods

public boolean isMustUseNativeMethods()
Indicates if the native methods will be used internally to perform user queue dequeue and enqueue requests.

Returns:
true if user dequeue and enqueue requests will be performed via native methods; false otherwise.
See Also:
setMustUseNativeMethods(boolean)

setMustUseNativeMethods

public void setMustUseNativeMethods(boolean useNativeMethods)
Specifies whether native methods are used by the current job to perform user queue operations. This option can only be set to true when the application is running on the System i.

Parameters:
useNativeMethods - Internally use native methods to perform read and write requests.
See Also:
isMustUseNativeMethods()

resetDequeueMessagePrefixBytes

public static void resetDequeueMessagePrefixBytes(byte[] dequeueMessagePrefixBytes)
Resets the dequeueMessagePrefixBytes to zero


getDequeueMessagePrefixBytesLength

public static int getDequeueMessagePrefixBytesLength(byte[] deqMsgPrefixBytes)
Returns the output length from the deqMsgPrefixBytes buffer


resetEnqueueMessagePrefixBytes

public static void resetEnqueueMessagePrefixBytes(byte[] enqueueMessagePrefixBytes)
Resets the enqueueMessagePrefixBytes to zero The format of the enqueueMessagePrefix is the following Offset Dec Hex Field Name Data Type and Length 0 0 Size of message to be enqueued Bin(4) 4 4 Enqueue key value Char(key length) (ignored for FIFO/LIFO queues with key lengths equal to 0)


setEnqueueMessagePrefixBytesMessageSize

public static void setEnqueueMessagePrefixBytesMessageSize(byte[] enqueueMessagePrefixBytes,
                                                           int messageSize)

setEnqueueMessagePrefixBytesEnqueueKey

public static void setEnqueueMessagePrefixBytesEnqueueKey(byte[] enqueueMessagePrefixBytes,
                                                          byte[] keyBytes)