Test User List Authority (TESTULA)


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5]
TESTULA 10E7
Available authority template receiver
System object
Test options template


TESTULAB 1CE7 Branch options Available authority template receiver System object Required authority template Branch targets


TESTULAI 18E7 Indicator options Available authority template receiver System object Required authority template Indicator targets
Operand 1: Space pointer or null.

Operand 2: System pointer.

Operand 3: Space pointer.

Operand 4-5:

Bound program access
Built-in number for TESTULA is 151.
TESTULA (
         available_authority_template_receiver   : address OR
                                                   null operand
         system_object                           : address of system pointer
         test_options_template                   : address
) :   signed binary(4) /* return_code */

The return code will be set as follows:

Return code

Meaning

1

Authorized.

0

Not Authorized.

This built-in function is used to provide support for the branch and indicator forms of the TESTULA instruction. The user must specify code to process the return code and perform the desired branching or indicator setting.

Description

This instruction verifies that the object authorities and/or ownership rights specified by operand 3 are available to the user list specified by operand 3 for the object specified by operand 2. The user list consists of a governing user profile and a list of group profiles for a thread. The profiles can be specified either by system pointers, or a uid for the user profile and a gid for the group profiles. Any program adopted user profiles for the current thread are not included in the authority verification process when this instruction is used.

If operand 1 is not null, all of the authorities and/or ownership specified by operand 3 that are currently available to the user list are returned in operand 1.

If the required authority is available, one of the following occurs:

If no branch options are specified, instruction execution proceeds to the next instruction.

The required authorities and/or ownership are specified by the required authority field of operand 3. This field includes a test option that indicates whether all of the specified authorities are required or whether any one or more of the specified authorities is sufficient. This option can be used, for example, to test for operational authority by coding a template value of hex 0F01 in operand 3. Using the any option does not affect what is returned in operand 1. If operand 1 is not null and the any option is specified, all of the authorities specified by operand 3 that are available to the user list are returned in operand 1.

If operand 1 is not null, it provides addressability to a template which contains a list of available authorization templates and 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
Bin(4)
4 4
Number of bytes available
Bin(4)
8 8
Number of authorization templates returned
Bin(2)
10 A
Reserved
Char(6)
16 10
Authorization templates
[*] Char(2)
16 10
Object control
Bit 0
16 10
Object management
Bit 1
16 10
Authorized pointer
Bit 2
16 10
Space authority
Bit 3
16 10
Retrieve
Bit 4
16 10
Insert
Bit 5
16 10
Delete
Bit 6
16 10
Update
Bit 7
16 10
Ownership (1 = yes)
Bit 8
16 10
Excluded
Bit 9
16 10
Authority list management
Bit 10
16 10
Execute
Bit 11
16 10
Alter
Bit 12
16 10
Reference
Bit 13
16 10
Reserved (binary 0)
Bits 14-15
* *
--- End ---

The first 4 bytes of the template identify the total number of bytes provided for use by the instruction. The 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 template 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.

The number of authorization templates returned field is how many authorization templates were returned in the space provided. This does not indicate the total possible that could be returned. A maximum of one authorization template will be returned.

Operand 2 identifies the object for which authority is to be tested. The program adopted and propagated user profiles for any invocations of the current thread will not be included in the authority verification process of the user list.

Operand 3 identifies the profiles to be used in the authority verification process. The profiles or users may be indicated either by uid/gid or by system pointer, but not both in one request. A user profile (system pointer or uid) must always be specified and the number of group profiles (or gids) may be zero or more, but not negative. If the number of group profiles (or gids) is negative or greater than 17, the template value invalid  (hex 3801) exception will be signaled. The format of the test options template (operand 3) is as follows:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Number of group profiles
Bin(2)
2 2
Required authority
Char(2)
4 4
User indicator
Char(1)



Hex 80 = Users are identified by system pointers
Hex 40 = Profiles are identified by uid/gid



5 5
Test flags
Char(1)
5 5
Ignore pointer authority
Bit 0
5 5
Reserved
Bits 1-7
6 6
Reserved (binary 0)
Char(10)
16 10
--- End ---

The ignore pointer authority bit indicates whether the authority stored in the operand 2 system pointer should be ignored when testing the user list's authority to the object.

Immediately following this information will be the identification of the user profile and the group profile list. The first entry always identifies the user to be the user profile followed by a list of the users in the group profile list. The number of users in the list is indicated by the number of group profiles field. The format of the identification is either in system pointers or in uid/gids as specified by the user indicator field.

If the option for system pointers is selected, the user identification will have the following format.

Offset
Dec Hex
Field Name
Data Type and Length
0 0
User profile
System pointer
16 10
--- End ---

Following the user profile pointer will be a list of system pointers for the group profiles. Each entry in the list will have the following format.
Offset
Dec Hex
Field Name
Data Type and Length
0 0
Group profile
System pointer
16 10
--- End ---

If the option for uid/gid is selected, the user identification will have the following format.

Offset
Dec Hex
Field Name
Data Type and Length
0 0
User profile (uid)
UBin(4)
4 4
--- End ---

Following the user profile (uid) will be a list of gids for the group profile list. Each entry in the list will have the following format.
Offset
Dec Hex
Field Name
Data Type and Length
0 0
Group profile (gid)
UBin(4)
4 4
--- End ---

The format for the required authority field (operand 3) is as follows: (1 = authorized)

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Authorization template
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)
Bit 14
0 0
Test option
Bit 15



0 = All of the above authorities must be present.
1 = Any one or more of the above authorities must be present.



2 2
--- End ---

This instruction will tolerate a damaged object referenced by operand 2 when the reference is a resolved pointer. The instruction will not tolerate damaged contexts or programs when resolving pointers. Damaged user profiles encountered during the authority verification processing result in the signaling of the authority verification terminated due to damaged object  (hex 1005) exception.

This instruction will not tolerate destroyed profiles or invalid system pointers/uid/gids to the users specified in operand 3. If system pointers are specified and any of them are null or do not point to a user profile, or if the uid or any of the gids are not in use or the user profile for it is destroyed, the authority verification terminated due to destroyed object  (hex 2207) exception will be signaled.

Resultant Conditions

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

0A Authorization

10 Damage Encountered

1A Lock State

1C Machine-Dependent

20 Machine Support

22 Object Access

24 Pointer Specification

2C Program Execution

2E Resource Control Limit

32 Scalar Specification

36 Space Management

38 Template Specification

44 Protection Violation