Resolve System Pointer (RSLVSP)

Instruction Syntax

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
)
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 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
0 0 Object specification Char(32)
0 0
  • Type code
  • Char(1)
1 1
  • Subtype code
  • Char(1)
2 2
  • Object name
  • Char(30)
32 20 Required authorization (1 = required) Char(2)
32 20
  • Object control
  • Bit 0
32 20
  • Object management
  • Bit 1
32 20
  • Authorized pointer
  • Bit 2
32 20
  • Space authority
  • Bit 3
32 20
  • Retrieve
  • Bit 4
32 20
  • Insert
  • Bit 5
32 20
  • Delete
  • Bit 6
32 20
  • Update
  • Bit 7
32 20
  • Ownership
  • Bit 8
32 20
  • Excluded
  • Bit 9
32 20
  • Authority list management
  • Bit 10
32 20
  • Execute
  • Bit 11
32 20
  • Alter
  • Bit 12
32 20
  • Reference
  • Bit 13
32 20
  • Reserved (binary 0)
  • Bit 14
32
20
  • Extended template
    0 =
    The template is not extended
    1 =
    The template is extended

  • Bit 15
34
22
--- 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
34 22 Template version Char(1)
35
23
Search method
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
Char(1)
36 24 Options Char(1)
36
24
  • Ignore object specification and authorization fields
    1 =
    Ignore these values
    0 =
    Use these values

  • Bit 0
36
24
  • Do not signal object not found exception
    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

  • Bit 1
36 24
  • Reserved (binary 0)
  • Bits 2-7
37 25 Reserved (binary 0) Char(7)
44 2C Independent ASP number to search Char(2)
46 2E ASP number of context containing resolved object Char(2)
48 30 Context containing the resolved object System pointer
64 40 Reserved (binary 0) Char(64)
128
80
--- 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.