com.ibm.as400.access
Class UserIndex

java.lang.Object
  com.ibm.as400.access.UserIndex

public class UserIndex
extends Object

The UserIndex class represents an IBM i user index 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 int	FIND_BETWEEN
static int	FIND_EQUALS
static int	FIND_FIRST
static int	FIND_GREATER
static int	FIND_LAST
static int	FIND_LESSER
static int	FIND_NOT_GREATER
static int	FIND_NOT_LESSER
static byte	FIXED_LENGTH_ENTRIES
static byte	IMMEDIATE_UPDATE
static byte	INSERTION_BY_KEY
static byte	NO_IMMEDIATE_UPDATE
static byte	NO_INSERTION_BY_KEY
static byte	OPTIMIZE_FOR_RANDOM_REFERENCES
static byte	OPTIMIZE_FOR_SEQUENTIAL_REFERENCES
static int	RULE_INSERT Insert unique argument.
static int	RULE_INSERT_NO_REPLACE Insert argument only if the key is not already in the index
static int	RULE_INSERT_REPLACE Insert argument, replacing the nonkey portion if the key is already in the index
static byte	VARIABLE_LENGTH_ENTRIES

Constructor Summary

UserIndex(AS400 system, String path)
Constructs a UserIndex object.

Method Summary

void	create(String extendedAttribute, byte entryLengthAttribute, int entryLength, byte keyInsertion, int keyLength, byte immediateUpdate, byte optimization, String authority, String description) Creates a user index on the system.
void	delete() Deletes the user index.
void	findEntries(byte[] outputBytes, byte[] optionBytes, byte[] keyBytes) Returns one or more entries from the user index using the FNDINXEN MI instruction.
String[][]	findEntries(String key, int rule, int occCount) Returns one or more entries from the user index.
static int	getOptionBytesReturnCount(byte[] optionBytes) Utility method to obtain the return count from the option bytes.
void	insertEntry(byte[] entryBytes, byte[] optionBytes) Inserts one or more entries into the user index using the insinxen MI instruction.
void	insertEntry(String key, String value, int insertionRuleOption) Inserts key and value represented as Strings into the INDEX.
boolean	isMustUseNativeMethods() Indicates if the native methods will be used internally to perform user index insertion and retrieval requests.
static void	resetOptionBytes(byte[] optionBytes) Utility method to reset the optionBytes.
void	setMustUseNativeMethods(boolean useNativeMethods) Specifies whether native methods are used by the current job to perform user index operations.
static void	setOptionBytesArgLength(byte[] optionBytes, int argLength) Utility method to set the argument length in the option bytes
static void	setOptionBytesOccCount(byte[] optionBytes, int occurrenceCount) Utility method to set the occurrence count in the option bytes
static void	setOptionBytesRule(byte[] optionBytes, int insertionRuleOption) Utility method to set the rule option in the option bytes
String	toString() Returns the String representation of this user index object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

FIND_EQUALS

public static final int FIND_EQUALS

See Also:

Constant Field Values

FIND_GREATER

public static final int FIND_GREATER

See Also:

Constant Field Values

FIND_LESSER

public static final int FIND_LESSER

See Also:

Constant Field Values

FIND_NOT_LESSER

public static final int FIND_NOT_LESSER

See Also:

Constant Field Values

FIND_NOT_GREATER

public static final int FIND_NOT_GREATER

See Also:

Constant Field Values

FIND_FIRST

public static final int FIND_FIRST

See Also:

Constant Field Values

FIND_LAST

public static final int FIND_LAST

See Also:

Constant Field Values

FIND_BETWEEN

public static final int FIND_BETWEEN

See Also:

Constant Field Values

FIXED_LENGTH_ENTRIES

public static final byte FIXED_LENGTH_ENTRIES

See Also:

Constant Field Values

VARIABLE_LENGTH_ENTRIES

public static final byte VARIABLE_LENGTH_ENTRIES

See Also:

Constant Field Values

INSERTION_BY_KEY

public static final byte INSERTION_BY_KEY

See Also:

Constant Field Values

NO_INSERTION_BY_KEY

public static final byte NO_INSERTION_BY_KEY

See Also:

Constant Field Values

IMMEDIATE_UPDATE

public static final byte IMMEDIATE_UPDATE

See Also:

Constant Field Values

NO_IMMEDIATE_UPDATE

public static final byte NO_IMMEDIATE_UPDATE

See Also:

Constant Field Values

OPTIMIZE_FOR_RANDOM_REFERENCES

public static final byte OPTIMIZE_FOR_RANDOM_REFERENCES

See Also:

Constant Field Values

OPTIMIZE_FOR_SEQUENTIAL_REFERENCES

public static final byte OPTIMIZE_FOR_SEQUENTIAL_REFERENCES

See Also:

Constant Field Values

RULE_INSERT

public static final int RULE_INSERT

Insert unique argument. The RULE_INSERT is valid only for indexes not containing keys

See Also:

Constant Field Values

RULE_INSERT_REPLACE

public static final int RULE_INSERT_REPLACE

Insert argument, replacing the nonkey portion if the key is already in the index

See Also:

Constant Field Values

RULE_INSERT_NO_REPLACE

public static final int RULE_INSERT_NO_REPLACE

Insert argument only if the key is not already in the index

See Also:

Constant Field Values

Constructor Detail

UserIndex

public UserIndex(AS400 system,
                 String path)
          throws Exception

Constructs a UserIndex object.

Parameters:

system - The system object representing the system on which the user index exists.

path - The fully qualified integrated file system path name of the user index.

Throws:

Exception

Method Detail

create

