Materialize Journaled Object Attributes (MATJOAT)

Operand 2: System pointer or space pointer data object.

Built-in number for MATJOAT is 86.
MATJOAT (
         receiver                             : address
         object_or_materialization_template   : address of system pointer OR
                                                address of space pointer(16)
)

Description

This instruction returns all journal information pertinent for the object whether currently journaled or not. If the object is being journaled, all information returned by this instruction is pertinent to the current journal environment the object is journaled to. If the object is not being journaled (indicated by binary 0 in the object is being journaled field), all information returned by this instruction is pertinent to the last journal environment the object was journaled to. If the journal ID is binary 0's, then the object has never been journaled.

The format of the receiver is as follows:

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 to be materialized						Bin(4)
8	8		Object journal attributes						Char(6)
8	8			Object is being journaled						Bit 0
				0 = Not journaled 1 = Journaled
8	8			Before images						Bit 1
				0 = Journal does not contain before images whenever the entry/image is optional 1 = Journal contains before images whenever the entry is optional
8	8			After images						Bit 2
				0 = Journal does not contain after images whenever the entry or image is optional 1 = Journal contains after images whenever the entry is optional
8	8			Synchronized with journal						Bit 3
				0 = Object is currently synchronized with the indicated journal 1 = Object is not currently synchronized with the indicated journal
8	8			Journal optional entries						Bit 4
				0 = Journal all entries defined for this object type 1 = Do not journal optional entries defined for this object type
8	8			Implicit journaling eligibility value						Bit 5
				0 = Object is to be considered eligible for implicit journaling 1 = Object is NOT to be considered eligible for implicit journaling
8	8			Reserved						Bits 6-8
8	8			Automatically start journaling objects						Bit 9
				0 = New objects created within this container object (directory or context) will NOT inherit the journaling attributes of this object. 1 = New objects created within this container object (directory or context) will inherit the journaling attributes of this object.
8	8			Obsolete						Bit 10
8	8			Minimal journal entries accepted						Bit 11
				0 = Journal does NOT accept minimal journal entries for this object. 1 = Journal does accept minimal journal entries for this object.
8	8			Current implicit journaling status						Bit 12
				0 = Object is not currently implicitly journaled. 1 = Object is currently implicitly journaled.
8	8			Partial transaction state of the object						Bit 13
				0 = Object has no partial transactions. 1 = Object has partial transactions.
8	8			Reserved						Bits 14-16
8	8			Remote journal filtering status of the object						Bit 17
				0 = Object has no remote journal filtering. 1 = Object has remote journal filtering enabled.
8	8			Reserved						Bits 18-30
8	8			Perpetually implicitly journaled						Bit 31
				0 = Object is not perpetually journaled 1 = Object is perpetually journaled.
8	8			Reserved						Bits 32-33
8	8			Use extended MATJOAT template						Bit 34
				0 = No MATJOAT extended template. 1 = MATJOAT extended template is available.
8	8			Reserved						Bits 35-41
8	8			Reserved						Bits 42-47
14	E		Reserved						Char(2)
16	10		Journal port						System pointer
32	20		Journal ID						Char(10)
42	2A		--- End ---

The receiver must be aligned on a 16-byte boundary. The first 4 bytes of the materialization output identify the total number of bytes provided by the user for the materialization and the next 4 specify the total number of bytes available to be materialized. If fewer than 8 bytes are available in the space identified by the receiver (operand 1), a materialization length invalid  (hex 3803) exception is signaled. The instruction materializes as many bytes as can be contained in the receiver's space. If the space of the receiver is greater than that required to contain the information requested for materialization, the excess bytes are unchanged. No exceptions are signaled when the receiver contains insufficient space for the materialization other than the materialization length exception described previously.

If the object is being journaled field has a value of binary 0, and the journal ID field is non-zero, then the journal ID and the before images, after images, synchronized with journal, journal optional entries, implicit journaling eligibility , remote journal filtering status of the object, and automatically start journaling objects fields indicate the journaling attributes of the object when it was most recently journaled, and the remaining object journal attributes fields and the journal port field will contain binary zero. If the object is being journaled field contains a value of binary zero and the journal ID field contains a value of binary zero, then the object has never been journaled and all other fields, except the materialization size specification, will also contain binary zero.

An attempt is made to synchronize the journal and the objects being journaled to it at each IPL. If this cannot be done, the object is marked as not synchronized with the journal, as specified by the synchronized with journal field. Either the load or dump operation will reestablish an object as synchronized with the journal.

