Materialize Authority List (MATAL)


Op Code (Hex) Operand 1 Operand 2 Operand 3
01B3 Receiver Authority list or Authority list extension Materialization options
Operand 1: Space pointer

Operand 2: System pointer or open pointer

Operand 3: Space pointer

Bound program access
Built-in number for MATAL is 59.
MATAL (
       receiver                  : address
       authority_list            : address of system pointer OR
                                   address of open pointer
       materialization_options   : address
)

Description

Based on the contents of the materialization options specified by operand 3, the symbolic identification and/or system pointers to all, or a selected set, of the objects contained in the authority list or authority list extension specified by operand 2 are materialized into the receiver specified by operand 1.

A space pointer machine object may not be specified for operand 2.

The materialization options operand should be 16-byte aligned and has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Materialization control
Char(2)
0 0
Information requirements
Char(1)



Hex 12 = Materialize count of entries matching the criteria into the receiver
Hex 22 = Materialize identification of entries matching the criteria and return information using short description format into the receiver
Hex 32 = Materialize identification of entries matching the criteria and return information using long description format into the receiver
Hex 72 = Materialize identification of entries matching the criteria and return information using long description format into an independent index.


1 1
Selection criteria
Char(1)



Hex 00 = All authority list or authority list extension entries
Hex 01 = Type code selection
Hex 02 = Type code/subtype code selection
Hex 03 = Array type code/subtype code selection.


2 2
Reserved (binary 0)
Bin(2)
4 4
Type code
Char(1)
5 5
Subtype code
Char(1)
6 6 Number of array elements UBin(2)
8 8 Materialize size value (Bound program) UBin(8)
8 8 Materialize size value (Non-Bound program) Char(8)
16 10 Independent index System pointer
32 20 Array of type/subtype ranges [*] Char(4)
32 20 Starting range Char(2)
32 20 Object type code Char(1)
33 21 Object subtype code Char(1)
34 22 Ending range Char(2)
34 22 Object type code Char(1)
35 23 Object subtype code Char(1)
* *
--- End ---

The information requirements field specifies the type of materialization and where materialization data is returned.

The selection criteria field specifies the criteria to be used in selecting the authority list or authority list extension entries for which information is to be presented.

The type code identifies the type of MI object to select.

The subtype code identifies the subtype of the MI object to select. Only objects with the specified type code and subtype code are selected.

The number of array elements is the number of start and end ranges in array of type/subtype ranges.

The materialize size value is the same as the number of bytes available for materialization in the receiver's materialization size specification except it is an 8 byte value. Both the 8-byte value and the 4-byte value will be the same unless the size is over 2,147,483,647 then the 4 byte number will be -1(hex FFFFFFFF) and only the 8-byte number will be correct.

The independent index points to the independent index that the materialization data will be placed in when information requirements indicates data is going to an independent index.

The following considerations apply when materialization data is returned in an independent index:

The array of type/subtype ranges qualifies the objects materialized when the selection criteria is array type code/subtype code selection(hex 03). For other values of selection criteria, the first array element should be hex zeros. Each array element represents a range of object type/subtypes.

The starting range specifies the starting range of object type/subtype codes to select. The ending range specifies the ending range of object type/subtype codes to select. The starting range should be less than or equal to the ending range. An object type code of hex 00 is invalid and will be interpreted as hex 01. To select only by object type code, set the starting range and ending range object type code to the same value and set starting range object subtype code to hex 00 and set ending range object subtype code to hex FF.

The format of the receiver (operand 1) 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
Authority list identification
Char(32)
8 8
Object type
Char(1)
9 9
Object subtype
Char(1)
10 A
Object name
Char(30)
40 28
Authority list creation options
Char(4)
40 28
Existence attributes
Bit 0



1 = Permanent (always permanent)


40 28
Space attribute
Bit 1



0 = Fixed length
1 = Variable length


40 28
Reserved (binary 0)
Bits 2-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)
57 39
Reserved
Char(7)
64 40
Context
System pointer
80 50
Reserved
Char(16)
96 60
Authority list attributes
Char(4)
96 60
Override specific object authority
Bit 0



0 = No
1 = Yes


96 60
Reserved (binary 0)
Bits 1-31
100 64
Reserved (binary 0)
Char(28)
128 80
Entries header
Char(16)
128 80
Number of entries available
UBin(4)
132 84 Reserved Char(4)
136 88 Number of entries available(8-byte value) (Bound program) UBin(8)
136 88 Number of entries available(8-byte value) (Non-Bound program) Char(8)
144 90
Description entries
[*] Char(*)
* *
--- End ---

