Materialize Activation Group Attributes (MATAGPAT)


Op Code (Hex) Operand 1 Operand 2 Operand 3
MATAGPAT 02D3 Receiver Activation group mark Attribute selection
Operand 1: Space pointer.

Operand 2 for MATAGPAT2: Char(8) scalar.

Operand 2 for MATAGPAT : Unsigned binary(4) scalar.

Operand 3: Character(1) scalar.

Bound program access
Built-in number for MATAGPAT2 is 661.
MATAGPAT2 (
           receiver                : address
           activation_group_mark   : address of unsigned binary(8)
           attribute_selection     : address
)
 
OR
 

Built-in number for MATAGPAT is 120.
MATAGPAT (
          receiver                : address
          activation_group_mark   : address of unsigned binary(4)
          attribute_selection     : 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.

Note: The terms "heap" and "heap space" in this instruction refer to an "activation group-based heap space".

Note

It is recommended that you use the MATAGPAT2 instruction which supports 8-byte activation and activation group marks. The 8-byte activation group mark in the basic activation group attributes should also be used. 4-byte marks can wrap and produce unexpected results.

Description

This instruction will materialize the information selected by operand 3 for the activation group specified by operand 2 and return the information in the template supplied by operand 1. If the activation group mark specified by operand 2 is zero, then information about the activation group associated with the current invocation is returned. However, if the current invocation is associated with an activation which resides in a shared activation group owned by another process, or if no activation exists for the current invocation, then information about the default activation group with the same state as the invocation is returned.

In order to deal with the variable-length nature of some activation group attributes, the attribute_selection option is provided. All of the "length-of-list" type information can be gathered by selecting the first option described below.

Operand 3 can have the following values:

Any value for operand 3 other than those listed will cause a scalar value invalid  (hex 3203) exception.

The materialization template identified by operand 1 must be 16-byte aligned in the space. This materialization template has the following format:

Offset
Dec Hex
Field Name
Data Type and Length
0 0
Materialization size specification
Char(8)
0 0
Number of bytes provided for materialization
Bin(4)
4 4
Number of bytes available for materialization
Bin(4)
8 8
Reserved (binary 0)
Char(8)
16 10
Returned information
Char(*)
* *
--- End ---

The number of bytes provided indicates the number of bytes provided for returned information by the user of the instruction. In all cases if the number of bytes provided is less than 8, then a materialization length invalid  (hex 3803) exception will be signaled.

The number of bytes available is set by the instruction to indicate the actual number of bytes available to be returned. In no case does the instruction return more bytes of information than those available.

The format of returned information is described in the following paragraphs.

Basic Activation Group Attributes

The following information is returned when operand 3 is hex 00.

Offset
Dec Hex
Field Name
Data Type and Length
16 10
Root program
System pointer or Null
32 20
Reserved (binary 0)
Char(16)






48 30
Storage address recycling key
System pointer or Null
64 40
Activation group name
Char(30)
94 5E
Reserved (binary 0)
Char(2)
96 60
Activation group mark
UBin(4)
100 64
Reserved (binary 0)
Char(4)
104 68
Heap space count
UBin(4)
108 6C
Activation count
UBin(4)
112 70
Static storage size
UBin(4)
116 74
Reserved (binary 0)
UBin(4)






120 78
Attributes
Char(1)
120 78
Reserved
Bit 0
120 78
Activation group state
Bit 1



0 = User
1 = System


120 78
Is activation group named?
Bit 2



0 = No
1 = Yes


120 78
Destroy pending?
Bit 3



0 = No
1 = Yes


120 78
Shared activation group?
Bit 4



0 = No
1 = Yes


120 78
Storage model
Bit 5



0 = Single level storage
1 = Teraspace storage


120 78
Reserved (binary 0)
Bits 6-7
121 79
Process access group (PAG) membership advisory attributes
Char(1)
121 79
Reserved (binary 0)
Bit 0






121 79
Static storage
Bit 1



0 = Do not create in PAG
1 = Permit creation in PAG


121 79
Default heap storage
Bit 2



0 = Do not create in PAG
1 = Permit creation in PAG


121 79
Reserved (binary 0)
Bits 3-7
122 7A
Reserved (binary 0)
Char(6)
128 80
Activation group mark
UBin(8)



For Non-Bound programs, the following datatype should be used:


128 80
Activation group mark (Non-Bound program)
Char(8)
136 88
--- End ---

Additional Description

Root program

Those activation groups which are created by the machine (the default activation groups) do not have root programs, in which case this field is null.

Storage address recycling key

A system pointer is returned only if the activation group state is specified as user, otherwise the field is null.

Activation group name

For activation groups which do not have a symbolic name, this field contains all blanks.

Heap space count

This is the number of heap spaces currently associated with the activation group.

Activation count

This is the number of programs which are currently active within the activation group.

Static storage size

This is the maximum amount of static storage, in machine dependent units, which has been allocated to the activation group at any particular time. Note that this does not necessarily reflect the amount of storage currently in use.

Is activation group named?

Indicates whether the activation group is named or unnamed. The activation group name field contains blanks for unnamed activation groups. The default activation groups and those created with the "unnamed" attribute are unnamed.

Storage model

Indicates the storage model of the activation group. A single level storage activation group provides single level storage static storage to program activations while a teraspace storage activation group supplies teraspace storage.

Activation Group Heap List

When operand 3 is hex 01, the format of the returned information is an array of heap identifiers. This is a list of the heaps which are currently associated with the activation group. The heap space count (available in the basic template) indicates how many entries must be accommodated by the template. The format of the list is:

Offset
Dec Hex
Field Name
Data Type and Length
16 10
Activation group heap list entry
[*] Bin(4)



(repeated heap space count times)


* *
--- End ---

Information about a specific heap may be obtained from the Materialize Activation Group-Based Heap Space Attributes (MATHSAT) instruction.

Program Activation List

When operand 3 is hex 02, the format of the returned information is an array of activation marks. Each activation mark represents a program activation within the activation group. (The activation mark is a number which uniquely identifies the activation within a process.) The activation count (available in the basic template) indicates how many entries must be accommodated by the template. The format of the list is different for the MATAGPAT and MATAGPAT2 instructions.

Format of program activation list for MATAGPAT2

Offset
Dec Hex
Field Name
Data Type and Length
16 10
Program activation list entry
[*] UBin(8)



(repeated activation count times)





For Non-Bound programs, the following datatype should be used:


16 10
Program activation list entry (Non-Bound program)
Char(8)
* *
--- End ---

Format of program activation list for MATAGPAT

Offset
Dec Hex
Field Name
Data Type and Length
16 10
Program activation list entry
[*] UBin(4)



(repeated activation count times)


* *
--- End ---

Information about a specific activation may be obtained from the Materialize Activation Attributes (MATACTAT) instruction.

Authorization Required

Lock Enforcement

Exceptions

06 Addressing

08 Argument/Parameter

10 Damage Encountered

1C Machine-Dependent

20 Machine Support

24 Pointer Specification

2C Program Execution

32 Scalar Specification

38 Template Specification

44 Protection Violation