Materialize Invocation Attributes (MATINVAT)

Operand 2: Character(48) scalar or null.

Operand 3: Space pointer.

Built-in number for MATINVAT is 125.
MATINVAT (
          receiver                       : address
          invocation_identification      : address OR
                                           null operand
          attribute_selection_template   : address
)

Warning

The following information is subject to change from release to release. Use it with caution and be prepared to adjust for changes with each new release.

Description

The attributes specified by operand 3 of the invocation specified by operand 2 are materialized into the receiver specified by operand 1. In addition to specifying the attributes to be materialized, operand 3 controls how they are arranged in the operand 1 receiver.

Operand 1 is a space pointer to an area that is to receive the materialized attribute values. The format of this area is determined by the value of the attribute selection template.

Operand 2 identifies the source invocation whose attributes are to be materialized. It also identifies the originating invocation whose activation group access right to the source invocation's activation group is to be verified. If operand 2 is null, the invocation issuing the instruction is both the source invocation and the originating invocation.

Operand 3 is a space pointer to a template that selects the invocation attributes to be materialized and specifies how they are to be arranged in the receiver template.

Operand 2

The value specified by operand 2 identifies the source and originating invocations. This operand can be null (which indicates the current invocation is to be used for the source and originating invocations) or it can contain either a invocation pointer to an invocation or a null pointer (which indicates the current invocation).

Operand 2 has the following format:

Terminology

Field descriptions

Source invocation offset

A signed numerical value indicating an invocation relative to the invocation located by the source invocation pointer. A value of zero denotes the invocation addressed by the source invocation pointer, with increasingly positive numbers denoting increasingly later invocations in the stack, and increasingly negative numbers denoting increasingly earlier invocations in the stack.

If the source invocation pointer is not valid or the invocation identified by this offset does not exist in the stack, an invocation offset outside range of current stack  (hex 2C1A) exception will be signaled.

Originating invocation offset

A signed numerical value identifying the originating invocation relative to the current invocation. Since this is an offset relative to the current invocation, only zero or negative values are allowed.

If the invocation identified by this offset does not exist in the stack, an invocation offset outside range of current stack  (hex 2C1A) exception will be signaled.

Invocation range

This field is used by FNDRINVN and is ignored by this instruction.

Source invocation pointer

An invocation pointer to an invocation. If null, then the current invocation is indicated.

If the pointer identifies an invocation in another thread, a process object access invalid  (hex 2C11) exception will be signaled. If the invocation identified by this pointer does not exist in the stack, an object destroyed  (hex 2202) exception will be signaled.

Activation group access rights checking

This instruction sometimes (depending on the attributes materialized) requires that activation group access rights to the activation group of the source invocation be verified. In such cases, the originator offset field of operand 2 identifies the invocation whose right of access is to be checked. (That is, it identifies the invocation which is considered to have originated the request and on whose behalf the instruction is being executed.)

If originator offset is not zero, then the activation group of the requesting invocation must have the right to access the activation group of the invocation identified by originator offset. This check is made whether or not access rights to the source invocation need to be checked.

In the event that appropriate access rights are not found, an activation group access violation  (hex 2C12) exception is signaled.

Operand 3

The attribute selection template has the following format:

The attribute selection entries are each 16 bytes long and have the following format:

Basic structure

The attribute selection template allows the user of MATINVAT considerable flexibility in deciding what invocation attributes are to be materialized and where their materializations are to be returned. This flexibility is achieved by having the attribute selection template consist of a header, followed by a series of entries, each of which identifies an attribute to be materialized, the location where it is to be materialized, and the amount of space reserved for its materialization.

The template header specifies the number of attribute entries present in the template, and it also allows the specification of an optional attribute index field. The attribute index field, if present, identifies the first attribute selection entry to be processed (causing entries prior to that one to be skipped). In addition, if the attribute index field is present, it is updated upon the normal or abnormal completion of the instruction to contain either zero (if completion is normal) or the number of the entries being processed (if the instruction ends with an exception).

