Materialize User Profile Pointers from ID (MATUPID)

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

Materialization format option

Char(1)

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

Materialization type option

Char(1)

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

Number of uids provided

UBin(4)

Number of gids provided

UBin(4)

Reserved (binary 0)

Char(10)

--- 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		Char(1)
		Hex 01 = uid Hex 02 = gid
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