Create Independent Index (CRTINX)


Op Code (Hex) Operand 1 Operand 2

0446 Index Index description template

Operand 1: System pointer.

Operand 2: Space pointer.

Bound program access
Built-in number for CRTINX is 34.
CRTINX (
        index                        : address of system pointer
        index_description_template   : address
)

Description

This instruction creates an independent index based on the index template specified by operand 2 and returns addressability to the index in a system pointer stored in the addressing object specified by operand 1.

The format of the index description template pointed to by operand 2 is as follows (must be aligned on a 16-byte multiple):

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Template 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 = Permanent



40 28
Space attribute
Bit 1



0 = Fixed-length
1 = Variable-length



40 28
Initial context
Bit 2



0 = Do not insert addressability in context
1 = Insert addressability in context



40 28
Access group
Bit 3



0 = Do not create as member of access group
1 = Create as member of access group



40 28
Reserved (binary 0)
Bits 4-6
40 28
Initial owner specified
Bit 7



0 = No
1 = Yes



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



0 = Initialize
1 = Do not initialize



40 28
Reserved (binary 0)
Bits 14-19






40 28 Restrict index operations from user state at all security levels Bit 20
0 = Allow index operations from user state, according to domain semantics
1 = Prevent index operations from user state at all security levels.


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



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



40 28
Reserved (binary 0)
Bits 22-31






44 2C
Recovery options
Char(4)
44 2C
Reserved (binary 0)
Char(2)
46 2E
ASP number
Char(2)
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. If the size of space field is 0, this value must be specified.
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.
The value of this field is ignored when a value of 1 is given for the machine chooses space alignment field.


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 performed.

Usage note: On all current and foreseen implementations of the machine, a substantial performance penalty is incurred by any access to space data in the first (partial) page of a space created with this value. This value should only be used when absolutely required for space capacity needs.

1 = The machine will choose the space alignment most beneficial to performance, which may reduce maximum space capacity. When this value is specified, the space alignment field is ignored, but the alignment chosen will be a multiple of 512.



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



0 = Process default main storage pool is used for object.
1 = Machine default main storage pool is 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(3)






60 3C
Extension offset
Bin(4)
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 Obsolete Bit 5
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
--- End ---

Note: This instruction ignores the values associated with the fields annotated with a plus sign (+).
The template identified by operand 2 must be 16-byte aligned.

There are two ways the operand 2 template can be extended. When the longer template field is set to binary 1, the fields starting at offset 101 in the longer template are defined. Also, if the extension offset is non-zero, a template extension is located by the extension offset field.

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

Offset
Dec Hex
Field Name
Data Type and Length
101 65
Reserved (binary 0)
Char(12)
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(32)
148 94 Reserved (binary 0) Char(56)

204 CC
--- End ---

If the extension offset is non-zero, a template extension is defined at this offset from the beginning of the operand 2 template. The template extension must be 16-byte aligned in the space. The following is the format of the template extension:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
User profile
System pointer
16 10
Reserved (binary 0)
Char(4)
20 14
Domain assigned to the object
Char(2)
22 16
Reserved (binary 0)
Char(42)
64 40
--- End ---

If the created object is permanent, it is owned by the user profile governing thread execution. The owning user profile is implicitly assigned all private authority states for the object. The storage occupied by the created object is charged to this owning user profile. If the created object is temporary, there is no owning user profile, and all authority states are assigned as public. Storage occupied by the created object is charged to the process associated with the creating thread.

The object identification specifies the symbolic name that identifies the space within the machine. An object type of hex 0E is implicitly supplied by the machine. The object identification is used to identify the object on materialize instructions as well as to locate the object in a context that addresses the object.

The existence attribute specifies that the index is to be created as a permanent or a temporary object. A temporary index, if not explicitly destroyed by the user, is implicitly destroyed by the machine when machine processing is terminated.

Permanent index objects cannot be created by user state programs when the system security level is 40 or above.

A space may be associated with the created object. The space may be fixed or variable in size, as specified by the space attribute field. The initial allocation is as specified in the size of space field. The machine allocates a space of at least the size specified. The actual size allocated is dependent on an algorithm defined by a specific implementation.

