Materialize Context (MATCTX)

Instruction Syntax

Operand 1: Space pointer.

Operand 2: System pointer or null.

Operand 3: Character scalar.

Built-in number for MATCTX is 57.
MATCTX (
        receiver                  : address
        context                   : address of system pointer OR
                                    null operand
        materialization_options   : address
)

Description:

Based on the contents of the materialization options specified by operand 3, the symbolic identification and/or system pointers to all, or a selected set, of the objects addressed by the context specified by operand 2 are materialized into the receiver specified by operand 1.

If operand 2 is a null operand and the machine context selection field is zero, then the machine context for the system ASP is materialized. If operand 2 is a null operand and the machine context selection field is one, then the independent ASP machine context for the independent ASP number specified is materialized.

Usage Notes

To get a list of every context on a system, first use the MATRMD instruction to retrieve a list of every independent ASP (and the system ASP) on the system, using selection option hex 1F. For every independent ASP in the list, the field independent ASP will be set to binary 1. For each independent ASP (and the system ASP), the ASP number will be materialized. Each of the machine contexts can then be materialized using the MATCTX instruction. For each call to this instruction, the independent ASP number should be set to one of the ASP number values materialized from MATRMD. The machine context selection field should be set to binary 1, the object ID selection field should be set to hex 1, and the type code should be set to hex 04.

The materialization options operand has the following format:

Offset
Dec	Hex	Field Name	Data Type and Length
0	0	Materialization control	Char(2)
0	0	Information requirements (1 = materialize)	Char(1)
0	0	Extended template 0 = The extended template is not defined 1 = The extended template is defined	Bit 0
0	0	Reserved (binary 0)	Bits 1-2
0	0	Concurrency mode	Bit 3
0	0	Extended context attributes	Bit 4
0	0	Validation 0 = Validate system pointers 1 = No validation	Bit 5
0	0	System pointers	Bit 6
0	0	Symbolic identification	Bit 7
1	1	Selection criteria	Char(1)
1	1	Reserved (binary 0)	Bit 0
1	1	Materialize hidden contexts 0 = Do not materialize hidden contexts within the operand 2 context 1 = Materialize all contexts including hidden contexts within the operand 2 context	Bit 1
1	1	Machine context selection 0 = Materialize the system machine context. 1 = Materialize the independent ASP machine context specified by the independent ASP number field.	Bit 2
1	1	Modification date/time selection 0 = Do not select by modification date/time 1 = Select by modification date/time	Bit 3
1	1	Object ID selection Hex 0 = All entries Hex 1 = Type code selection Hex 2 = Type code/subtype code selection Hex 4 = Name selection Hex 5 = Type code/name selection Hex 6 = Type code/subtype code/name selection Hex E = Context entries collating at and above the specified type code/subtype code/name selection	Bits 4-7
2	2	Length of name to be used for search argument	Bin(2)
4	4	Type code	Char(1)
5	5	Subtype code	Char(1)
6	6	Name	Char(30)
36	24	Timestamp	Char(8)
44	2C	Independent ASP number	Char(2)
46	2E	--- End ---

46

The materialization control information requirements field in the materialization options operand specifies the information to be materialized for each selected entry. Symbolic identification and system pointers identifying objects addressed by the context can be materialized based on the bit setting of this field.

If the information requirements field is binary 0, the context attributes are materialized with no context entries. In this case, the modification date/time selection and object ID selection fields are ignored.

If the information requirements field is set to just return the extended context attributes, the context attributes and extended attributes are materialized with no context entries. In this case, the modification date/time selection and object ID selection fields are ignored.

If concurrency mode is set to binary 1, the instruction will periodically check for pending updates to the context. If a pending update is waiting, that update will be allowed to occur, and the materialize will continue after the update has finished.

If the system pointers field is set to binary 1, then the system pointers to objects in the context are returned in the object pointer field. If the symbolic identification field is set to binary 1, then the information in the object identification field is materialized for objects in the context.

If the validation attribute indicates no validation is to be performed, no object validation occurs and a significant performance improvement results.

When validation and/or concurrency mode is set to binary 1, some of the following pointers may be erroneous:

• Pointers to destroyed objects
• Pointers to objects that are no longer in the context
• Multiple pointers to the same object

If the materialize hidden contexts field is binary 1, then hidden contexts are materialized into the receiver (in addition to non-hidden contexts and other object types). A hidden context is denoted by the hidden attribute of a context. Since contexts can only be contained in a machine context, the materialize hidden contexts option is only useful when a machine context is being materialized. This option can only be specified when the thread is in system state. Otherwise a template value invalid (hex 3801) exception will be signalled.

The materialization control modification date/time selection and object ID selection fields specify the context entries from which information is to be presented. The type code, subtype code, and name fields contain the selection criteria when a selective materialization is specified.

When type code or type/subtype codes are part of the selection criteria, only entries that have the specified codes are considered.

