Resolve System Pointer (RSLVSP)

Op Code (Hex)	Operand 1	Operand 2	Operand 3	Operand 4
0164	Pointer for addressability to object	Resolve options	Context through which object is to be located	Authority to be set (1)

Operand 1: System pointer.

Operand 2: Character(34, 128) scalar or null.

Operand 3: System pointer or null.

Operand 4: Character(2) scalar or null.

Bound program access
Built-in number for RSLVSP is 30. RSLVSP ( pointer_for_addressability_to_object : address of system pointer resolve_options : address OR null operand context_through_which_object_is_to_be_located : address of system pointer OR null operand authority_to_be_set : address OR null operand )

Bound program access

Built-in number for RSLVSP is 30. RSLVSP ( pointer_for_addressability_to_object : address of system pointer resolve_options : address OR null operand context_through_which_object_is_to_be_located : address of system pointer OR null operand authority_to_be_set : address OR null operand )

Built-ins
_RSLVSP1 ( pointer_for_addressability_to_object : address of system pointer ) _RSLVSP2 ( pointer_for_addressability_to_object : address of system pointer resolve_options : address ) _RSLVSP3 ( pointer_for_addressability_to_object : address of system pointer context_through_which_object_is_to_be_located : address of system pointer ) _RSLVSP4 ( pointer_for_addressability_to_object : address of system pointer resolve_options : address context_through_which_object_is_to_be_located : address of system pointer ) _RSLVSP5 ( pointer_for_addressability_to_object : address of system pointer authority_to_be_set : address ) _RSLVSP6 ( pointer_for_addressability_to_object : address of system pointer resolve_options : address authority_to_be_set : address ) _RSLVSP7 ( pointer_for_addressability_to_object : address of system pointer context_through_which_object_is_to_be_located : address of system pointer OR authority_to_be_set : address ) _RSLVSP8 ( pointer_for_addressability_to_object : address of system pointer resolve_options : address context_through_which_object_is_to_be_located : address of system pointer OR authority_to_be_set : address )

Built-ins

_RSLVSP1 (
        pointer_for_addressability_to_object            : address of system pointer
)
 
 
_RSLVSP2 (
        pointer_for_addressability_to_object            : address of system pointer
        resolve_options                                 : address
 
)
 
_RSLVSP3 (
        pointer_for_addressability_to_object            : address of system pointer
        context_through_which_object_is_to_be_located   : address of system pointer 
)
 
_RSLVSP4 (
        pointer_for_addressability_to_object            : address of system pointer
        resolve_options                                 : address
        context_through_which_object_is_to_be_located   : address of system pointer 
 
)
 
_RSLVSP5 (
        pointer_for_addressability_to_object            : address of system pointer
        authority_to_be_set                             : address
 
)
 
_RSLVSP6 (
        pointer_for_addressability_to_object            : address of system pointer
        resolve_options                                 : address
        authority_to_be_set                             : address
 
)
 
_RSLVSP7 (
        pointer_for_addressability_to_object            : address of system pointer
        context_through_which_object_is_to_be_located   : address of system pointer OR
        authority_to_be_set                             : address
 
)
_RSLVSP8 (
        pointer_for_addressability_to_object            : address of system pointer
        resolve_options                                 : address
        context_through_which_object_is_to_be_located   : address of system pointer OR
        authority_to_be_set                             : address
 
)

Description

This instruction locates an object identified by a symbolic address and stores the object's addressability and authority (1) in a system pointer. A resolved system pointer is returned in operand 1 with addressability to a system object and the requested authority currently available to the thread for the object.

Note:

The ownership flag is never set in the system pointer.

Operand 2 specifies the symbolic identification of the object to be located. Operand 3 identifies the context to be searched in order to locate the object. Operand 4 identifies the authority states to be set in the pointer. First, the instruction locates an object based on operands 1, 2 and 3. Then, the instruction sets the appropriate authority states in the system pointer. If the object is not found, and do not signal object not found exception is set to binary 0, then an object not found (hex 2201) exception is signaled. If the object is not found, and do not signal object not found exception is set to binary 1, then the operand 1 pointer is set to a null pointer value and no exception is signaled.

The object to be located is either addressed through a machine context or a context object.

The following object types can only be addressed through the system ASP machine context (i.e. they cannot be addressed through an independent ASP machine context or a context object):

: Hex 08 = User profile
: Hex 10 = Logical unit description
: Hex 11 = Network description
: Hex 12 = Controller description
: Hex 14 = Class of service description
: Hex 15 = Mode description
: Hex 16 = Network interface description
: Hex 17 = Connection list
: Hex 1D = Auxiliary server