If the initial context creation attribute field indicates that addressability is to be inserted in a context, the context field must be a system pointer that identifies a context where addressability to the newly created object is to be placed. If the initial context indicates that addressability is not to be placed in a context, the context field is ignored.

If the access group creation attribute field indicates that the object is to be created in an access group, the access group field must be a system pointer that identifies an access group in which the object is to be created. The existence attribute must be temporary for an object to be in an access group. If the object is not to be created in an access group, the access group field is ignored.

The initial owner specified creation option controls whether or not the initial owner of the independent index is to be the user profile specified in the template. When yes is specified, initial ownership is assigned to the user profile specified in the user profile field of the template extension. When no is specified, initial ownership is assigned to the user profile governing thread execution. The initial owner user profile is implicitly assigned all authority states for the object. The storage occupied by the object is charged to the initial owner.

The initialize space creation option controls whether or not the space is to be initialized. When initialize is specified, each byte of the space is initialized to a value specified by the initial value of space field. Additionally, when the space is extended in size, this byte value is also used to initialize the new allocation. When do not initialize is specified, the initial value of space field is ignored and the initial value of the bytes of the space are unpredictable.

When do not initialize is specified for a space, internal machine algorithms do ensure that any storage resources last used for allocations to another object which are reused to satisfy allocations for the space are reset to a machine default value to avoid possible access of data which may have been stored in the other object. To the contrary, reusage of storage areas previously used by the space object are not reset, thereby exposing subsequent reallocations of those storage areas within the space to access of the data which was previously stored within them.

The restrict index operations from user state at all security levels field is used to indicate whether index operations on this particular index object can be run from user state. This attribute is similar to domain, but applies at all security levels.

The always enforce hardware storage protection of associated space field is used to specify whether the hardware storage protection defined by the machine for this object type's associated space should be enforced at all times, or only when hardware storage protection is enforced for all storage.

The ASP number field specifies the ASP number of the ASP on which the object is to be allocated. A value of 0 indicates an ASP number is not specified and results in the default of allocating the object in the system ASP. Allocation on the system ASP can only be done implicitly by not specifying an ASP number. The only nonzero values allowed are 2 through 255 which provide for explicit allocation of objects on a user ASP or an independent ASP. The ASP number must specify an existing ASP. An ASP number of 1 or greater than 255 results in a template value invalid  (hex 3801) exception being signalled. The given ASP number must be currently configured on the system otherwise an auxiliary storage pool number invalid  (hex 1C09) exception is signalled. If the ASP number identifies an independent ASP, there must be an existing active logical unit description for the independent ASP otherwise an independent asp varied off  (hex 1C11) exception is signalled. A temporary object cannot be created in an ASP other than the system ASP. If this is attempted, a template value invalid  (hex 3801) exception is signalled. If the ASP number identifies an independent ASP, or initial context indicates that addressability is to be inserted into a context that resides in an independent ASP, then both must indicate the same independent ASP or belong to the same ASP group or else a template value invalid  (hex 3801) exception is signalled. The ASP number of an object can be materialized, but cannot be modified.

The performance class field provides information allowing the machine to more effectively manage the object considering the overall performance objectives of operations involving the index.

If the entry length attribute field specifies fixed-length entries, the entry length of every index entry is established at creation by the value in the argument length field of the index description template. If the entry length attribute field specifies variable-length entries, then entries will be variable-length (the length of each entry is supplied when the entry is inserted), and the argument length field is ignored.

If the immediate update field specifies that an immediate update should occur, then every update to the index will be written to auxiliary storage after every insert or remove operation. This option is ignored if the existence attributes field is set to binary 0 (temporary). In this case, the value of the immediate update field is assumed to be binary 0 and updates will not be written to auxiliary storage after every insert or remove operation.

If the key insertion field specifies insertion by key, then the key length field must be specified. This allows the specification of a portion of the argument (the key), which may be manipulated in either of the following ways in the Insert Index Entry (INSINXEN) instruction:

