Find Independent Index Entry (FNDINXEN)

Instruction Syntax

Operand 2: System pointer.

Operand 3: Space pointer.

Operand 4: Space pointer.

Built-in number for FNDINXEN is 36.
FNDINXEN (
          receiver          : address
          index             : address of system pointer
          option_list       : address
          search_argument   : address
)

Warning

The following information is subject to change from release to release. Use it with caution and be prepared to adjust for changes with each new release.

Description:

Search the independent index identified by index (operand 2) according to the search criteria specified in the option list (operand 3) and the search argument (operand 4); then return the desired entry or entries in the receiver operand (operand 1). The maximum size of the independent index entry is set when the index is created. The MATINXAT instruction can be used to materialize this information.

The option list is a variable-length area that identifies the type of search to be performed, the length of the search argument(s), the maximum number of entries to be returned, the number of entries returned, the length of each entry returned, and the offsets to the entries within the receiver identified by the receiver (operand 1) space pointer. The option list has the following format:

The rule option to find between requires that operand 4 be a 2-element array in which element 1 is the starting argument and element 2 is the ending argument. All arguments between (and including) the starting and ending arguments are returned, but the occurrence count specified is not exceeded.

If the index was created to contain both pointers and scalar data, then the search argument must be 16-byte aligned. For the option to find between limits, both search arguments must be 16-byte aligned.

The rule option and the argument length determine the search criteria used for the index search. The argument length must be greater than or equal to one. The argument length for fixed-length entries must be less than or equal to the argument length specified when the index is created.

The argument length input field specifies the length of the search argument (operand 4) to be used for the index search. When the rule option equals first or last, the argument length field is ignored. For the rule option to find between, the argument length field specifies the length of one array element. The lengths of the array elements must be equal.

The argument offset input field specifies the offset of the second search argument from the beginning of the entire search argument field (operand 4). The argument offset field is ignored unless the rule option is find between.

The occurrence count input field specifies the maximum number of index entries that satisfy the search criteria to be returned. This field is limited to a maximum value of 4,095. If this value is exceeded, a template value invalid (hex 3801) exception is signaled.

The return count output field specifies the number of index entries satisfying the search criteria that were returned in the receiver (operand 1). If this field is 0, no index arguments satisfied the search criteria.

There are two output fields in the option list for each entry returned in the receiver (operand 1). The entry length is the length of the entry retrieved from the index. The offset has the following meaning:

• For the first entry, the offset is the number of bytes from the beginning of the receiver (operand 1) to the first byte of the first entry.
• For any succeeding entry, the offset is the number of bytes from the beginning of the immediately preceding entry to the first byte of the entry returned.

The entries that are retrieved as a result of the Find Independent Index Entry instruction are always returned starting with the entry that is closest to or equal to the search argument and then proceeding away from the search argument. For example, a search that is for < (less than) or <= (less than or equal to) returns the entries in order of decreasing value.

All the entries that satisfy the search criteria (up to the occurrence count) are returned in the space starting at the location designated by the receiver (operand 1) space pointer.

If the index was created to contain both pointers and scalar data, then each returned entry is 16-byte aligned.

If the index was created to contain scalar data only, then returned entries are contiguous.

Every entry retrieved causes the count of the find operations to be incremented by 1. The current value of this count is available through the Materialize Independent Index Attributes (MATINXAT) instruction.

This operation will cause an object domain or hardware storage protection violation (hex 4401) exception if attempted from user state on an index object with the restrict index operations from user state at all security levels attribute set to binary 1.

Authorization Required

• Retrieve
  • Operand 2
• Execute
  • Contexts referenced for address resolution

Lock Enforcement

• Materialize
  • Operand 2
  • Contexts referenced for address resolution

Exceptions

• 06 Addressing
  • 0601 Space Addressing Violation
  • 0602 Boundary Alignment
  • 0603 Range
• 08 Argument/Parameter
  • 0801 Parameter Reference Violation
• 0A Authorization
  • 0A01 Unauthorized for Operation
• 10 Damage Encountered
  • 1004 System Object Damage State
  • 1005 Authority Verification Terminated Due to Damaged Object
  • 1044 Partial System Object Damage
• 1A Lock State
  • 1A01 Invalid Lock State
• 1C Machine-Dependent
  • 1C03 Machine Storage Limit Exceeded
• 20 Machine Support
  • 2002 Machine Check
  • 2003 Function Check
• 22 Object Access
  • 2201 Object Not Found
  • 2202 Object Destroyed
  • 2203 Object Suspended
  • 2207 Authority Verification Terminated Due to Destroyed Object
  • 2208 Object Compressed
  • 220B Object Not Available
• 24 Pointer Specification
  • 2401 Pointer Does Not Exist
  • 2402 Pointer Type Invalid
  • 2403 Pointer Addressing Invalid Object Type
• 2E Resource Control Limit
  • 2E01 User Profile Storage Limit Exceeded
• 36 Space Management
  • 3601 Space Extension/Truncation
• 38 Template Specification
  • 3801 Template Value Invalid
  • 3802 Template Size Invalid
• 44 Protection Violation
  • 4401 Object Domain or Hardware Storage Protection Violation
  • 4402 Literal Values Cannot Be Changed