Materialize User Profile (MATUP)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2
013E Receiver User profile
Operand 1: Space pointer.

Operand 2: System pointer or space pointer data object.

Bound Program Access 
Built-in number for MATUP is 62.
MATUP (
       receiver       : address
       user_profile   : address of system pointer OR
                        address of space pointer(16)
)

Description:

The attributes of the user profile specified by operand 2 are materialized into the receiver specified by operand 1. (Operand 2 may refer to a materialization template that contains a system pointer to the user profile.)

The receiver identified by operand 1 must be 16-byte aligned in the space. The following is the format of the materialized information:

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 attribute
    1 =
    Permanent
  • Bit 0
40
28
  • Space attribute
    0 =
    Fixed-length
    1 =
    Variable-length
  • Bit 1
40 28
  • Reserved (binary 1)
  • Bit 2
40 28
  • Reserved (binary 0)
  • Bits 3-12
40 28
  • Initialize space
  • Bit 13
40 28
  • Reserved (binary 0)
  • Bits 14-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 (binary 0) Char(7)
64 40 Reserved (binary 0) Char(16)
80 50 Reserved (binary 0) Char(16)
96
60
Privileged instructions
(1 =  authorized)
Char(4)
96 60
  • Create Logical Unit Description
  • Bit 0
96 60
  • Create Network Description
  • Bit 1
96 60
  • Create Controller Description
  • Bit 2
96 60
  • Create User Profile
  • Bit 3
96 60
  • Modify User Profile
  • Bit 4
96 60
  • Diagnose
  • Bit 5
96 60
  • Terminate Machine Processing
  • Bit 6
96 60
  • Initiate Process
  • Bit 7
96 60
  • Modify Resource Management Controls
  • Bit 8
96 60
  • Create Mode Description
  • Bit 9
96 60
  • Create Class of Service Description
  • Bit 10
96 60
  • Reserved (binary 0)
  • Bits 11-31
100
64
Special authorizations
(1 =  authorized)
Char(4)
100 64
  • All object authority
  • Bit 0
100 64
  • Load (unrestricted)
  • Bit 1
100 64
  • Dump (unrestricted)
  • Bit 2
100 64
  • Suspend object (unrestricted)
  • Bit 3
100 64
  • Load (restricted)
  • Bit 4
100 64
  • Dump (restricted)
  • Bit 5
100 64
  • Suspend object (restricted)
  • Bit 6
100 64
  • Process control
  • Bit 7
100 64
  • Reserved (binary 0)
  • Bit 8
100 64
  • Service authority
  • Bit 9
100 64
  • Auditor authority
  • Bit 10
100 64
  • Spool control
  • Bit 11
100 64
  • I/O system configuration
  • Bit 12
100 64
  • Reserved (binary 0)
  • Bits 13-23
100 64
  • Modify machine attributes
  • Bits 24-31
100 64
    • Group 2
    • Bit 24
100 64
    • Group 3
    • Bit 25
100 64
    • Group 4
    • Bit 26
100 64
    • Group 5
    • Bit 27
100 64
    • Group 6
    • Bit 28
100 64
    • Group 7
    • Bit 29
100 64
    • Group 8
    • Bit 30
100
64
    • Group 9
      Note: Group 1 requires no authorization.
    • Bit 31
104 68 System storage authorization (small) Bin(4)
108 6C System storage utilization (small) Bin(4)
112 70 User profile status Char(2)
112
70
  • Verify storage utilization
    0 =
    Storage utilization has been verified and is correct
    1 =
    Storage utilization has not been verified and may not be correct
  • Bit 0
112
70
  • Storage count format
    0 =
    Storage utilization/authorization is in the small count format
    1 =
    Storage utilization/authorization is in the large count format
  • Bit 1
112 70
  • Reserved (binary 0)
  • Bits 2-15
114 72 Identification flags Char(1)
114 72
  • Reserved (binary 0)
  • Bits 0-1
114 72
  • User identification specified
  • Bit 2
114 72
  • Group identification specified
  • Bit 3
114 72
  • Reserved (binary 0)
  • Bits 4-7
115 73 Object audit level Char(1)
115 73
  • Reserved (binary 0)
  • Bits 0-5
115 73
  • Audit object changes for this user
  • Bit 6
115 73
  • Audit object reads for this user
  • Bit 7
116 74 User audit level 1 Char(4)
116
74
  • Operating system defined
  • Bits 0-1
116
74
  • Security function auditing
    0 =
    Security function auditing is not active
    1 =
    Security function auditing is active
  • Bit 2
116
74
  • Operating system defined
  • Bits 3-6
116
74
  • Signal action auditing
    0 =
    Signal action auditing is not active
    1 =
    Signal action auditing is active
  • Bit 7