If modification date/time selection is 0 and object ID selection is 0 and the number of bytes provided in the receiver does not allow for materialization of at least one context entry, requests that as much of the context attributes as will fit be materialized into the receiver and that an estimate of the byte size correlating to the full list of context entries currently in the context be set into the number of bytes available for materialization field of the receiver. This capability of requesting an estimate of the size of a full materialization of the context provides a low overhead way of getting a close approximation of the amount of space that will be needed for an actual materialize of all context entries. This approximation may be either high or low by a few entries due to abnormal system terminations.

If the number of bytes provided in the receiver allows for materialization of at least one context entry, the number of bytes available for materialization field is set with the byte size correlating to the full list of context entries that matched the selection criteria whether or not the receiver provided enough room for the full list to be materialized.

When operand 2 is a null operand, the machine context selection field is used to select which machine context to materialize. If 0 is specified for the machine context selection field, the system machine context is materialized. If 1 is specified for the machine context selection field, the independent ASP machine context specified by the independent ASP number field is materialized. If the value specified for the independent ASP number is not valid then a template value invalid (hex 3801) exception is signaled. If the associated independent ASP for the independent ASP number is not varied on, then a object not available (hex 220B) exception is signaled. If operand 2 is not a null operand, then both the machine context selection field and the independent ASP number field must be zero else a template value invalid (hex 3801) exception is signaled.

If modification date/time selection is specified, then entries are selected according to the time of last modification in addition to any object identification selection specified. The timestamp in the materialization control is used to determine which entries will be selected. Entries with modification timestamps greater than or equal to the timestamp specified in the control will be selected. Besides the additional selection done as above, the materialize will work the same as specified in the other controls.

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

Offset
Dec	Hex	Field Name	Data Type and Length
46	2E	Extended selection criteria	Char(2)
46	2E	Reserved (binary 0)	Bits 0-14
46	2E	Type/subtype range specified 0 = The type/subtype range is not specified 1 = The type/subtype range is specified	Bit 15
48	30	Range start	Char(2)
48	30	Start type	Char(1)
49	31	Start subtype	Char(1)
50	32	Range end	Char(2)
50	32	End type	Char(1)
51	33	End subtype	Char(1)
52	34	Reserved (binary 0)	Char(140)
192	C0	--- End ---

If type/subtype range specified is set to binary 1, then the following conditions apply:

• An object that meets the selection criteria will only be materialized if the ordinal value of the object type is greater than or equal to the ordinal value of start type and less than or equal to the ordinal value of end type, and the ordinal value of the object subtype is greater than or equal to the ordinal value of start subtype and less than or equal to the ordinal value of end subtype.
• The ordinal value of end type must be greater than or equal to the ordinal value of start type, and the ordinal value of end subtype must be greater than or equal to the ordinal value of start subtype. Otherwise, a template value invalid (hex 3801) exception is signaled.
• If an object type is specified as object ID selection (Hex options 1 and 5), then both the start type and end type must be set to that type. Otherwise, a template value invalid (hex 3801) exception is signaled.
• If both an object type and subtype are specified as object ID selection (Hex options 2 or 6), then a template value invalid (hex 3801) exception is signaled.
• For a object ID selection of Hex option E, the ordinal value of the object type specified must be greater than or equal to the ordinal value of start type and less than or equal to the ordinal value of end type, and the ordinal value of the object subtype specified must be greater than or equal to the ordinal value of start subtype and less than or equal to the ordinal value of end subtype. Otherwise, a template value invalid (hex 3801) exception is signaled.

If the specified timestamp is for a date/time earlier than the date/time currently associated with the changed object list, all objects in the context will be inspected for their modification date. This may degrade system performance.

The format of the materialization (operand 1) is as follows:

The first 4 bytes of the materialization output identify the total number of bytes provided for use by the instruction. This value is supplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes the materialization length invalid (hex 3803) exception to be signaled. The instruction materializes as many bytes and pointers as can be contained in the receiver. If the byte area identified by the receiver is greater than that required to contain the information requested for materialization, the excess bytes are unchanged. No exceptions are signaled in the event that the receiver contains insufficient area for the materialization, other than the materialization length invalid (hex 3803) exception described above.

When the protected attribute is set to binary 1, any attempt to insert an entry into the context or to change an entry in the context signals a cannot change contents of protected context (hex 4403) exception. Deleting an entry from the context will not cause this exception to be signaled.

The context entry object identification information, if requested by the materialization options field, is present for each entry in the context that satisfies the search criteria. If both system pointers and symbolic identification are requested by the materialization options field, the system pointer immediately follows the object identification for each entry.

The order of the materialization of a context is by object type code, object subtype code, and object name, all in ascending sequence.

Authorization Required

• Retrieve
  • Operand 2
  • Device description for the specified Independent ASP number (when the field Machine context selection is set to binary 1).

Lock Enforcement

• Materialization
  • Operand 2

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
  • 1C03 Machine Storage Limit Exceeded
• 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
  • 2403 Pointer Addressing Invalid Object Type
• 2C Program Execution
  • 2C07 Instruction Termination
• 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
  • 3803 Materialization Length Invalid
• 44 Protection Violation
  • 4401 Object Domain or Hardware Storage Protection Violation
  • 4402 Literal Values Cannot Be Changed