Materialize User Profile Pointers from ID (MATUPID)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2
013A Return template Input template
Operand 1: Space pointer.

Operand 2: Space pointer.

Bound Program Access 
Built-in number for MATUPID is 382.
MATUPID (
         return_template   : address
         input_template    : address
)

Description:

This instruction converts the uids and/or gids specified by the input template in operand 2 to system pointers for the corresponding user profiles returned in operand 1. The materialization options determine the format of the profile information returned in operand 1.

The operand 2 template must be on a 4-byte boundary. The format of the input template is:

Offset  
Dec Hex Field Name Data Type and Length

0

0

Materialization format option

Hex 01 =
Materialize short template
Hex 02 =
Materialize long template

Char(1)

1

1

Materialization type option

Hex 00 =
List provided
Hex 41 =
Return all gids starting with the specified gid
Hex 80 =
Return all uids then all gids
Hex 81 =
Return all uids then gids starting with the specified uid

Char(1)
2 2 Number of uids provided UBin(4)
6 6 Number of gids provided UBin(4)
10 A Reserved (binary 0) Char(10)

20

14

--- End ---

 

The materialization format option field identifies the format of the materialization to be returned in the return template specified by operand 1.

The materialization type option field identifies the type of materialization operation to be performed. When one of the following is not specified, a template value invalid (hex 3801) exception is signalled.

  • List provided - a list of uids and/or gids is provided (number of entries is indicated by number of uids provided and number of gids provided). An entry for each uid and gid in the list will be materialized into operand 1.
  • Return all uids then gids - return all uids, then gids starting with the first uid. Only as many uids and gids will be returned as will fit in the space provided for operand 1.
  • Return all uids then gids starting with the specified uid - return all uids/gids beginning with the uid specified. An entry for each uid and gid starting with the uid specified will be materialized into operand 1. If the specified uid is not found, then the next entry found in the table will be returned as the first entry in the materialization template. The next entry found will either be the next uid in numerical order, or the first gid.
  • Return all gids starting with the specified gid - return all gids beginning with the gid specified. An entry for each gid starting with the gid specified will be materialized into operand 1. If the specified gid is not found, then the next entry found in the table will be returned as the first entry in the materialization template. The next entry found will be the next gid in numerical order. To get a list of all gids start with a gid of 1 (hex 00000001).
    Note: Starting with a specified uid/gid does not guarantee that the list has not changed. When trying to get all uids/gids and a continuation is required, any ID's added between calls that are less than the uid/gid specified as the resume will not be returned.

The number of uids provided field is the number of uids in the list of uids that follows the reserved area. This may be zero (no uids) or a positive number. This field is used for materialization type option hex 00; otherwise ignored.

The number of gids provided field is the number of gids in the list of gids that follows any uids provided after the reserved area. This may be zero (no gids) or a positive number. This field is used for materialization type option hex 00; otherwise ignored.

This information will be followed by a list of uids specified. If materialization type option hex 81 is selected, one uid will be in the list. Each uid has the following format.

Offset  
Dec Hex Field Name Data Type and Length
0 0 Uid UBin(4)

4

4

--- End ---

 

Following the uids will be a list of gids specified. If materialization type option hex 41 is selected, one gid will be in the list. Each gid has the following format.

Offset  
Dec Hex Field Name Data Type and Length
0 0 Gid UBin(4)

4

4

--- End ---

 

The receiver identified by operand 1 must be 16-byte aligned in the space. The format of the materialization 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 Number of uids returned UBin(4)
12 C Number of gids returned UBin(4)
16 10 Indicators Char(1)
16 10
  • Pointer(s) not set
  • Bit 0
16 10
  • Reserved
  • Bits 1-7
17 11 Reserved Char(15)

32

20

--- End ---

 

The number of bytes provided for materialization identify the total number of bytes that may be used 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 number of bytes available for 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 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.

The number of uids returned field contains the total number of uids materialized.

The number of gids returned field contains the total number of gids materialized.

Pointer(s) not set. When this field is binary 1, one or more user profile instances in the uid and/or gid list is binary 0s because a uid or gid in the list provided is not in use or the user profile associated with the uid/gid is destroyed.

This information will be followed by an entry for each uid in the list in operand 2 followed by an entry for each gid in the list in operand 2.

For the short format, each entry (for uids and gids) in the list will have the following format:

Offset  
Dec Hex Field Name Data Type and Length
0 0 User profile System pointer

16

10

--- End ---

 

For the long format, each entry (for uids and gids) in the list will have the following format:

Offset  
Dec Hex Field Name Data Type and Length
0 0 User profile type code Char(1)
1 1 User profile subtype code Char(1)
2 2 User profile name Char(30)
32 20 Uid/gid UBin(4)

36

24

ID type

Hex 01 =
uid
Hex 02 =
gid

Char(1)
37 25 Flags Char(1)
37 25
  • User profile pointer is not set
  • Bit 0
37 25
  • Reserved
  • Bits 1-7
38 26 Reserved Char(10)
48 30 User profile System pointer

64

40

--- End ---

 

User profile pointer is not set. When this field is binary 1, the uid or gid specified is not in use or the user profile is destroyed. User profile will be set to binary 0s.

Authorization Required

  • None

Lock Enforcement

  • None

Exceptions

  • 06 Addressing
    • 0601 Space Addressing Violation
    • 0602 Boundary Alignment
    • 0603 Range
  • 08 Argument/Parameter
    • 0801 Parameter Reference Violation
  • 0A Authorization
    • 0A0A ID Index Not Available
  • 10 Damage Encountered
    • 1002 Machine Context Damage State
    • 1005 Authority Verification Terminated Due to Damaged Object
  • 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
Parent topic: Authorization Management