116 74
  • Operating system defined
  • Bits 8-31
 
 
  
120 78 User audit level 2 Char(4)
120
78
  • Program adoption auditing
    0 =
    Program adoption auditing is not active
    1 =
    Program adoption auditing is active
  • Bit 0
120 78
  • Reserved (binary 0)
  • Bits 1-31
124 7C User identification UBin(4)
128 80 Group identification UBin(4)
132 84 Number of independent ASP entries UBin(2)
134 86 Output flags Char(1)
134
86
  • Format of counts of profiles
    0 =
    Counts as small numbers
    1 =
    Counts as large numbers
  • Bit 0
134 86
  • Reserved (binary 0)
  • Bits 1-7
135 87 Reserved (binary 0) Char(1)
136 88 User audit level 3 Char(8)
136 88
  • Operating system defined
  • Char(8)
 
 
  
144 90 Counts of profile entries Char(64)
208 D0 Reserved (binary 0) Char(8)
216 D8 Total storage utilization Char(8)
224
E0
Storage information
Char(*)
*
*
--- 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 and the receiver may contain a partial individual independent ASP information entry.

System storage authorization (small) is the amount of auxiliary storage (in units of 1,024 bytes) that this user profile is authorized to use in the system ASP and basic ASPs. The combined storage of all objects this user profile owns in the system ASP and basic ASPs may not exceed this value. A value of 2,147,483,647 (hex 7FFFFFFF) indicates that this user profile has no limit on the amount of storage it may use (*NOMAX). If the user profile is authorized to use storage that is equal to or greater than 2 terabytes, and the materialize for given Licensed Internal Code release bit is set to binary 1, and the target Licensed Internal Code release to materialize field is set to a release prior to V7R2M0, then system storage authorization (small) will be set to *NOMAX. Otherwise, a value of -1 (hex FFFFFFFF) will be used to indicate that the profile is authorized to use storage that is equal to or greater than 2 terabytes, and the system storage authorization (large) field should be used to get an accurate value for this attribute. This same convention also applies to the independent ASP storage authorization (small) field.

System storage utilization (small) is the current amount of auxiliary storage (in units of 1,024 bytes) allocated for the storage of objects owned by this user profile in the system ASP and basic ASPs. A value of -1 (hex FFFFFFFF) indicates that the amount of auxiliary storage allocated is equal to or greater than 2 terabytes, and the system storage utilization (large) field should be used to get an accurate value of this attribute. This same convention also applies to the independent ASP storage utilization (small) field.

The verify storage utilization field returns either binary 0 or 1. If binary 0 is returned, the value returned in the total storage utilization field has been verified and it is correct. That is, all values returned in the system storage utilization and independent ASP storage utilization for varied-on independent ASPs have been verified and they are correct. If binary 1 is returned, the value returned in the total storage utilization field has not been verified and may not be correct. That is, at least one of the values returned in system storage utilization and independent ASP storage utilization for varied on independent ASPs have not been verified and may not be correct. The MATAUOBJ instruction can be used to correct all the values of storage utilization. After MATAUOBJ is issued to correct the storage utilization values, the MATUP instruction must be issued again to retrieve the corrected values.

Note: The storage utilization of independent ASPs that are not varied on is not verified.

The security function auditing field specifies whether an audit record is created for identified security-related functions. (See specific instructions for which security-related functions an audit record is to be created.)

User audit level 1, user audit level 2, and user audit level 3 specify the level of activity that is audited for this user profile.

The signal action auditing field specifies whether an audit record is created when a signal, that is not ignored, is delivered to a thread.

The program adoption auditing field specifies whether an audit record is created when authority is obtained through program adoption.

The number of independent ASP entries field is the total number of individual independent ASP information entries. 223 is returned even if number of bytes provided is not large enough to contain all of the individual independent ASP information entries.

Counts of profile entries refers to the total number of entries for each type of entry that a profile can have. This area can be formated in small or large format for the counts, and is controlled by the input bit, count format, in the materialization options of the materialization template. The output bit format of counts of profiles in the output flags identifies the format of the counts in the receiver.

The small format, as shown below, is used when the format of counts of profiles is binary zero.

Offset  
Dec Hex Field Name Data Type and Length
144 90 Small counts of profile entries Char(64)
144 90
  • Ownership entries
  • Char(8)
144 90
    • Number of used entries
    • UBin(4)
148 94
    • Number of possible available entries
    • UBin(4)
152 98
  • Authorization entries
  • Char(8)
152 98
    • Number of used entries
    • UBin(4)
156 9C
    • Number of possible available entries
    • UBin(4)
160 A0
  • Authorized user entries
  • Char(8)
160 A0
    • Number of used entries
    • UBin(4)
164 A4
    • Number of possible available entries
    • UBin(4)