The attribute indicating whether an object is currently considered for implicit journaling will be materialized in the implicit journal eligibility value field. However, there are other attributes concerning implicit journaling and information about implicitly generated Journal IDs which are not reflected by this instruction. Therefore, if an object is currently implicitly journaled, the object is being journaled will be binary 0. If an implicit Journal ID has been assigned for the object, the Journal ID will be materialized as hex 00's. If an explicit Journal ID has been assigned for the object, the Journal ID will be materialized as the explicit Journal ID value.

If the automatically start journaling objects field has a value of binary 1, and the associated object is an appropriate byte stream file object, then related byte stream file objects are allowed to adopt the same journaling attributes as this object.

If the automatically start journaling objects field has a value of binary 1, and the associated object is a context then objects added to the context are allowed to adopt the same journaling attributes as this object.

If the minimal journal entries accepted field has a value of binary 1, then minimal journal entries may be placed in the journal for this object. If the minimal journal entries accepted field has a value of binary 0, then minimal journal entries may not be placed in the journal for this object. The minimal journal entries accepted field is only returned if journaling is active (object being journaled is binary 1).

A minimal journal entry is a subset of a non-minimal journal entry, containing only a copy of the bytes which were modified within the associated object. The minimal journal entry representation may also have been subjected to compression algorithms.

The current implicit journaling status field reveals whether the object is currently being implicitly journaled by the system.

The partial transaction state of the object field reveals whether the object has partial transactions or not. If object has partial transactions, then see the partial transaction indicator for the reason partial transactions exist.

If the remote journal filtering status of the object has a value of binary 1, journal entries for the object may be filtered if the remote journal sending environment has object level filtering enabled.

The perpetually implicitly journaled field reveals whether the object is perpetually journaled or not.

The use extended MATJOAT template field indicates whether the extended MATJOAT template exists.

The extended MATJOAT template directly follows the receiver template and has the following format:

For Byte Stream File objects (object type hex 1E), the object dependent information returned is as follows:

The dump timestamp is the timestamp for when the byte stream file was dumped.

The load timestamp is the timestamp for when the byte stream file was loaded.

For all other objects, the object dependent information will be returned as binary zeros.

Note the apply information will not have meaningful data (will have blanks for name fields, binary zeros for the rest) if the object does not support having the apply information, or if the object has not been loaded, or if an apply has already been done against the loaded object after which the apply information is cleared, or if the partial transaction indicator is hex 02 (ie rollback abruptly ended prior to full completion). The apply information represents the start apply and earliest needed journal space information. The apply information is of the form:

The start apply journal entry sequence number identifies the journal entry sequence number this object would need to start apply from if the object was journalled when it was dumped and now has been loaded. Note the sequence number will only be filled in if the object was dumped while active.

The generation number for start apply further qualifies the start apply journal entry sequence number.

The earliest needed journal space sort value is to assist in sorting when dealing with multiple journal spaces due to multiple objects.

The name of earliest needed journal space identifies the name of the earliest needed journal space to exist on the system for a successful apply if the object was journalled when it was dumped and now has been loaded.

The name of context for journal space further qualifies the name of earliest needed journal space.

The name of IASP of context for journal space further qualifies the name of context for journal space.

The partial transaction indicator field indicates whether the object has partial transactions or not, and if so how the object ended up with partial transactions.

If operand 2 is a system pointer, it identifies the input object. If operand 2 is a space pointer, it provides addressability to the materialization template. The format of the materialization template is as follows:

The materialization template must be aligned on a 16-byte boundary.

The object field specifies a system pointer to the input object being materialized.

When a system pointer is used for operand 2, exceptions are never signaled if the journal port is damaged in some way. When operand 2 is a space pointer, the input template provides the signal damage exceptions for journal port option field that can indicate that exceptions should be signaled. Damage exceptions are signaled when this field is binary 1.

The reveal current implicit journaling status field indicates whether we have been instructed to report on the implicit journaling status of this object. Unless this field contains a value of one, none of the journal related fields will be filled in nor will the current implicit journaling status field accurately reveal the current status of this object.

Authorization Required

• Execute

  • Contexts referenced for address resolution

• Operational

  • Operand 2

Lock Enforcement

• Materialization

  • Operand 2

  • Contexts referenced for address resolution

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
• 1005 Authority Verification Terminated Due to Damaged Object

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

2E Resource Control Limit

• 2E01 User Profile Storage Limit Exceeded

32 Scalar Specification

• 3201 Scalar Type 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