The entry format field designates the index entries as containing both pointers and scalar data or scalar data only. The both pointers and scalar data field can be used only for indexes with fixed-length entries. If the index is created to contain both pointers and data, then If the index is created to contain scalar data only, then: The optimized processing mode index attribute field is used to designate whether the index should be created and maintained in a manner that optimizes performance for either random or sequential operations.

The key length field specifies the length of the key for the entries that are inserted into the index. The argument length specifies the length of the entries when fixed length entries are used.

The key length must have a value less than or equal to the argument length whether specified during creation (for fixed-length entries) or during insertion (for variable length). The key length is not used if the key insertion field specifies no insertion by key.

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 object size of 1 terabyte), the index cannot be saved to a target release earlier than Version 5 Release 2. If the longer template is not defined (i.e. the field longer template is set to binary 0), the index format field defaults to a value of hex 00 (maximum object size of 4 gigabytes).

The maximum entry length field indicates the maximum entry length for the index. If the field is set to 0, the default maximum entry length of 2,000 bytes will be used. Otherwise, a valid maximum entry length of 2,000 to 32,000 bytes must be used. A value of less than 2,000 or greater than 32,000 bytes will result in a template value invalid  (hex 3801) exception being signalled. If specifying a maximum entry length of 2,001 or more bytes, the index format field must be set to hex 01. Otherwise, a template value invalid  (hex 3801) exception will be signalled. The maximum entry length is set at create time and cannot be changed later on. An independent index which is created with a maximum entry length of 2,001 or more bytes cannot be saved to a target release earlier than Version 6 Release 1. Note that indexes created before Version 3 Release 6 could have been created with a maximum entry length of 120 bytes or 2,000 bytes. The MATINXAT instruction can be used to materialize this attribute.

If the index coherency tracking attribute field specifies track index coherency then additional checking is done when the index is referenced for the first time after an IPL to determine if the index was coherent at system termination. If the index is found to not be coherent then the index is marked as damaged. The index is not coherent while the internal structure is being modified, for example, during an insert or a remove operation.

If the system is not able to save its main storage at system termination then it can not be determined whether or not the index is coherent and the index is marked as damaged the next time it is referenced.

If the index coherency tracking attribute field specifies do not track index coherency then no additional checking is done when the index is referenced for the first time after an IPL.

The extension offset specifies the byte offset from the beginning of the operand 2 template to the beginning of the template extension. An offset value of zero specifies that the template extension is not provided. A negative offset value is invalid. A non-zero offset must be a multiple of 16 (to cause 16-byte alignment of the extension). Except for these restrictions, the offset value is not verified for correctness relative to the location of other portions of the create template.

The domain assigned to the object field in the template extension allows the user of this instruction to override the domain for this object that would otherwise be chosen by the machine. Valid values for this field are:

Domain field Domain assigned to the object
Hex 0000 The domain will be chosen by the machine.
Hex 0001 The domain will be 'User'.

Any value specified for the domain assigned field other than those listed above will result in a template value invalid  (hex 3801) exception being signalled.

Limitations (Subject to Change)

The following are limits that apply to the functions performed by this instruction. These limits may change on different implementations of the machine.

The size of the object specific portion of the object is limited to a maximum of 4 gigabytes or 1 terabyte, depending on the value of the index format field. This size is dependent upon the amount of storage needed for the number and size of index entries and excludes the size of the associated space, if any.

The size of the associated space for this object is limited to a maximum of 16MB-32 bytes if the machine does not choose the space alignment and 0 is specified for the space alignment field. The size of the associated space for this object is limited to a maximum of 16MB-512 bytes if the machine does not choose the space alignment and 1 is specified for the space alignment field. The maximum size of an associated space for this object if the machine chooses the space alignment is returned by option Hex 0003 of MATMDATA.

Authorization Required

Lock Enforcement

Exceptions

02 Access Group

06 Addressing

08 Argument/Parameter

0A Authorization

0E Context Operation

10 Damage Encountered

1A Lock State

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

2E Resource Control Limit

36 Space Management

38 Template Specification

44 Protection Violation