The following object types can only be addressed through the system ASP machine context or an independent ASP machine context (i.e. they cannot be addressed through a context object):

: Hex 04 = Context

Other object types are addressed through a context object, which may reside in the system ASP, basic ASP, or an ASP group.

No two context objects with the same name and subtype can exist within a given ASP group or within all basic ASPs and the system ASP (combined). Also, a context object in the system ASP or basic ASP cannot have the same name and subtype as a context in an ASP group. But context objects that are in different ASP groups may have the same name and subtype.

An ASP group is a set of independent ASPs that are configured such that they always vary on and off together.

The search for the object to be located proceeds as follows:

If an object is a type that can only reside in the system ASP machine context, then only that machine context is searched.
Otherwise, if the search method field in the extended template is used to limit the search to a context object (or machine context) in a specified independent ASP or ASP group, then only that context object (or machine context) is searched.
Otherwise, the name space of the current thread is searched. A name space is a list that identifies which machine contexts RSLVSP uses to search for a context object. The name space includes the system ASP and basic ASPs and may include one ASP group.
(Note that the search method field can be used to limit the search to just the ASP groups of the current thread's name space.)

When a name space is used to resolve to an object, the method used to search the name space depends on the type of object being resolved to:

If the object to be resolved is a context object, then each machine context in the name space is searched. If the context object is found, this instruction will resolve to the context. If the context object is not found, and do not signal object not found exception is set to binary 0, then an object not found (hex 2201) exception is signaled. If the object is not found, and do not signal object not found exception is set to binary 1, then the operand 1 pointer is set to a null pointer value and no exception is signaled.
If the object to be resolved can reside in a context object and a containing context is specified, then the search algorithm depends on whether or not the context object has an alias context. A containing context object is specified in operand 3 (see description of operand 3) or when operand 1 defines the name of a context object in an initial value declaration (see description of behavior when operand 2 is null).
An alias context is a context object on an independent ASP which is searched before searching the specified context in the system ASP or basic ASP. Note that only context objects in the system ASP or basic ASPs can have an alias context. The alias context will always be in the ASP group of the current thread's name space.
If the name space contains an ASP group and the ASP group has an alias context for the containing context object, then this instruction searches for the specified object in the alias context first. If the object is found, the instruction resolves to that object. If the object is not found (or if the context does not have an alias context) the instruction then searches the actual containing context that was specified. If the object is found there, the instruction resolves to that object. If the object is still not found, and do not signal object not found exception is set to binary 0, then an object not found (hex 2201) exception is signaled. If the object is still not found, and do not signal object not found exception is set to binary 1, then the operand 1 pointer is set to a null pointer value and no exception is signaled.
When a containing context is specified, the current thread must have authority to each context object that is searched (e.g. the specified context object and the alias context, if any); otherwise an unauthorized for operation (hex 0A01) exception is signaled. If an object is found in an alias context, the specified containing context in the system ASP or basic ASPs will not be searched and authority will only be verified for the alias context (not the specified containing context object itself.)
If the object to be resolved can reside in a context object and a containing context is not specified, the name resolution list is used to search for the object. The search starts with the first context object in the name resolution list. If the context object has an alias context, first the alias context is searched. Then the instruction searches the actual containing context that was specified.
If the object still has not been found, the next context object in the the name resolution list is searched in a similar manner. This continues until all context objects in the name resolution list have been searched (or until the object is found). If the object is not found, and do not signal object not found exception is set to binary 0, then an object not found (hex 2201) exception is signaled. If the object is not found, and do not signal object not found exception is set to binary 1, then the operand 1 pointer is set to a null pointer value and no exception is signaled.
For every context object in the name resolution list, the current thread must have authority to each context object that is searched (e.g. the specified context object and the alias for the context object, if any); otherwise an unauthorized for operation (hex 0A01) exception is signaled. For every context object in the name resolution list, if an object is found in an alias context, the specified containing context in the system ASP or basic ASPs will not be searched and authority will only be verified for the alias context (not the specified containing context object itself.)

As described above, objects are located in a machine context, in a specified containing context object, or using a name resolution list of context objects. Issues regarding name spaces are now described for these cases. If an object cannot reside in an independent ASP machine context or a context object, then name spaces do not apply.

Objects in a machine context (i.e. context objects)
When searching a name space for a context object, if the name space contains an ASP group and it is varied off, then that ASP group is bypassed and only the system ASP machine context is searched (for objects in the system ASP and basic ASPs).
Objects in a context
When searching a name space, if a containing context object is specified and that context object resides on an independent ASP that is varied off, an object not available (hex 220B) exception is signaled. If the containing context has an alias context and the alias context resides on an independent ASP that is varied off, then the alias context is bypassed and no exception is signaled.
Objects in context searched using name resolution list
If a name resolution list is used to find an object, if the context object referenced by the name resolution list entry is destroyed or it resides on an independent ASP that is varied off, that context name is bypassed and the search continues with the next context object in the name resolution list. If the context object referenced by the name resolution list entry has an alias context and the alias context resides on an independent ASP that is varied off, then the alias context is bypassed and no exception is signaled.

The following describes the instruction's function when operand 2 is null (or if the operand 2 template is extended and the field ignore object specification and authorization fields is set to 1). Note that operand 3 is always ignored in this case.

If operand 1 does not contain a system pointer, an exception is signaled.
If the system pointer specified by operand 1 is not resolved but has an initial value declaration, the instruction resolves the system pointer to the object that the initial value describes. The initial value defines the following:
- Object to be located (by type code, subtype code, and object name)
- Name of context to be searched to locate the object (optional)
- Minimum required authorization required for the object
If a context name is specified, then that context will be searched to locate the object. If no context is specified, the context object(s) located by the name resolution list associated with the thread issuing this instruction is used to locate the object. In both cases, the current thread's name space will be used (unless the search method field in the extended template is used to specify a different method).
If the minimum required authorization in the initial value is not set (binary 0), the instruction resolves the operand 1 system pointer to the first object encountered with the designated type code, subtype code, and object name without regard to the authorization available to the thread for the object. If one or more authorization (or ownership) states are required (signified by binary 1's), the context(s) is searched until an object is encountered with the designated type, subtype, and name for which the thread currently has all required authorization states.
If the system pointer specified by operand 1 is currently resolved to address an existing object, the instruction does not modify the addressability contained in the pointer and causes only the authority attribute in the pointer to be modified based on operand 4.

If operand 2 is not null, then the object identified by operand 2 is resolved. (But if the operand 2 template is extended and the field ignore object specification and authorization fields is set to binary 1, then the object identified by operand 2 is ignored. See the preceding section, starting with the phrase "The following describes the instruction's function when operand 2 is null...".) When the object identified by operand 2 is resolved, the instruction searches the context(s) specified by operand 3 and stores the resolved system pointer in operand 1.

The format of operand 2 is as follows:

Offset

Dec

Hex

Field Name

Data Type and Length

Object specification

Char(32)

Type code

Char(1)

Subtype code

Char(1)

Object name

Char(30)

Required authorization (1 = required)

Char(2)

Object control

Bit 0

Object management

Bit 1

Authorized pointer

Bit 2

Space authority

Bit 3

Retrieve

Bit 4

Insert

Bit 5

Delete

Bit 6

Update

Bit 7

Ownership

Bit 8

Excluded

Bit 9

Authority list management

Bit 10

Execute

Bit 11

Alter

Bit 12

Reference

Bit 13

Reserved (binary 0)

Bit 14

Extended template

Bit 15

0 =	The template is not extended
1 =	The template is extended

--- End ---

The allowed type codes are as follows:

: Hex 01 = Access group
: Hex 02 = Program
: Hex 03 = Module
: Hex 04 = Context
: Hex 06 = Byte string space
: Hex 07 = Journal space
: Hex 08 = User profile
: Hex 09 = Journal port
: Hex 0A = Queue
: Hex 0B = Data space
: Hex 0C = Data space index
: Hex 0D = Cursor
: Hex 0E = Index
: Hex 0F = Commit block
: Hex 10 = Logical unit description
: Hex 11 = Network description
: Hex 12 = Controller description
: Hex 13 = Dump space
: Hex 14 = Class of service description
: Hex 15 = Mode description
: Hex 16 = Network interface description
: Hex 17 = Connection list
: Hex 18 = Queue space
: Hex 19 = Space
: Hex 1A = Process control space
: Hex 1B = Authority list
: Hex 1C = Dictionary
: Hex 1D = Auxiliary server
: Hex 1E = Byte stream file
: Hex 21 = Composite object group
: Hex 23 = Transaction control structure

All other codes are reserved. If other codes are specified, they cause a scalar value invalid (hex 3203) exception to be signaled. This instruction will not resolve to hidden contexts. If an attempt is made to resolve to a hidden context, and do not signal object not found exception is set to binary 0, then an object not found (hex 2201) exception is signaled. If do not signal object not found exception is set to binary 1, then the operand 1 pointer is set to a null pointer value and no exception is signaled. A hidden context is denoted by the hidden attribute of a context. See the MATCTX instruction for additional details.

When resolving to an object that can reside in a context object, operand 3 identifies the context in which to locate the object identified by operand 2. If operand 3 is null, then the contexts identified in the name resolution list associated with the thread issuing this instruction are searched in the order in which they appear in the list. If operand 3 is not null, the system pointer specified must address a context, and only this context (and possible aliases for the context) are used to locate the object.

If the required authorization field in operand 2 is not set (all values set to 0), the instruction resolves the operand 1 system pointer to the first object encountered with the designated type code, subtype code, and object name without regard to the authorization currently available to the thread. If one or more authorization (or ownership) states are required (signified by binary 1's), the context is searched until an object is encountered with the designated type code, subtype code, object name, and the user profiles governing the thread's execution that have all the required authorization states.

If the bit extended template is set to binary 1, then the extended template is defined starting at offset 34 of the operand 2 template. The extended template is defined as follows:

Offset

Dec

Hex

Field Name

Data Type and Length

Template version

Char(1)

Search method

Char(1)

Hex 00 =	Search the thread's name space
Hex 01 =	Search only for objects residing on the specified independent ASP
Hex 02 =	Search only for objects residing on the ASP group containing the specified independent ASP
Hex 03 =	Search only the ASP group of the name space

Options

Char(1)

Ignore object specification and authorization fields

Bit 0

1 =	Ignore these values
0 =	Use these values

Do not signal object not found exception

Bit 1

0 =	Signal object not found (hex 2201) exception if the object is not found
1 =	Do not signal object not found (hex 2201) exception if the object is not found

Reserved (binary 0)

Bits 2-7

Reserved (binary 0)

Char(7)

Independent ASP number to search

Char(2)

ASP number of context containing resolved object

Char(2)

Context containing the resolved object

System pointer

Reserved (binary 0)

Char(64)

128

--- End ---

The field template version identifies the version of the extended template. It must be set to hex 00.

The field search method determines how the name space is searched:

A value of hex 00 means the thread's name space is searched, as described above (where the term "name space" is defined).
A value of hex 01 means that the the search is restricted to objects that reside on a specified independent ASP (or the system ASP and basic ASPs). The field independent ASP number to search determines which ASP. This option is applicable when searching a specified context object or when searching the name resolution list. When the object resides in an ASP group, this instruction will search context objects in all independent ASPs of the ASP group.
The field independent ASP number to search must specify an existing independent ASP. A value of 0 specifies the system ASP and basic ASPs. Values 33 through 255 specify an independent ASP. An ASP number between 1 and 32 or a number greater than 255 results in a template value invalid (hex 3801) exception being signaled. If the specified independent ASP is not varied on, then a object not available (hex 220B) exception is signaled.
A value of hex 02 means that the search is restricted to objects that reside on a single ASP group or the system ASP and basic ASPs. The field independent ASP number to search determines which one. A value of 0 specifies the system ASP and basic ASPs. Values 33 through 255 specify the ASP group or UDFS (User Defined File System) ASP containing that independent ASP. (Any independent ASP in an ASP group can be used to identify that ASP group.) This option is applicable when searching a specified context object or when searching the name resolution list. The rules for the field independent ASP number to search are the same as those given for search method hex 01.
A User Defined File System (UDFS) ASP is an IASP that is never part of an ASP group.
A value of hex 03 means the search is restricted to the ASP group of the name space (not the system ASP or basic ASPs).

As stated above, if a resolve is done for an object type that can only be addressed through the system ASP machine context then only the system machine context is searched. When resolving to objects that can only reside in the system ASP machine context, the field search method must be set to hex 00 (if the template is extended). Otherwise a template value invalid (hex 3801) exception is signaled.

For option hex 01 or hex 02, if a context address is provided in operand 3, then the context object must reside in the same ASP group as the specified independent ASP to search; otherwise an auxiliary storage pool number invalid (hex 1C09) exception is signaled.

For option hex 01 or hex 02, execute authority is required for the device description for every independent ASP in the ASP group (the ASP group that contains the independent ASP number to search). Authority to a device description is checked only when the corresponding independent ASP is searched. Once an object is found, the remaining independent ASPs do not have to be searched.

For option hex 03, if a context address is provided in operand 3, then it must reference a context object in an ASP group of the current thread's name space or in the system ASP or basic ASP; otherwise an auxiliary storage pool number invalid (hex 1C09) exception is signaled. If the context address refers to a context object in the system ASP or basic ASP, then only the alias contexts are searched.

When ignore object specification and authorization fields is set to binary 0, the object specification and required authorization will be used as defined above. If this field is set to binary 1, then the object specification and required authorization fields will be ignored, as if operand 2 were a null pointer.

When do not signal object not found exception is set to binary 0, an object not found (hex 2201) exception will be signaled if the object is not found. If this field is set to binary 1, then an object not found (hex 2201) exception will not be signaled if the object is not found, and the operand 1 pointer will be set to a null pointer value.

When an object is successfully resolved by this instruction, the field context containing the resolved object will contain a pointer to the context object in which the object was found. A null pointer value means the object was found in a machine context. The field ASP number of context containing resolved object indicates the ASP number on which the context containing the resolved object resides. This will be a basic ASP number or an independent ASP number. When ASP number of context containing resolved object is set to hex 00, it identifies the system ASP.

Once addressability has been set in the operand 1 pointer, operand 4 is used to determine which, if any, of the object authority states is to be set into the pointer. Only the object authority states correlating with bits 0 through 7 and 11, that is, object control through update and execute, can be set into the pointer. This restriction applies whether the authority mask controlling which authorities to set in the pointer comes from operand 4, operand 2, or the initial value for the system pointer.

If operand 4 is null, the object authority states required to locate the object are set in the operand 1 pointer. This required object authority is as specified in operand 2 or in the initial value for operand 1 if operand 2 is null (or if the operand 2 template is extended and the field ignore object specification and authorization fields is set to 1). If the thread does not currently have authorized pointer authority for the object, no authority is stored in the system pointer, and no exception is signaled.

If operand 2 is null (or if the operand 2 template is extended and the field ignore object specification and authorization fields is set to 1) and operand 4 is null and operand 1 is a resolved system pointer, the authority states in the pointer are not modified.

If operand 4 is not null, it specifies the object authority states to be set in the operand 1 system pointer. The format of operand 4 is as follows:

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Requested authorization (1 = set authority)		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		Reserved (binary 0)		Bits 8-10
0	0		Execute		Bit 11
0	0		Alter (will be ignored)		Bit 12
0	0		Reference (will be ignored)		Bit 13
0	0		Reserved (binary 0)		Bits 14-15
2	2	--- End ---

The authority states set in the operand 1 system pointer are based on the following:

The authority already stored in the pointer can be increased only when the thread has authorized pointer authority to the referenced object. If this authority is not available and the pointer was resolved by this instruction, the authority in the operand 1 system pointer is set to the not set state, and no exception is signaled. If operand 2 is null (or if the operand 2 template is extended and the field ignore object specification and authorization fields is set to 1), if operand 1 is a resolved system pointer containing authority, and if authorized pointer authority is not available to the thread, additional authorities cannot be stored in the pointer.
If the thread does not currently have all the authority states requested in operand 4, only the requested and available states are set in the pointer, and no exception is signaled.
A thread executing in user state may not set any additional authority in a system pointer. Operand 4 will be ignored if the thread executing this instruction is running in user state.
Note that the authority stored in the operand 1 system pointer is a source of authority applies to this instruction when operand 2 is null (or if the operand 2 template is extended and the field ignore object specification and authorization fields is set to 1) and operand 1 is a resolved system pointer with authority stored in it.

Authorization Required

Execute
- Contexts referenced for address resolution. This includes the operand 3 system pointer (when it is not a null system pointer) and system pointers obtained from the name resolution list. Authority is also checked for aliases of context objects. The authority supplied in the actual pointers is used when verifying authority for each context (referenced by the operand 3 or the name resolution list) and for any alias context.
- Device description for every independent ASP in a ASP group when a resolve is done for an object on a specified independent ASP or ASP group. See the description of the search method field for details.

Lock Enforcement

Materialization
- Contexts referenced for address resolution (including operand 3)

Exceptions

06 Addressing

0601 Space Addressing Violation
0602 Boundary Alignment
0603 Range

08 Argument/Parameter

0801 Parameter Reference Violation

0A Authorization

0A01 Unauthorized for Operation

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

1C09 Auxiliary Storage Pool Number Invalid

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
2404 Pointer Not Resolved

2E Resource Control Limit

2E01 User Profile Storage Limit Exceeded

32 Scalar Specification

3202 Scalar Attributes Invalid
3203 Scalar Value Invalid

36 Space Management

3601 Space Extension/Truncation

38 Template Specification

3801 Template Value Invalid

44 Protection Violation

4401 Object Domain or Hardware Storage Protection Violation
4402 Literal Values Cannot Be Changed

Footnotes:

(1) Programs executing in user-state may not assign authority in the resulting system pointer. The value in operand 4 is ignored and no exception is raised.