com.ibm.as400.access

Class 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.

    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.

    • Constructor Summary

      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
    • 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