Materialize Authorized Objects (MATAUOBJ)

Instruction Syntax

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 Notes

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
0
0
Materialization options
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).
Char(1)
0
0
  • Format of operand 3
    0 =
    Operand 3 is a Char(1) scalar
    1 =
    Operand 3 is variable length
  • Bit 0
0 0
  • Materialization identifier
  • Bits 1-7
1 1 Materialization flags Char(1)
1
1
  • Restrict information scope
    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.
  • Bit 0
1
1
  • More materialization data available
    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.
  • Bit 1
1
1
  • Continuation point specified
    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.
  • Bit 2
1
1
  • Avoid storage correction
    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.
  • Bit 3
1
1
  • Format of template header
    0 =
    Use long template header format 1
    1 =
    Use long template header format 2
  • Bit 4
1 1
  • Reserved (binary 0)
  • Bits 5-7
2 2 Reserved (binary 0) Char(30)
32
20
Independent Index 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.
System pointer
48
30
Continuation point
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.
Char(16)
64
40
Object type/subtype range array
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.
Bin(2)
66
42
Object type/subtype array
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:
[*] Char(4)
66 42
  • Start of range
  • Char(2)
66 42
    • Object type code
    • Char(1)
67 43
    • Object subtype code
    • Char(1)
68 44
  • End of range
  • Char(2)
68 44
    • Object type code
    • Char(1)
69 45
    • 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
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).
Bin(4)
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
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).
UBin(8)
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
    Hex 40 =
    Owned object
    Hex 80 =
    Authorized object
    Hex A0 =
    Profile is primary group of object
  • Char(1)
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
    Hex 40 =
    Owned object
    Hex 80 =
    Authorized object
    Hex A0 =
    Profile is primary group of object
  • Char(1)
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
    Hex 40 =
    Owned object
    Hex 80 =
    Authorized object
    Hex A0 =
    Profile is primary group of object
  • Char(1)
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
(1 = authorized)
Char(2)
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
(1 = authorized)
Char(2)
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