Each attribute selection entry identifies the attribute to be materialized and the area where the materialization is to be returned. The attribute may be returned directly into the area addressed by the operand 1 space pointer, or it may be returned into an area addressed by a space pointer which is, in turn, contained in the area addressed by the operand 1 space pointer. These two cases are distinguished by the indirect bit.

In addition, each attribute selection entry contains:

• An offset value which is the offset relative to the operand 1 space pointer where either the attribute's materialization area or the pointer to the attributes' materialization area is contained.

• A length value identifying the maximum number of bytes of data to be materialized for the attribute.

• A flag indicating whether the length of the attribute is to be materialized.

• A flag indicating whether the status of the attribute is to be materialized.

• A flag indicating whether a pad field precedes the attribute (or its pointer, if indirect is specified). If present, the length of this "pad" field is automatically adjusted so that the combined length of the length, status, and pad fields is either zero or 16, maintaining the relative quadword alignment of the modification value if the length and/or status fields are present.

Note that, for the sake of regularity, the fields of the attribute selection template header are arranged in the same general fashion as those in the attribute selection entries.

Field descriptions

Number of attributes

Specifies how many 16-byte attribute selection entries follow.

Attribute index indirect

If attribute index indirect is binary 0, then offset to attribute index specifies the location where the attribute index is stored as an offset from the location addressed by the operand 1 space pointer. If attribute index indirect is binary 1, then the location identified by attribute index offset must be quadword aligned and must contain a space pointer. This space pointer in turn addresses the location where the attribute index value is stored.

Offset to attribute index

Specifies the offset to the attribute index or the offset to a pointer to the attribute index, depending on the value of attribute index indirect.

Length of attribute index

Specifies the length of the area where the attribute index value is stored. This field must have a value of either zero or four.

If this field has a value of zero, then the first attribute entry to be processed is the first attribute entry in the template, and no feedback is given as to which attribute entry was being processed at the time of an exception. Attribute index indirect and attribute index offset are ignored.

If this field has a value of four, then the value of the attribute index, treated as a signed bin(4) value, must be greater than or equal to one and less than or equal to number of attributes. In this case the attribute index identifies the attribute entry to be processed first (with the first entry in the template having an index of one), and, in the event of an exception, the attribute index value is modified by this instruction such that it identifies the attribute entry being processed at the time of the exception. If the instruction completes without an exception, then the attribute index value is set to zero.

Attribute ID

Specifies the attribute to be materialized. Values that may be specified are:

