User index considerations

In IBM i APIs, a user index is an object that provides a specific order for byte data according to the value of the data. A user index has better performance than a database file. However, before using a user index, you must know its functional differences from a database file.

The contents of a database file are not affected by an abnormal system end. On the other hand, the contents of a user index might become totally unusable if the system ends abnormally. Therefore, you should not use a user index if the information that you want to store needs to remain without errors after an abnormal system end.

If your system abnormally ends when you are removing or inserting a user index entry, unpredictable results might occur. If you are inserting or removing a user index entry, you need to force the index entry to the disk unit using one of the following:

  • A user index created with the immediate update parameter set to 1 (affects performance)
  • A Modify Independent Index (MODIDX) MI instruction with the immediate update bit set to 1
  • The Set Access State (SETACST) MI instruction

If you do not force the index entry and the system abnormally ends, your index is probably damaged.

To determine if your last system power-down was normal or abnormal, you can check the system value QABNORMSW.

If your index is damaged, you do not get an error message. The definition of your index is usable; it is probably the data in your index that is bad.

You can log changes to a database file in a journal, and you can use the journal to apply or remove those changes later. You can also use the journal to audit who is using the database file. However, the system does not support the journaling of indexes. As a result, user applications should log entries in a journal to keep track of changes to the index, but you cannot update the index using apply and remove journal entry functions.

Indexes support the storage of data that does not need to remain after an abnormal system end. If an abnormal system end does occur, you must use a backup copy of the index that was previously saved or create a new copy of the index.