Test User List Authority (TESTULA)

Instruction Syntax

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:

  • Branch Form–Branch point, instruction pointer, relative instruction number, or absolute instruction number.
  • Indicator Form–Numeric variable scalar or character variable scalar.

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:

  • Branch form indicated
    • Conditional transfer of control to the instruction indicated by the appropriate branch target operand.
  • Indicator form specified
    • The leftmost byte of each of the indicator operands is assigned the following values:

      • Hex F1– If the result of the test matches the corresponding indicator option
      • Hex F0– If the result of the test does not match the corresponding indicator option
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

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

Char(1)
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

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

  • Bit 15

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

  • Authorized - the required authority is available.
  • Unauthorized - the required authority is not available.

Authorization Required

  • Execute
    • Contexts referenced for address resolution

Lock Enforcement

  • Materialize
    • Contexts referenced for address resolution

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
    • 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
    • 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
  • 2C Program Execution
    • 2C04 Branch Target Invalid
  • 2E Resource Control Limit
    • 2E01 User Profile Storage Limit Exceeded
  • 32 Scalar Specification
    • 3201 Scalar Type Invalid
    • 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
Parent topic: Authorization Management