Materialize Context (MATCTX)

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 note:

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				Reserved (binary 0)						Bits 0-2
0	0				Concurrency mode						Bit 3
0	0				Extended context attributes						Bit 4
0	0				Validation						Bit 5
					0 = Validate system pointers 1 = No validation
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						Bit 1
					0 = Do not materialize hidden contexts within the operand 2 context 1 = Materialize all contexts including hidden contexts within the operand 2 context
1	1				Machine context selection						Bit 2
					0 = Materialize the system machine context. 1 = Materialize the independent ASP machine context specified by the independent ASP number field.
1	1				Modification date/time selection						Bit 3
					0 = Do not select by modification date/time 1 = Select by modification date/time
1	1				Object ID selection						Bits 4-7
					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
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 ---

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. When a name is specified as part of the selection criteria, the N characters in the search criteria are compared against the N characters of the context entry, where N is defined by the length of name to be used for search argument field in the materialization options. The remaining characters (if any) in the context entry are not used in the comparison.

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. If object ID selection has a value from hex 1 through hex 6, as many context entries as will fit which match the associated type code/subtype code/name criteria are materialized into the receiver. Object ID selection value hex E requests that as many context entries as will fit which collate at or higher (are equal to or greater) than the specified type code/subtype code/name criteria be materialized into the receiver.

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.

Programming note

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 hidden attribute determines whether or not this context is addressable. If a context is hidden, it affects the way the RSLVSP and MATCTX instructions behave. RSLVSP will not address hidden contexts. When MATCTX is used to materialize a machine context, hidden contexts in that machine context will only be materialized when the materialize hidden contexts option is set to binary 1.

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