Materialize Independent Index Attributes (MATINXAT)

Instruction Syntax

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
    0 = Temporary
    1 = Reserved
  • Bit 0
40
28
  • Space attribute
    0 = Fixed-length
    1 = Variable-length
  • Bit 1
40
28
  • Context
    0 = Addressability not in context
    1 = Addressability in context
  • Bit 2
40
28
  • Access group
    0 = Not a member of access group
    1 = Member of access group
  • Bit 3
40 28
  • Reserved (binary 0)
  • Bits 4-12
40
28
  • Initialize space
    0 = Initialize
    1 = Do not initialize
  • Bit 13
40
28
  • Automatically extend space
    0 = No
    1 = Yes
  • Bit 14
40
28
  • Hardware storage protection level
    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
  • Bits 15-16
40
28
  • Reserved (binary 0)
  • Bits 17-19
40
28
  • Always enforce hardware storage protection of this index
    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.
  • Bit 20
40
28
  • Always enforce hardware storage protection of the associated space
    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.
  • Bit 21
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
    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.
  • Bit 0
53 35
  • Reserved (binary 0)
  • Bits 1-2
53
35
  • Machine chooses space alignment
    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.
  • Bit 3
53 35
  • Reserved (binary 0)
  • Bit 4
53
35
  • Main storage pool selection
    0 = Process default main storage pool used for object.
    1 = Machine default main storage pool used for object.
  • Bit 5
53 35
  • Reserved (binary 0)
  • Bit 6
53
35
  • Block transfer on implicit access state modification
    0 =
    Transfer the minimum storage transfer size for this object.
    1 =
    Transfer the machine default storage transfer size for this object.
  • Bit 7
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
    0 = Fixed-length entries
    1 = Variable-length entries
  • Bit 0
96
60
  • Immediate update
    0 = No immediate update
    1 = Immediate update
  • Bit 1
96
60
  • Key insertion
    0 = No insertion by key
    1 = Insertion by key
  • Bit 2
96
60
  • Entry format
    0 = Scalar data only
    1 = Both pointers and scalar data
  • Bit 3
96
60
  • Optimized processing mode
    0 = Optimize for random references
    1 = Optimize for sequential references
  • Bit 4
96
60
  • Maximum entry length attribute
    0 = Maximum entry length is 120 bytes
    1 = Maximum entry length is 2,000 to 32,000 bytes
  • Bit 5
96
60
  • Index coherency tracking
    0 = Do not track index coherency
    1 = Track index coherency
  • Bit 6
96
60
  • Longer template
    0 = The template is the original size
    1 = The template is longer
  • Bit 7
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
0 = Maximum object size of 4 Gigabytes.
1 = Maximum object size of 1 Terabyte.
Char(1)
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

  • Operational
    • 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
  • 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
    • 3803 Materialization Length Invalid
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed