Materialize Authorized Objects (MATAUOBJ)

Op Code (Hex)	Operand 1	Operand 2	Operand 3
013B	Receiver	User profile or User profile extension	Materialization options/template

Operand 1: Space pointer

Operand 2: System pointer or open pointer

Operand 3: Character scalar

Bound program access
Built-in number for MATAUOBJ is 60. MATAUOBJ ( receiver : address user_profile : address of system pointer OR address of open pointer materialization_options : address )

Description

This instruction materializes the identification and the system pointers to all or selected system objects that are privately owned and/or authorized by a specified user profile or user profile extension, and/or for which the profile is the primary group. For the user profile or user profile extension (operand 2), the materialization options (operand 3) specify object selection criteria and the format and location of the object materialization data. The receiver space (operand 1) always indicates the number of objects materialized, and contains the object materialization data unless the materialization options specify an independent index to contain the data.

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

When format of operand 3 is operand 3 is a Char(1) scalar, operand 3 is viewed as a Char(1) scalar. This option does not permit object selection by type and subtype, does not allow a continuation point to be specified, and returns all object materialization data in the receiver (operand 1). The short template header format is used.

Following are the valid operand 3 values which may be used with the short template header format (operand 1):

Value (hex)	Meaning
07	Verify user profile integrity for all authorized, owned objects, and objects for which profile is the primary group.
11	Materialize count of owned objects.
12	Materialize count of authorized objects.
13	Materialize count of all authorized and owned objects.
14	Materialize count of objects for which profile is the primary group.
15	Materialize count of owned objects and objects for which profile is the primary group.
16	Materialize count of authorized objects and objects for which profile is the primary group.
17	Materialize count of all authorized, owned objects, and objects for which profile is the primary group.
21	Materialize identification of owned objects using short description entry format.
22	Materialize identification of authorized objects using short description entry format.
23	Materialize identification of all authorized and owned objects using short description entry format.
24	Materialize identification of objects for which profile is the primary group using short description entry format.
25	Materialize identification of owned objects and objects for which profile is the primary group using short description entry format.
26	Materialize identification of authorized objects and objects for which profile is the primary group using short description entry format.
27	Materialize identification of all authorized, owned objects, and objects for which profile is the primary group using short description entry format.
31	Materialize identification of owned objects using long description entry format.
32	Materialize identification of authorized objects using long description entry format.
33	Materialize identification of all authorized and owned objects using long description entry format.
34	Materialize identification of objects for which profile is the primary group using long description entry format.
35	Materialize identification of owned objects and objects for which profile is the primary group using long description entry format.
36	Materialize identification of authorized objects and objects for which profile is the primary group using long description entry format.
37	Materialize identification of all authorized, owned objects, and objects for which profile is the primary group using long description entry format.

Usage note:

Although damage in a user profile is extremely rare, option hex 07 can be used to verify the integrity of the user profile without referencing any owned or authorized objects. This allows the caller to quickly verify a user profile before a lengthy procedure, such as a product install. If any integrity problems are found, the user profile will be damaged and a system object damage state (hex 1004) exception will be signaled.

Following are the valid operand 3 values which may be used with the long template header formats (operand 1):

Value (hex)	Meaning
51-57 (D1-D7)	These long template header materialization options are the same as the short template header materialization options 11-17 (hex).
61-67 (E1-E7)	These long template header materialization options are the same as the short template header materialization options 21-27 (hex).
71-77 (F1-F7)	These long template header materialization options are the same as the short template header materialization options 31-37 (hex) except that the context extension is materialized for each object as well.

Options 51-57, 61-67, and 71-77 use the long template header format 1.

Options D1-D7, E1-E7, F1-F7 use the variable-length materialization option template and can use either the long template header format 1 or the long template header format 2, which has larger numbers in it. The header format is selectable by the format of template header field.

When format of operand 3 is set to operand 3 is variable length, operand 3 is viewed as variable-length, must be 16-byte aligned in the space, and has the following format:

Offset

Dec

Hex

Field Name

Data Type and Length

Materialization options

Char(1)

Valid values are hex 91-97, A1-A7, B1-B7, D1-D7, E1-E7, and F1-F7. They have the same meanings as the corresponding values with format of operand 3 set to binary 0 (i.e., hex 91 has the same meaning as hex 11).

Format of operand 3

Bit 0

0 =	Operand 3 is a Char(1) scalar
1 =	Operand 3 is variable length

Materialization identifier

Bits 1-7

Materialization flags

Char(1)

Restrict information scope

Bit 0

This is an input bit which only has meaning when materialization data is being returned in the operand 1 receiver template. When there is more data to be materialized than can be contained in the template, then when this bit is set to binary 1, the number of bytes available for materialization, the number of objects owned by user profile, the number of objects for which the profile is the primary group, and the number of objects privately authorized to user profile output fields are restricted to reflect only the information returned in the template; when set to binary 0, the output fields reflect the total amount of materialization data available, even though the template may not be large enough to contain it all.

More materialization data available

Bit 1

This output bit has meaning only when materialization data is being returned in the operand 1 receiver template. When set to binary 1, it indicates that objects exist beyond those for which materialization data was returned in the template; when set to binary 0 it indicates the end of the objects was reached.

Continuation point specified

Bit 2

This is an input bit. When set to binary 1, it indicates that a continuation point is specified in the continuation point field; when set to binary 0, continuation processing is ignored.

Avoid storage correction

Bit 3

This is an input bit. When set to binary 1, it indicates that storage correction is avoided on owned objects. When set to binary 0, storage correction is performed as required.

Format of template header

Bit 4

0 =	Use long template header format 1
1 =	Use long template header format 2

Reserved (binary 0)

Bits 5-7

Reserved (binary 0)

Char(30)

Independent Index pointer

System pointer

If the pointer does not exist, the instruction returns all object materialization data in the receiver (operand 1). Otherwise it returns only the template header in the receiver and returns the object materialization data in the independent index.

Continuation point

Char(16) or System pointer

If the continuation point specified bit is on, when the instruction begins, if this field contains a system pointer or the storage form of a system pointer, then materialization data is returned for objects found in the profile following the object identified by the continuation point; otherwise, materialization data is returned beginning with the object which is logically first.

Object type/subtype range array

Bin(2)

Indicates the number of object type/subtype ranges specified in the array immediately following. If zero, objects of all types and subtypes are materialized. If larger than zero, only objects included in one or more of the type/subtype ranges specified in the array are materialized.

Object type/subtype array

[*] Char(4)

An array of object type/subtype ranges qualifying the objects materialized. Each array element represents a range of object type/subtypes and has the following format:

Start of range

Char(2)

Object type code

Char(1)

Object subtype code

Char(1)

End of range

Char(2)

Object type code

Char(1)

Object subtype code

Char(1)

--- End ---

All materialization options with the low order bit on (except for option hex 07) also verify and correct the user profile's system storage utilization (storage used on the system ASP and basic ASPs) and varied on independent ASP storage utilization. The corrected storage utilization is not returned by MATAUOBJ and the MATUP instruction must be used to obtain the storage utilization values. The storage utilization is not corrected if either of the following are true:

The extended form of operand 3 is used and a valid continuation point is specified, or
The avoid storage correction field is set to binary 1.

The avoid storage correction field indicates whether or not system storage utilization for the user profile should be verified or corrected at this time. This may improve performance significantly when avoid storage correction is set to binary 1.

The order of materialization is owned objects, objects privately authorized to the user profile, and objects for which the profile is the primary group (as specified in the materialization options operand). No authorizations are stored in the system pointers that are returned.

The template identified by operand 1 must be 16-byte aligned in the space. For options hex 07 through hex 37 and hex 91 through hex B7, the short template header is materialized. It has the following format:

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	Number of objects owned by user profile		Bin(2)
10	A	Number of objects privately authorized to user profile		Bin(2)
12	C	Number of objects for which the user profile is the primary group		Bin(2)
14	E	Reserved (binary 0)		Char(2)
16	10	--- End ---

For options hex 51 through 77, the long template header format 1 is used. The long template header format 1 is also used for options hex D1 through hex F7 if format of template header is set to binary 0. It has the following format:

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	Number of objects owned by user profile		Bin(4)
12	C	Number of objects privately authorized to user profile		Bin(4)
		The following header information is only provided when an option requesting primary group is selected (for example hex 54 - 57, 64 - 67 and 74 - 77 etc).
16	10	Number of objects for which the profile is the primary group		Bin(4)
20	14	Reserved (binary 0)		Char(12)
32	20	--- End ---

For options hex D1 through F7 that have the format of template header set to binary 1, the following long template header format 2 will be used. It has the following format:

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	Number of objects owned by user profile		UBin(8)
16	10	Number of objects privately authorized to user profile		UBin(8)
		The following header information is only provided when an option requesting primary group is selected (for example hex D4 - D7, E4 - E7 and F4 - F7 etc).
24	18	Number of objects for which the profile is the primary group		UBin(8)
32	20	Reserved (binary 0)		Char(32)
64	40	--- End ---

The first 4 bytes of the materialization 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. 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) are signaled in the event that the receiver contains insufficient area for the materialization. If the restrict information scope flag is binary 1, then the field contains the number of bytes materialized, rather than the number of bytes available to be materialized. The number of objects owned by user profile, the number of objects for which the profile is the primary group, and the number of objects privately authorized to user profile will contain the appropriate counts for each type of authorized/owned object. For options greater than hex 07, the authorized/owned objects are verified and these counts are corrected. For option hex 07, the counts are not verified.

If the restrict information scope flag is binary 1, then the number of objects owned by user profile and the number of objects privately authorized by user profile fields reflect the number of objects for which complete materialization data is returned, rather than the total number of such objects.

If no description is requested in the materialization options field, the above constitutes the information available for materialization. If a description (short, long, or long with context extension) is requested by the materialization options field, a description entry is present for each object materialized into the receiver (assuming it is of sufficient size) or into the independent index. Object materialization data is in one of the following formats depending on the materialization options and the object into which it is materialized:

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Short description entry materialized into receiver		Char(32)
0	0		Object type code		Char(1)
1	1		Object subtype code		Char(1)
2	2		Private authorization		Char(2)
4	4		Reserved (binary 0)		Char(10)
14	E		Independent ASP number		Char(2)
16	10		Object pointer		System pointer
32	20	--- End ---

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Long description entry materialized into receiver		Char(64)
0	0		Object type code		Char(1)
1	1		Object subtype code		Char(1)
2	2		Object name		Char(30)
32	20		Private authorization		Char(2)
34	22		Public authorization		Char(2)
36	24		Reserved (binary 0)		Char(10)
46	2E		Independent ASP number		Char(2)
48	30		Object pointer		System pointer
64	40	--- End ---

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Long description entry with context extension materialized into receiver		Char(112)
0	0		Object type code		Char(1)
1	1		Object subtype code		Char(1)
2	2		Object name		Char(30)
32	20		Private authorization		Char(2)
34	22		Public authorization		Char(2)
36	24		Reserved (binary 0)		Char(10)
46	2E		Independent ASP number		Char(2)
48	30		Object pointer		System pointer
64	40		Context type code		Char(1)
65	41		Context subtype code		Char(1)
66	42		Context name		Char(30)
96	60		Context pointer		System pointer
112	70	--- End ---

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Short description entry materialized into independent index		Char(32)
0	0		Entry type code		Char(1)
			Hex `40` = Owned object Hex `80` = Authorized object Hex `A0` = Profile is primary group of object
1	1		Object type code		Char(1)
2	2		Object subtype code		Char(1)
3	3		Private authorization		Char(2)
5	5		Reserved (binary 0)		Char(9)
14	E		Independent ASP number		Char(2)
16	10		Object pointer		System pointer
32	20	--- End ---

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Long description entry materialized into independent index		Char(64)
0	0		Entry type code		Char(1)
			Hex `40` = Owned object Hex `80` = Authorized object Hex `A0` = Profile is primary group of object
1	1		Object type code		Char(1)
2	2		Object subtype code		Char(1)
3	3		Object name		Char(30)
33	21		Private authorization		Char(2)
35	23		Reserved (binary 0)		Char(2)
37	25		Public authorization		Char(2)
39	27		Reserved (binary 0)		Char(7)
46	2E		Independent ASP number		Char(2)
48	30		Object pointer		System pointer
64	40	--- End ---

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Long description entry with context extension materialized into independent index		Char(112)
0	0		Entry type code		Char(1)
			Hex `40` = Owned object Hex `80` = Authorized object Hex `A0` = Profile is primary group of object
1	1		Context type code		Char(1)
2	2		Context subtype code		Char(1)
3	3		Context name		Char(30)
33	21		Object type code		Char(1)
34	22		Object subtype code		Char(1)
35	23		Object name		Char(30)
65	41		Private authorization		Char(2)
67	43		Reserved (binary 0)		Char(2)
69	45		Public authorization		Char(2)
71	47		Reserved (binary 0)		Char(7)
78	4E		Independent ASP number		Char(2)
80	50		Object pointer		System pointer
96	60		Context pointer		System pointer
112	70	--- End ---

Following is the format of the authorization information:

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Private authorization		Char(2)
		(1 = authorized)
0	0		Object control		Bit 0
0	0		Object management		Bit 1
0	0		Authorized pointer		Bit 2
0	0		Space authority		Bit 3
0	0		Retrieve		Bit 4
0	0		Insert		Bit 5
0	0		Delete		Bit 6
0	0		Update		Bit 7
0	0		Ownership (1 = yes)		Bit 8
0	0		Excluded		Bit 9
0	0		Authority list management		Bit 10
0	0		Execute		Bit 11
0	0		Alter		Bit 12
0	0		Reference		Bit 13
0	0		Reserved (binary 0)		Bits 14-15
2	2	Public authorization		Char(2)
		(1 = authorized)
2	2		Object control		Bit 0
2	2		Object management		Bit 1
2	2		Authorized pointer		Bit 2
2	2		Space authority		Bit 3
2	2		Retrieve		Bit 4
2	2		Insert		Bit 5
2	2		Delete		Bit 6
2	2		Update		Bit 7
2	2		Reserved (binary 0)		Bit 8
2	2		Excluded		Bit 9
2	2		Authority list management		Bit 10
2	2		Execute		Bit 11
2	2		Alter		Bit 12
2	2		Reference		Bit 13
2	2		Reserved (binary 0)		Bits 14-15
4	4	--- End ---

When context information is materialized, if the object addressed by the system pointer is not addressed by a context, the context type field is set to hex 00 or if the object is addressed by the machine context, the context type field is set to hex 81. Additionally, in either of these cases, the context pointer is set to the system default pointer does not exist value.

When the more materialization data available flag is binary 1, the pointer to the object within the last entry in the operand 1 receiver template may be specified as the continuation point on a subsequent invocation of this instruction, to cause materialization to continue, starting with the "logically next" object. To determine whether the continuation point is within the owned or authorized objects, the ownership bit in the private authorizations of the last materialized object may be tested. This instruction does not guarantee an atomic snapshot of the user profile or user profile extension across a continuation request.

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

System pointers returned in index entries are not set unless the index is created to contain both pointer and scalar data.
Entry data may be truncated or padded on the right with hex zeroes to conform to the index's key and/or fixed entry lengths.
An entry is added to the index for each qualifying object. Previously existing entries which are thereby duplicated are replaced.
In order to ensure that index entries inserted within the same execution of this instruction are not duplicates of each other, the index entry length (if fixed) and key length (if keyed) must be sufficiently large to include the object pointer within the entry data.

Authorization Required

Operational
- Operand 2
All object special authority
- Operand 2 if user profile extension
Execute
- Contexts referenced for address resolution
Retrieve
- Operand 2 if materializing owned objects
Insert
- Independent index if identified by operand 3

Lock Enforcement

Materialize
- Contexts referenced for address resolution
- Operand 2 if materializing owned objects
Modify
- Independent index if identified by operand 3

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
0A04 Special Authorization Required

10 Damage Encountered

1002 Machine Context Damage State
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
1C04 Object 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
2204 Object Not Eligible for Operation
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

32 Scalar Specification

3203 Scalar Value Invalid

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