Test Authority (TESTAU)


Op Code (Hex) Extender Operand 1 Operand 2 Operand 3 Operand [4-5]
TESTAU 10F7
Available authority template receiver System object or object template Required authority template


TESTAUB 1CF7 Branch options Available authority template receiver System object or object template Required authority template Branch targets


TESTAUI 18F7 Indicator options Available authority template receiver System object or object template Required authority template Indicator targets
Operand 1: Character(2) variable scalar or null.

Operand 2: System pointer or space pointer data object.

Operand 3: Character(2) scalar.

Operand 4-5:

Bound program access
Built-in number for TESTAU is 63.
TESTAU (
        available_authority_template_receiver   : address OR
                                                  null operand
        system_object_or_object_template        : address of system pointer OR
                                                  address of space pointer(16)
        required_authority_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 TESTAU 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 currently available to the thread for the object specified by operand 2.

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

If an object template is not specified (i.e. operand 2 is a system pointer), then authority verification is performed relative to the invocation executing this instruction. If an object template is specified (i.e. operand 2 is a space pointer), then authority verification is performed relative to the invocation specified in the template. Specifying an invocation causes the invocations subsequent to it to be bypassed in the authority verification process. This has the influence of excluding the program adopted user profiles for any of these excluded invocations from acting as a source of authority to the authority verification process.

The required authorities and/or ownership are specified by the required authority template of operand 3. This template 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 process 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. If operand 1 is null and neither the branch or indicator form is used, an invalid operand type  (hex 2A06) exception is signaled.

The format for the available authority template (operand 1) 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)
Bits 14-15
2 2
--- End ---

If operand 2 is a system pointer, it identifies the object for which authority is to be tested. If operand 2 is a space pointer, it provides addressability to the object template. The format for the optional object template is as follows:
Offset
Dec Hex
Field Name
Data Type and Length
0 0
Object template
Char(32)
0 0
Relative invocation
Bin(2)
2 2
Reserved (binary 0)
Char(14)
16 10
System object
System pointer
32 20
--- End ---

The relative invocation field in the object template identifies an invocation relative to the current invocation at which the authority verification is to be performed. The value of the relative invocation field must be less than or equal to zero. A value of zero identifies the current invocation, -1 identifies the prior invocation, -2, the invocation prior to that, and so on. A value larger than the number of invocations currently on the invocation stack or a positive value results in the signaling of the template value invalid  (hex 3801) exception. The program adopted and propagated user profiles for the identified invocation and older invocations will be included in the authority verification process. Program adopted user profiles for invocations newer than the identified invocation will not be included in the authority verification process. If the current invocation is specified, its program adopted user profile is included whether or not it is to be propagated.

The system object field specifies a system pointer which identifies the object for which authority is to be tested.

The format for the required authority template (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.

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