UserIndex

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

```
public class UserIndex
extends java.lang.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. The native methods on the IBM i have not yet been completed, so this class is currently not functional.
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

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description

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

Constructors
Constructor and Description
`UserIndex(AS400 system, java.lang.String path)` Constructs a UserIndex object.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`create(java.lang.String extendedAttribute, byte entryLengthAttribute, int entryLength, byte keyInsertion, int keyLength, byte immediateUpdate, byte optimization, java.lang.String authority, java.lang.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.
`java.lang.String[][]`	`findEntries(java.lang.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(java.lang.String key, java.lang.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
`java.lang.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,
         java.lang.String path)
          throws java.lang.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:
    
    java.lang.Exception - If an exception occurs.
- Method Detail
  - create
```
public void create(java.lang.String extendedAttribute,
          byte entryLengthAttribute,
          int entryLength,
          byte keyInsertion,
          int keyLength,
          byte immediateUpdate,
          byte optimization,
          java.lang.String authority,
          java.lang.String description)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   IllegalObjectTypeException,
                   java.lang.InterruptedException,
                   ObjectAlreadyExistsException,
                   java.lang.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.
    
    java.io.IOException - If an error occurs while communicating with the system.
    
    IllegalObjectTypeException - If the object on the system is not the required type.
    
    java.lang.InterruptedException - If this thread is interrupted.
    
    ObjectAlreadyExistsException - If the object already exists on the system.
    
    java.lang.Exception - If an exception occurs.
  - delete
```
public void delete()
```
    Deletes the user index.
  - insertEntry
```
public void insertEntry(java.lang.String key,
               java.lang.String value,
               int insertionRuleOption)
                 throws java.lang.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:
    
    java.lang.Exception - If an exception occurs.
  - insertEntry
```
public void insertEntry(byte[] entryBytes,
               byte[] optionBytes)
                 throws AS400SecurityException,
                        ErrorCompletingRequestException,
                        java.io.IOException,
                        IllegalObjectTypeException,
                        java.lang.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.
    
    java.io.IOException - If an error occurs while communicating with the system.
    
    IllegalObjectTypeException - If the object on the system is not the required type.
    
    java.lang.InterruptedException - If this thread is interrupted.
    
    ObjectDoesNotExistException - If the object does not exist on the system.
  - findEntries
```
public java.lang.String[][] findEntries(java.lang.String key,
                               int rule,
                               int occCount)
                                 throws java.lang.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.
    
    Parameters:
    key -
    rule -
    occCount -
    
    Returns:
    entries from user index
    
    Throws:
    
    java.lang.Exception - If an exception occurs.
  - findEntries
```
public void findEntries(byte[] outputBytes,
               byte[] optionBytes,
               byte[] keyBytes)
                 throws java.lang.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:
    
    java.lang.Exception - If an exception occurs.
  - toString
```
public java.lang.String toString()
```
    Returns the String representation of this user index object.
    
    Overrides:
    
    toString in class java.lang.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"
    
    Parameters:
    optionBytes -
  - setOptionBytesRule
```
public static void setOptionBytesRule(byte[] optionBytes,
                      int insertionRuleOption)
```
    Utility method to set the rule option in the option bytes
    
    Parameters:
    optionBytes -
    insertionRuleOption -
  - setOptionBytesArgLength
```
public static void setOptionBytesArgLength(byte[] optionBytes,
                           int argLength)
```
    Utility method to set the argument length in the option bytes
    
    Parameters:
    optionBytes -
    argLength -
  - setOptionBytesOccCount
```
public static void setOptionBytesOccCount(byte[] optionBytes,
                          int occurrenceCount)
```
    Utility method to set the occurrence count in the option bytes
    
    Parameters:
    optionBytes -
    occurrenceCount -
  - getOptionBytesReturnCount
```
public static int getOptionBytesReturnCount(byte[] optionBytes)
```
    Utility method to obtain the return count from the option bytes.
    
    Parameters:
    optionBytes -
    
    Returns:
    return count

Methods inherited from class java.lang.Object

FIND_EQUALS

FIND_GREATER

FIND_LESSER

FIND_NOT_LESSER

FIND_NOT_GREATER

FIND_FIRST

FIND_LAST

FIND_BETWEEN

FIXED_LENGTH_ENTRIES

VARIABLE_LENGTH_ENTRIES

INSERTION_BY_KEY

NO_INSERTION_BY_KEY

IMMEDIATE_UPDATE

NO_IMMEDIATE_UPDATE

OPTIMIZE_FOR_RANDOM_REFERENCES

OPTIMIZE_FOR_SEQUENTIAL_REFERENCES

RULE_INSERT

RULE_INSERT_REPLACE

RULE_INSERT_NO_REPLACE

UserIndex

create

delete

insertEntry

insertEntry

findEntries

findEntries

toString

isMustUseNativeMethods

setMustUseNativeMethods

resetOptionBytes

setOptionBytesRule

setOptionBytesArgLength

setOptionBytesOccCount

getOptionBytesReturnCount