Find Independent Index Entry (FNDINXEN)

Op Code (Hex)	Operand 1	Operand 2	Operand 3	Operand 4
0494	Receiver	Index	Option list	Search argument

Operand 1: Space pointer.

Operand 2: System pointer.

Operand 3: Space pointer.

Operand 4: Space pointer.

Bound program access
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.

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:

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Rule option		Char(2)
2	2	Argument length		UBin(2)
4	4	Argument offset		Bin(2)
6	6	Occurrence count		Bin(2)
8	8	Return count		Bin(2)
10	A	Returned index entry		[*] Char(4)
		(Repeated return count times)
10	A		Entry length		UBin(2)
12	C		Offset		Bin(2)
*	*	--- End ---

The rule option identifies the type of search to be performed and has the following meaning:

Search Type	Value (Hex)	Meaning
=	0001	Find equal occurrences of operand 4. This option will return entries that match the search argument or begin with the search argument.
>	0002	Find occurrences that are greater than operand 4.
<	0003	Find occurrences that are less than operand 4.
>=	0004	Find occurrences that are greater than or equal to operand 4.
<=	0005	Find occurrences that are less than or equal to operand 4.
First	0006	Find the first index entry or entries.
Last	0007	Find the last index entry or entries.
Between	0008	Find all entries between the two arguments specified by operand 4 (inclusive). With this option, entries that match either search argument or begin with either search argument will be included.

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