1	Invocation pointer to specified invocation. (16 bytes, quadword aligned.)
2	Automatic storage pointer. Space pointer to the automatic storage for this invocation. If no automatic storage exists for this invocation, then a null pointer is returned. (16 bytes, quadword aligned, access rights required.)
3	Static storage pointer. Space pointer to the static storage for a non-bound program invocation, if any exists. Otherwise, a null pointer value is returned. (16 bytes, quadword aligned, access rights required.) Note: For bound program procedure invocations there is no single "distinguished" static storage area, but instead there may be multiple static storage areas. The list of static storage areas corresponding to the invocation's activation can be obtained by using the Materialize Activation Attributes (MATACTAT) instruction.
4	Parameter list pointer. Space pointer to the parameter list passed to this invocation (bound program procedure invocations only). If the procedure for this invocation does not have a parameter list, or if this invocation is for a program entry procedure or a non-bound program, then a null pointer value is returned. (16 bytes, quadword aligned, access rights required.)
6	Program pointer. System pointer to the program for this invocation. If the program no longer exists then a null pointer is returned. (16 bytes, quadword aligned, access rights required.)
7	Space pointer to module associated space. For bound program procedures, this space pointer addresses the secondary associated space in the bound program that was propagated from the primary associated space of the bound program module. For non-bound programs, this space pointer addresses the program's primary associated space. If the appropriate associated space does not exist in the program or if the program no longer exists, then a null pointer is returned. For both bound and non-bound program invocations the requesting invocation must have space authority to the program. (16 bytes, quadword aligned, access rights required.)
8	Pointer to containing scope. If the specified invocation is in a nested scope, then this is an invocation pointer to the invocation of the containing scope. Otherwise a null pointer is returned. (16 bytes, quadword aligned.)
9	Relative invocation offset to containing scope. If the specified invocation is in a nested scope, then this is the relative invocation offset to the invocation of the containing scope. Otherwise, a value of zero is returned. Note that the relative invocation offset will be a negative number and is relative to the specified invocation. (4 bytes.)
10	Lexical level number. Outer procedures have a lexical level number of 1. (4 bytes.)
11	Invocation number. (2 bytes.)
12	Invocation mark. (4 bytes.)
13	Activation mark. If no activation exists for this invocation, then a zero value is returned. (4 bytes.)
14	Activation group mark. (4 bytes.) If the activation resides in a shared activation group owned by another process, or if no activation exists for the invocation, then the value returned is as follows: 1 if this is a system state invocation 2 if this is a user state invocation
15	Invocation type. The possible values for invocation type are: Hex 01 = Call external Hex 02 = Transfer control Hex 03 = Event handler Hex 04 = External exception handler (for non-bound program) Hex 05 = Initial program in process problem state Hex 06 = Initial program in process initiation state Hex 07 = Initial program in process termination state Hex 08 = Invocation exit (for non-bound program) Hex 09 = Return or return/XCTL trap handler Hex 0A = Call program Hex 0B = Cancel handler (bound program only) Hex 0C = Exception handler (bound program only) Hex 0D = Call bound procedure/call with procedure pointer Hex 0E = Process Default Exception Handler (1 byte.)
16	Routine type. The possible values for routine type are: Hex 01 = Non-Bound Program Hex 02 = Bound Program Entry Procedure (PEP) Hex 03 = Bound Program Procedure Note: Bound program procedures are contained within bound programs, bound service programs, and Java™ programs. All discussion of bound program procedure semantics also apply to Java program procedures. (1 byte.)
17	State invocation was invoked with. (2 bytes.) Hex 8000 = System state Hex 0001 = User state
18	State for invocation. (2 bytes.) Hex 8000 = System state Hex 0001 = User state
19	Invocation status of the specified invocation (including invocation flags). Bit 0 Cancelled Bit 1 Ending -- a return operation has been initiated from within the invocation or the actual termination of a cancelled invocation has begun. Bit 2 Invocation interrupted by exception Bit 3 Invocation interrupted by event (reserved) Bit 4 Invocation is a non-bound program CALLX exception handler Bit 5 Invocation contains a non-bound program CALLI exception handler Bit 6 Invocation contains a signalled non-bound program branchpoint handler Bit 7 Retry not allowed Bit 8 Resume not allowed Bit 9 Resume point has been modified Bit 10 Invocation is a program entry procedure and is marked as the oldest in the activation group (This is also known as a hard control boundary.) Bit 11 Invocation is a soft control boundary. Bit 12 Invocation created an unnamed activation group. Bits 13-15 Reserved Bits 16-31 Invocation flags (4 bytes.) Performance consideration: When the only invocation status information required is the invocation flags, there may be a significant performance advantage if the following attribute is materialized instead of this one.
20	Invocation flags of the specified invocation. This attribute has the same format as the invocation status attribute, except that the first two bytes are returned as zero. (4 bytes.)
23	Cancel reason of the specified invocation. (4 bytes.)
24	Suspend point. Suspend pointer identifying the location within the invocation's routine where execution was suspended due to a call, interrupt, or machine operation. If the program no longer exists then a null pointer is returned. (16 bytes, quadword aligned, access rights required.)
25	Resume point. A suspend pointer identifying the location within the invocation's routine where execution will resume if execution is allowed to resume in the invocation. If the invocation is suspended for some cause that permits resumption, then this is initially set to the location that logically follows the suspend point. If the invocation is suspended for some cause that does not permit resumption, then this is initially set to be a null pointer. If the resume point is modified via Modify Invocation Attributes then a suspend pointer (or null pointer) corresponding to the modified resume point is returned. If the program no longer exists or if the invocation is cancelled or ending, then a null pointer is returned. (16 bytes, access rights required, quadword aligned.)
26	Interrupt message invocation. If the invocation is interrupted due to an exception interrupt, and the message causing the interrupt has not been removed or modified to a non-interrupt state, then this is an invocation pointer which addresses the invocation to which the interrupt message is enqueued. If no interrupt cause currently exists, then a null pointer is returned. (16 bytes, quadword aligned.)
27	Interrupt message reference key. If the invocation is interrupted due to an exception interrupt, and the message causing the interrupt has not been removed or modified to a non-interrupt state, then this is the message reference key of the interrupt cause message. If no interrupt cause currently exists, then a value of zero is returned. (4 bytes.)
28	External exception handler's monitoring invocation. If the specified invocation is an external exception handler for a non-bound program, then this is an invocation pointer identifying the invocation which enabled the handler (also the invocation where the exception message is currently enqueued). Otherwise, a null pointer is returned. (16 bytes, quadword aligned.)
29	External exception handler's message reference key. If the specified invocation is an external exception handler for a non-bound program, then this is the message reference key of the corresponding exception message. Otherwise, a zero value is returned. (4 bytes.)
30	Non-bound program internal exception handler's message reference key. If the specified invocation is a non-bound program invocation with an internal exception handler active, then this is the message reference key of the exception message corresponding to the currently active internal exception handler. Otherwise, a zero value is returned. (4 bytes.)
31	Non-bound program branchpoint exception handler's message reference key. If the specified invocation is a non-bound program invocation with a branchpoint exception handler in a signalled state, then this is the message reference key of the exception message corresponding to the most recently signalled branchpoint exception exception handler. Otherwise, a zero value is returned. (4 bytes.)
32	Trap handler's message reference key. If the specified invocation was invoked as a trap handler, then this is the message reference key of the corresponding trap message. (Note that the trapped invocation is, by definition, the immediately preceding invocation.) Otherwise, a zero value is returned. (4 bytes.)
33	Invocation mark. (8 bytes.)
34	Activation mark. If no activation exists for this invocation, then a zero value is returned. (8 bytes.)
35	Activation group mark. (8 bytes.) If the activation resides in a shared activation group owned by another process, or if no activation exists for the invocation, then the value returned is as follows: 1 if this is a system state invocation 2 if this is a user state invocation