168 A8
  • Primary group entries
  • Char(8)
168 A8
    • Number of used entries
    • UBin(4)
172 AC
    • Number of possible available entries
    • UBin(4)
176 B0
  • Reserved (binary 0)
  • Char(32)
208
D0
--- End ---
 

The large format, as shown below, is used when the format of counts of profiles is binary one.

Offset  
Dec Hex Field Name Data Type and Length
144 90 Large counts of profile entries Char(64)
144 90
  • Ownership entries
  • Char(16)
144 90
    • Number of used entries
    • UBin(8)
152 98
    • Number of possible available entries
    • UBin(8)
160 A0
  • Authorization entries
  • Char(16)
160 A0
    • Number of used entries
    • UBin(8)
168 A8
    • Number of possible available entries
    • UBin(8)
176 B0
  • Authorized user entries
  • Char(16)
176 B0
    • Number of used entries
    • UBin(8)
184 B8
    • Number of possible available entries
    • UBin(8)
192 C0
  • Primary group entries
  • Char(16)
192 C0
    • Number of used entries
    • UBin(8)
200 C8
    • Number of possible available entries
    • UBin(8)
208
D0
--- End ---
 

Ownership entries refer to the entries created in the user profile due to owned objects.

Authorization entries refer to the entries created in the user profile due to objects to which this profile has been authorized.

Authorized user entries refer to the entries created in the user profile due to owned objects which have been authorized to other user profiles.

Primary group entries refer to the entries created in the user profile due to objects for which this profile is the primary group.

Number of used entries is the number of entries currently in the user profile for the specified type of entry.

Number of possible available entries is the number of entries which can possibly be added to the user profile.

The total storage utilization (in units of 1,024 bytes) field contains the sum of the system storage utilization (storage used on the system and basic ASPs) and all the independent ASP storage utilization of independent ASPs that are currently varied on.

The storage information field refers to the total storage a user profile is using and is authorized to use. This area can be formatted in small or large format, and is controlled by the input bit storage format in the materialization options of the materialization template. The output bit storage count format identifies the format of the storage information field.

The small format, as shown below, is used when the storage count format is binary zero.

Offset  
Dec Hex Field Name Data Type and Length
224
E0
Individual independent ASP information
(repeated once for each independent ASP, up to the number of independent ASPs supported (223))
[*] Char(16)
224 E0
  • Independent ASP storage authorization (small)
  • Bin(4)
228 E4
  • Independent ASP storage utilization (small)
  • Bin(4)
232 E8
  • Reserved (binary 0)
  • Char(2)
234 EA
  • Specification flags
  • Char(1)
234
EA
    • Independent ASP storage authorization setting
      0 =
      The value of independent ASP storage authorization (small) is a default value.
      1 =
      The value of independent ASP storage authorization (small) was set to a specific value .
    • Bit 0
234 EA
    • Reserved (binary 0)
    • Bits 1-7
235 EB
  • Status flags
  • Char(1)
235
EB
    • User profile extension existence flag
      0 =
      This independent ASP does not have a user profile extension for this user profile.
      1 =
      This independent ASP has a user profile extension for this user profile
    • Bit 0
235
EB
    • User profile extension damaged
      0 =
      The user profile extension is not damaged
      1 =
      The user profile extension is damaged
    • Bit 1
235 EB
    • Reserved (binary 0)
    • Bits 2-7
236 EC
  • Reserved (binary 0)
  • Char(4)
*
*
--- End ---
 

The large format, as shown below, is used when the storage count format is binary one.

Offset  
Dec Hex Field Name Data Type and Length
224 E0 System ASP information Char(16)
224 E0
  • Storage authorization (large)
  • Bin(8)
232 E8
  • Storage utilization (large)
  • Bin(8)
240
F0
Individual independent ASP information
(repeated once for each independent ASP, up to the number of independent ASPs supported (223))
[*] Char(24)
240 F0
  • Independent ASP storage authorization (large)
  • Bin(8)
248 F8
  • Independent ASP storage utilization (large)
  • Bin(8)
256 100
  • Reserved (binary 0)
  • Char(2)
258 102
  • Specification flags
  • Char(1)
258
102
    • Independent ASP storage authorization setting
      0 =
      The value of independent ASP storage authorization (large) is a default value.
      1 =
      The value of independent ASP storage authorization (large) was set to a specific value .
    • Bit 0
258 102
    • Reserved (binary 0)
    • Bits 1-7
259 103
  • Status flags
  • Char(1)
259
103
    • User profile extension existence flag
      0 =
      This independent ASP does not have a user profile extension for this user profile.
      1 =
      This independent ASP has a user profile extension for this user profile
    • Bit 0
259
103
    • User profile extension damaged
      0 =
      The user profile extension is not damaged
      1 =
      The user profile extension is damaged
    • Bit 1
