Materialize Independent Index Attributes (MATINXAT)


Op Code (Hex) Operand 1 Operand 2

0462 Receiver Index

Operand 1: Space pointer.

Operand 2: System pointer.

Bound program access
Built-in number for MATINXAT is 38.
MATINXAT (
          receiver   : address
          index      : address of system pointer
)

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

The instruction materializes the creation attributes and current operational statistics of the independent index identified by operand 2 into the space identified by operand 1. The format of the attributes materialized is as follows:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Materialization size specification
Char(8)
0 0
Number of bytes provided for materialization
Bin(4)
4 4
Number of bytes available for materialization
Bin(4)
8 8
Object identification
Char(32)
8 8
Object type
Char(1)
9 9
Object subtype
Char(1)
10 A
Object name
Char(30)
40 28
Object creation options
Char(4)
40 28
Existence attributes
Bit 0



0 = Temporary
1 = Reserved



40 28
Space attribute
Bit 1



0 = Fixed-length
1 = Variable-length



40 28
Context
Bit 2



0 = Addressability not in context
1 = Addressability in context



40 28
Access group
Bit 3



0 = Not a member of access group
1 = Member of access group



40 28
Reserved (binary 0)
Bits 4-12
40 28
Initialize space
Bit 13



0 = Initialize
1 = Do not initialize



40 28
Automatically extend space
Bit 14



0 = No
1 = Yes



40 28
Hardware storage protection level
Bits 15-16



00 = Reference and modify allowed for user state programs
01 = Only reference allowed for user state programs
10 = Only reference allowed in any state
11 = No reference or modify allowed for user state programs



40 28
Reserved (binary 0)
Bits 17-19






40 28
Always enforce hardware storage protection of this index
Bit 20



0 = Enforce hardware storage protection of this index only when hardware storage protection is enforced for all storage.
1 = Enforce hardware storage protection of this index at all times.



40 28
Always enforce hardware storage protection of the associated space
Bit 21



0 = Enforce hardware storage protection of this space only when hardware storage protection is enforced for all storage.
1 = Enforce hardware storage protection of this space at all times.



40 28
Reserved (binary 0)
Bits 22-31






44 2C
Reserved (binary 0)
Char(4)
48 30
Size of space
Bin(4)
52 34
Initial value of space
Char(1)
53 35
Performance class
Char(4)
53 35
Space alignment
Bit 0



0 = The space associated with the object is allocated to allow proper alignment of pointers at 16-byte alignments within the space.
1 = The space associated with the object is allocated to allow proper alignment of pointers at 16-byte alignments within the space as well as to allow proper alignment of input/output buffers at 512-byte alignments within the space.
Ignore the value of this field when the machine chooses space alignment field has a value of 1.


53 35
Reserved (binary 0)
Bits 1-2
53 35
Machine chooses space alignment
Bit 3



0 = The space alignment indicated by the space alignment field is in effect.
1 = The machine chose the space alignment most beneficial to performance, which may have reduced maximum space capacity. The alignment chosen is a multiple of 512. Ignore the value of the space alignment field.



53 35
Reserved (binary 0)
Bit 4
53 35
Main storage pool selection
Bit 5



0 = Process default main storage pool used for object.
1 = Machine default main storage pool used for object.



53 35
Reserved (binary 0)
Bit 6
53 35
Block transfer on implicit access state modification
Bit 7



0 = Transfer the minimum storage transfer size for this object.
1 = Transfer the machine default storage transfer size for this object.


53 35
Reserved (binary 0)
Bits 8-31
57 39
Reserved (binary 0)
Char(7)
64 40
Context
System pointer
80 50
Access group
System pointer
96 60
Index attributes
Char(1)
96 60
Entry length attribute
Bit 0



0 = Fixed-length entries
1 = Variable-length entries



96 60
Immediate update
Bit 1



0 = No immediate update
1 = Immediate update



96 60
Key insertion
Bit 2



0 = No insertion by key
1 = Insertion by key



96 60
Entry format
Bit 3



0 = Scalar data only
1 = Both pointers and scalar data



96 60
Optimized processing mode
Bit 4



0 = Optimize for random references
1 = Optimize for sequential references



96 60 Maximum entry length attribute Bit 5



0 = Maximum entry length is 120 bytes
1 = Maximum entry length is 2,000 to 32,000 bytes



96 60
Index coherency tracking
Bit 6



0 = Do not track index coherency
1 = Track index coherency



96 60
Longer template
Bit 7



0 = The template is the original size
1 = The template is longer



97 61
Argument length
Bin(2)
99 63
Key length
Bin(2)
101 65
Index statistics
Char(12)
101 65
Entries inserted
UBin(4)
105 69
Entries removed
UBin(4)
109 6D
Find operations
UBin(4)
113 71
--- End ---

The maximum entry length attribute indicates the maximum entry length the index was created with. If the maximum entry length attribute is set to binary 0, the index was created with a maximum entry length of 120 bytes. If the maximum entry length attribute is set to binary 1, the index was created with a maximum entry length from 2,000 to 32,000 bytes. The maximum entry length field in the longer template returns the value of the maximum entry length.

If the bit longer template is set to binary 1, then the longer template is defined starting at offset 113 of the operand 1 template. The longer template is defined as follows:

Offset
Dec Hex
Field Name
Data Type and Length
113 71
Template version
Char(1)
114 72
Index format
Char(1)



0 = Maximum object size of 4 Gigabytes.
1 = Maximum object size of 1 Terabyte.



115 73 Reserved (binary 0) Char(1)
116 74 Maximum entry length UBin(4)
120 78 Reserved (binary 0) Char(56)
176 B0
--- End ---

The first 4 bytes of the materialization identify the total number of bytes provided that may be used by the instruction. This value is supplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes the materialization length invalid  (hex 3803) exception to be signaled.

The second 4 bytes of the materialization identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver is greater than that required to contain the information requested, then the excess bytes are unchanged.

No exceptions other than the materialization length invalid  (hex 3803) exception described previously are signaled in the event that the receiver contains insufficient area for the materialization.

The template identified by the operand 1 space pointer must be 16-byte aligned. Values in the template remain the same as the values specified at the creation of the independent index except that the object identification, context, size of space, index attributes, and index statistics contain current values.

If the entry length is fixed, then the argument length is the value supplied in the template when the index was created. If the entry length is variable, then the argument length field is equal to the length of the longest entry that has ever been inserted into the index.

The number of arguments in the index equals the number of entries inserted minus entries removed. The value of the find operations field is initialized to 0 each time the index is materialized. The value may not be correct after an abnormal system termination.

The field template version identifies the version of the longer template. It must be set to hex 00.

The index format field determines the format of the index. This attribute cannot be modified after the index has been created. If an index is created with a format of hex 01 (maximum size of 1 terabyte), the index cannot be saved to a target release earlier than Version 5 Release 2.

The maximum entry length field returns the maximum length of an index entry for this independent index. Note that indexes with a maximum entry length of 2,001 or more bytes cannot be saved to a target release prior to Version 6 Release 1 Modification 0.

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

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

0A Authorization

10 Damage Encountered

1A Lock State

1C Machine-Dependent

22 Object Access

24 Pointer Specification

2E Resource Control Limit

36 Space Management

38 Template Specification

44 Protection Violation