The first four bytes of the materialization output identify the total number of bytes provided for use 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. If this value is over 2,147,483,647(hex 7FFFFFFF), then the 4 byte number will be set to -1(hex FFFFFFFF) and the correct value will be in the materialize size value in the materialization options template. The instruction materializes as many bytes and pointers as can be contained in the receiver. If the byte area identified by the receiver is greater than that required to contain the information requested for materialization, the excess bytes are unchanged. No exceptions are signaled in the event that the receiver contains insufficient area for the materialization, other than the materialization length invalid  (hex 3803) exception signaled above. If an independent index is used for the materialization data, then no description entries are put into the receiver.

The creation attributes (bytes 40 through 127) are not returned when materializing an authority list extension. These fields of the template will be set to hex zero. The fields are:

The authority list identification specifies the symbolic name that identifies the object within the machine. An object type of hex 1B is returned. The object identification is used to identify the object on materialize instructions as well as to locate the object in a context that addresses it.

A space may be associated with the authority list. The space may be fixed or variable in size, as specified by the space attribute field. The size of the space in bytes is returned in the size of space field. A fixed size space of zero length indicates the authority list does not have a space associated with it.

The initial value of space field indicates the value used to initialize each byte of the space. Additionally, when the space is extended in size, this byte value is also used to initialize the new allocation.

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

The context field identifies the context that contains addressability to the authority list. A null pointer value is returned if the authority list is not addressed by a context.

The override specific object authority authority list attribute specifies whether or not the specific authorities that users may have directly to an object are to be overridden for objects in the authority list. The authorities to override are both the object's public authority, if it has any, and the private authorities which users may hold to the specific object. When override specific object authority is set to binary 1, authorization verification for an object in the authority list ignores the specific object authority and instead proceeds directly to checking the authority held to the authority list to determine if the authority check can be satisfied.

The number of entries available fields specify the number of authority list entries which satisfied the selection criteria and were therefore materialized. Both the 8-byte value and the 4-byte value will be the same unless the number of entries available is over 4,294,967,294 then the 4 byte number will be 4,294,967,295(hex FFFFFFFF) and only the 8-byte number will be correct. A value of zero indicates no entries were available.

If no description (information requirements = hex 12) or long description into independent index (information requirements = hex 72) is requested in the materialization options operand, the above template describes the information available for materialization into the receiver.

If a description (short or long) is requested by the materialization options operand, a description entry is present (assuming a sufficient size receiver) for each object materialized into the receiver. One of the following description entry formats may be selected.

Short description entry (information requirements = hex 22)

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Short description entry
Char(32)
0 0
Object identification
Char(2)
0 0
Object type code
Char(1)
1 1
Object subtype code
Char(1)
2 2
Reserved
Char(14)
16 10
System object
System pointer
32 20
--- End ---

Long description entry (information requirements = hex 32)

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Long description entry
Char(128)
0 0
Object identification
Char(32)
0 0
Object type code
Char(1)
1 1
Object subtype code
Char(1)
2 2
Object name
Char(30)
32 20
Reserved
Char(16)
48 30
System object
System pointer
64 40
Object owning user profile
System pointer
80 50
Context identification
Char(48)
80 50
Context type code
Char(1)
81 51
Context subtype code
Char(1)
82 52
Context name
Char(30)
112 70
Context pointer
System pointer
128 80
--- End ---

Independent index long description entry (information requirements=hex 72)

Offset
Dec Hex Field Name Data Type and Length
0 0 Long description entry materialized into independent index Char(112)
0 0 Context identification Char(32)
0 0 Context type code Char(1)
1 1 Context subtype code Char(1)
2 2 Context name Char(30)
32 20 Object identification Char(32)
32 20 Object type code Char(1)
33 21 Object subtype code Char(1)
34 22 Object name Char(30)
64 40 System object System pointer
80 50 Context pointer System pointer
96 60 Object owning user profile System pointer
112 70 --- End ---

The object identification information (in the short and long description entries), is present for each entry in the authority list or authority list extension that satisfies the search criteria. The object type code identifies the type of the MI object. The object subtype code identifies the subtype of the MI object. The object name identifies the name of the object.

The system object field points to the object contained in the authority list or authority list extension.

The object owning user profile points to the user profile of the owner of the object. When an authority list extension is materialized, a null pointer value will be returned for object owning user profile.

The context identification identifies the context that contains addressability to the system object. The context type code identifies the type of the context. The context subtype code identifies the subtype of the context. The context name identifies the name of the context. If the system object is not addressed by a context, the context type code field is set to hex 00 or if the object is addressed by a machine context, the context type code field is set to hex 81. Additionally, in either of these cases, the context pointer is set to a null pointer value.

The context pointer field returns a pointer to the context that contains addressability to the system object. A null pointer value is returned if the system object is not addressed by a context.

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

0A Authorization

10 Damage Encountered

1A Lock State

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

2E Resource Control Limit

32 Scalar Specification

36 Space Management

38 Template Specification

44 Protection Violation