public void create(String extendedAttribute,
                   byte entryLengthAttribute,
                   int entryLength,
                   byte keyInsertion,
                   int keyLength,
                   byte immediateUpdate,
                   byte optimization,
                   String authority,
                   String description)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   IOException,
                   IllegalObjectTypeException,
                   InterruptedException,
                   ObjectAlreadyExistsException,
                   Exception

Creates a user index on the system. The index will be created with the attributes provided.

Parameters:

extendedAttribute - The extended attribute of the user index to be created.

entryLengthAttribute - Length attribute of the queue entries. Must be set to FIXED_LENGTH_ENTRIES or VARIABLE_LENGTH_ENTRIES. Currently only FIXED_LENGTH_ENTRIES is supported.

entryLength - The length of entries in the index. The valid values for fixed-length entries are from 1 through 2000. Valid values for variable length entries are 0 or -1. A value of 0 enables a maximum entry length of 120 bytes and a key length from 1 through 120. A value of -1 enables a maximum entry length of 2000 and a key length from 1 through 2000.

keyInsertion - Whether the inserts to the index are by key. The valid values are: INSERTION_BY_KEY and NO_INSERTION_BY_KEY

keyLength - The length of the key where the first byte of an entry is the beginning of the key for the index entries. The value for this parameter must be 0 for NO_INSERTION_BY_KEY. If you specify key length insertion, this value is from 1 through 2000

immediateUpdate - Whether the updates to the index are written synchronously to auxiliary storage on each update to the index. The valid values are: IMMEDIATE_UPDATE and NO_IMMEDIATE_UPDATE.

optimization - The type of access in which to optimize the index. The valid values are: OPTIMIZE_FOR_RANDOM_REFERENCES and OPTIMIZE_FOR_SEQUENTIAL_REFERENCES.

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

description -

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.

Exception

delete

public void delete()

Deletes the user index.

insertEntry

public void insertEntry(String key,
                        String value,
                        int insertionRuleOption)
                 throws Exception

Inserts key and value represented as Strings into the INDEX. The values are stored in the index using the translation CCSID (Currently IBM-037)

Parameters:

key - The key for the new entry

value - The value portion of the new entry

insertionRuleOption - The rule used for inserting the entries. Valid values are : RULE_INSERT, RULE_INSERT_REPLACE, RULE_INSERT_NO_REPLACE

Throws:

Exception

insertEntry

public void insertEntry(byte[] entryBytes,
                        byte[] optionBytes)
                 throws AS400SecurityException,
                        ErrorCompletingRequestException,
                        IOException,
                        IllegalObjectTypeException,
                        InterruptedException,
                        ObjectDoesNotExistException

Inserts one or more entries into the user index using the insinxen MI instruction. For more information, see the following: http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/index.jsp?topic=/rzatk/INSINXEN.htm

Parameters:

entryBytes - Byte array containing the bytes of the entry or entries to be inserted.

optionBytes - Byte array containing insertion options.

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.

findEntries

public String[][] findEntries(String key,
                              int rule,
                              int occCount)
                       throws Exception

Returns one or more entries from the user index. The entries are returned as two element string arrays, where the first entry of each array is the key and the second entry is the value. The translation is done using the translation CCSID (Currently IBM-037). Currently only supported for fixed length keys.

Throws:

Exception

findEntries

public void findEntries(byte[] outputBytes,
                        byte[] optionBytes,
                        byte[] keyBytes)
                 throws Exception

Returns one or more entries from the user index using the FNDINXEN MI instruction. For more information, see http://publib.boulder.ibm.com/infocenter/iseries/v7r1m0/index.jsp?topic=/rzatk/FNDINXEN.htm.

Parameters:

outputBytes - Byte array into which the returned entries are placed.

optionBytes - Byte array containing the options for the query. Also returns information about the retrieved entries.

keyBytes - Byte array containing the key used to find the entries.

Throws:

Exception

toString

public String toString()

Returns the String representation of this user index object.

Overrides:

toString in class Object

Returns:

The String representation of this user index object.

isMustUseNativeMethods

public boolean isMustUseNativeMethods()

Indicates if the native methods will be used internally to perform user index insertion and retrieval requests.

Returns:

true if user index insertion and retrieval 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 index operations. This option can only be set to true when the application is running on the System i.

Parameters:

useNativeMethods - Internally use ProgramCall to perform read and write requests.

See Also:

isMustUseNativeMethods()

resetOptionBytes

public static void resetOptionBytes(byte[] optionBytes)

Utility method to reset the optionBytes. The layout of the optionBytes is the following Offset Dec Hex Field Name Data Type and Length 0 0 Rule option short 2 2 Argument length unsigned short 4 4 Argument offset short 6 6 Occurrence count short 8 8 Return count short 10 A Returned index entry (unsigned short,short) (Repeated return count times) 10 A Entry length unsigned short 12 C Entry offset short The occurrence count is limited to a maximum value of 4095. The number of bytes in the optionBytes must be at least 10 + 4 * "Occurrence Count"

setOptionBytesRule

public static void setOptionBytesRule(byte[] optionBytes,
                                      int insertionRuleOption)

Utility method to set the rule option in the option bytes

setOptionBytesArgLength

public static void setOptionBytesArgLength(byte[] optionBytes,
                                           int argLength)

Utility method to set the argument length in the option bytes

setOptionBytesOccCount

public static void setOptionBytesOccCount(byte[] optionBytes,
                                          int occurrenceCount)

Utility method to set the occurrence count in the option bytes

getOptionBytesReturnCount

public static int getOptionBytesReturnCount(byte[] optionBytes)

Utility method to obtain the return count from the option bytes.

Parameters:

optionBytes -

Returns:

return count