Where "access rights required" is specified above, the activation group of the invocation identified as the originating invocation must have activation group access rights to the activation group of the source invocation or else an activation group access violation  (hex 2C12) exception is signaled.

The invocation with an invocation number of 1 is always the first invocation in the stack.

Indirect

If indirect is binary 0, then offset to receiver specifies the location where the selected attribute value is to be materialized as as offset from the location addressed by operand 1. If indirect is binary 1, then the location identified by offset to receiver, after accounting for any length, status, or pad fields specified, must be quadword aligned and must contain a space pointer. This space pointer in turn addresses the location where the selected attribute value is to be materialized.

Return length

If return length and return status are both binary 0, then only the attribute itself is materialized. If return length is binary 1, then the attribute (or attribute pointer, if indirect is true) is preceded by a four-byte value which specifies the length of the attribute (exclusive of the length value itself, and the status and pad fields, if present).

Return status

If return status is binary 1, then the attribute (or attribute pointer, if indirect is true) is preceded by a four-byte value which contains the status of the attribute.

If the status value is returned, it has the following format:

Bits 0-2	Reserved (binary 0)
Bit 3	Attribute unavailable at this time. (Eg, asking for the system pointer to a destroyed non-bound program.) The result returned is zeros for the minimum length defined.
Bit 4	Attribute not defined in this context. (Eg, asking for lexical level number from non-bound program invocation.) The result returned is zeros for the minimum length defined.
Bit 5	Attribute not defined at this time. (Eg, asking for interrupt message invocation when the invocation is not interrupted.) The result returned is zeros for the minimum length defined.
Bit 6	Attribute defined but null. (Eg, when asking for the resume point for an invocation for which resume is not currently allowed.) The result returned is zeros for the minimum length defined.
Bit 7	Attribute truncated. Indicates that the specified length of receiver was too small to allow the entire attribute to be returned. The truncated result is returned, as described earlier.
Bits 8-31	Reserved (binary 0)