259 103
    • Reserved (binary 0)
    • Bits 2-7
260 104
  • Reserved (binary 0)
  • Char(4)
*
*
--- End ---
 

System storage authorization (large) is the amount of auxiliary storage (in units of 1,024 bytes) that this user profile is authorized to use in the system ASP and basic ASPs. The combined storage of all objects this user profile owns in the system ASP and basic ASPs may not exceed this value. A value of 9,223,372,036,854,775,807 (hex 7FFFFFFFFFFFFFFF) indicates that this user profile has no limit on the amount of storage it may use (*NOMAX). This same convention also applies to the independent ASP storage authorization (large) field.

System storage utilization (large) is the current amount of auxiliary storage (in units of 1,024 bytes) allocated for the storage of objects owned by this user profile in the system ASP and basic ASPs. A value of 9,223,372,036,854,775,807 (hex 7FFFFFFFFFFFFFFF) indicates that the amount of auxiliary storage allocated is equal to or greater than 9,444,732,965,739,290,426,368 bytes.

The individual independent ASP information is an array of information for the individual independent ASPs. This array starts from the independent ASP 33 and increases sequentially to 255. As many entries as will fit in number of bytes provided will be returned up to a maximum of number of independent ASP entries. It is possible for a partial entry to be returned.

The independent ASP storage authorization field contains the maximum amount of independent auxiliary storage (in units of 1,024 bytes) that can be owned by this user profile. A value will always be returned in this field, even for an independent ASP that is varied off.

The independent ASP storage utilization field contains the current amount of independent auxiliary storage (in units of 1,024 bytes) allocated for the permanent objects owned by this user profile if the independent ASP is varied on. If the independent ASP is not varied on, 0 is returned.

The user profile extension existence flag field indicates whether or not the independent ASP has a user profile extension for this user profile. A user profile extension is stored on the independent ASP and contains information about the user profile.

If operand 2 is a system pointer, it identifies the input user profile object. If operand 2 is a space pointer, it provides addressability to the materialization template. The materialization template must be aligned on a 16-byte boundary. The format of the template is as follows:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Materialization template Char(64)
0 0
  • Template version
  • Char(1)
1 1
  • Reserved (binary 0)
  • Char(1)
2 2
  • Materialization options
  • Char(2)
2
2
    • Materialize for given Licensed Internal Code release
      0 =
      Materialize data applicable to the current release
      1 =
      Materialize data applicable to the specified release
    • Bit 0
2
2
    • Count format
      0 =
      Small counts used for counts of profile entries
      1 =
      Large counts used for counts of profile entries
    • Bit 1
2
2
    • Storage format
      0 =
      Small storage values used for storage used/limit
      1 =
      Large storage values used for storage used/limit
    • Bit 2
2 2
    • Reserved (binary 0)
    • Bits 3-15
4 4
  • Reserved (binary 0)
  • Char(10)
14 E
  • Target Licensed Internal Code release to materialize
  • Char(2)
14 E
    • Reserved (binary 0)
    • Bits 0-3
14 E
    • Version
    • Bits 4-7
14 E
    • Release
    • Bits 8-11
14 E
    • Modification level
    • Bits 12-15
16 10
  • User profile
  • System pointer
32 20
  • Reserved (binary 0)
  • Char(32)
64
40
--- End ---
 

The template version identifies the version of the materialization template. It must be set to hex 00.

The materialization options are options that control how the user profile data is presented in the receiver.

If the materialize for given Licensed Internal Code release bit is set to binary 1, then the operand 1 receiver will be filled in with values applicable to the Licensed Internal Code release specified by the target Licensed Internal Code release to materialize field. Fields that are not defined in the target release will be returned as hex zeroes.

The count format indicates whether the counts of profile entries are materialized in small or large format.

The storage format indicates whether the storage information is materialized in small or large format. While storage authorization (small) and storage utilization (small) will always be filled in, setting storage format to binary 1 will cause storage authorization (large) and storage utilization (large) to also be materialized. This is useful for when the values of authorized storage and/or utilized storage exceed that which can be represented in storage authorization (small) and storage utilization (small).

The target Licensed Internal Code release to materialize field is the target release specified when the materialize for given Licensed Internal Code release bit is set to binary 1. The earliest release that can be specified is Version 5, Release 1, Modification level 0. The latest release that can be specified is the current release. If an invalid release is specified, a template value invalid (hex 3801) exception is signaled.

The user profile system pointer is the user profile to be materialized.

Authorization Required

  • Operational
    • User profile identified by operand 2

Lock Enforcement

  • Materialize
    • User profile identified by operand 2

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
    • 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
  • 20 Machine Support
    • 2002 Machine Check
    • 2003 Function Check
  • 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