If return length and return status are both binary 1 then the length field comes first, followed immediately by the status field.

Pad

If either return length or return status is binary 1, and pad is also binary 1, then twelve bytes of pad are assumed between the length or status value and the attribute (or attribute pointer, if indirect is true). If both return length and return status are binary 1, and pad is also binary 1, then eight bytes of pad are assumed between the status value and the attribute (or attribute pointer). If return length and return status are both binary 0, then no padding occurs, regardless of the value of pad. The area occupied by the pad is not modified by this instruction.

Note: Pad makes it easier to quadword align the area to receive the materialized attribute (if indirect is false) or the area containing the attribute pointer (if indirect is true) when return status and/or return length are also specified.

Offset to receiver

Specifies the offset to the location where the selected attribute value is to be materialized, or the offset to a pointer to the location, depending on the value of indirect.

Length of receiver

Specifies the length of the area where the attribute value is to be materialized.

This length indicates the length of the actual area available for materializing the attribute, and does not include the length of any length, status, or pad field. If the number of bytes of attribute data available to be materialized (exclusive of the status, length, and pad fields, if any) exceeds length of receiver, then only length of receiver bytes of data are returned. No exception is signalled in this case.

If indirect is a binary 0, then length of receiver indicates the length of the area located by offset to receiver. If indirect is a binary 1, then length of receiver indicates the length of the area located by the indirect space pointer identified by offset to receiver.

In the case that length of receiver is sufficient to receive only part of a field in an attribute structure, then the partial field may or may not be materialized.

Individual attribute entries are processed in order, with the attributes specified by each entry being materialized before processing of the next entry begins. If an exception occurs while processing an attribute entry, then the attributes materialized due to the preceding attribute entries will still be present in their specified result locations.

For attributes which include pointers, the specified direct or indirect value location, after accounting for any length, status, or pad fields, must be quadword aligned or a boundary alignment  (hex 0602) exception may occur. (The exception is not guaranteed to occur, eg, in the case where length of receiver is insufficient to include the materialized pointer, or when a null pointer is returned.)

If the value locations of individual attribute entries overlap, then the values will be overlaid in the sequence implied by the attribute entry order. If the value location of a non-indirect result overlays the location of the space pointer for an indirect result, then the validity of the space pointer will depend on the order of the associated entries.

Authorization Required

• Activation group access

  • From the activation group of the invocation issuing the instruction to the activation group of the originating invocation identified by operand 2

  • When an attribute annotated with "access rights required" is specified: From the activation group of the originating invocation identified by operand 2 to the activation group of the source invocation identified by operand 2

• Space authority

  • For the module associated space option, the requesting invocation must have space authority to the program executing in the source invocation identified by operand 2

Lock Enforcement

• None

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

• 1004 System Object Damage State
• 1044 Partial System Object Damage

1C Machine-Dependent

• 1C03 Machine Storage Limit Exceeded

20 Machine Support

• 2002 Machine Check
• 2003 Function Check

22 Object Access

• 2202 Object Destroyed
• 2203 Object Suspended
• 2208 Object Compressed
• 220B Object Not Available

24 Pointer Specification

• 2401 Pointer Does Not Exist
• 2402 Pointer Type Invalid

2C Program Execution

• 2C11 Process Object Access Invalid
• 2C12 Activation Group Access Violation
• 2C19 Invalid Origin Invocation
• 2C1A Invocation Offset Outside Range of Current Stack

2E Resource Control Limit

• 2E01 User Profile Storage Limit Exceeded

32 Scalar Specification

• 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