Materialize Journaled Object Attributes (MATJOAT)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2
05B6 Receiver Object or materialization template
Operand 1: Space pointer.

Operand 2: System pointer or space pointer data object.

Bound Program Access 
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
    0 =
    Not journaled
    1 =
    Journaled
  • Bit 0
8
8
  • Before images
    0 =
    Journal does not contain before images whenever the entry/image is optional
    1 =
    Journal contains before images whenever the entry is optional
  • Bit 1
8
8
  • After images
    0 =
    Journal does not contain after images whenever the entry or image is optional
    1 =
    Journal contains after images whenever the entry is optional
  • Bit 2
8
8
  • Synchronized with journal
    0 =
    Object is currently synchronized with the indicated journal
    1 =
    Object is not currently synchronized with the indicated journal
  • Bit 3
8
8
  • Journal optional entries
    0 =
    Journal all entries defined for this object type
    1 =
    Do not journal optional entries defined for this object type
  • Bit 4
8
8
  • Implicit journaling eligibility value
    0 =
    Object is to be considered eligible for implicit journaling
    1 =
    Object is NOT to be considered eligible for implicit journaling
  • Bit 5
8
8
  • Reserved
  • Bits 6-8
8
8
  • Automatically start journaling objects
    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.

  • Bit 9
8
8
  • Obsolete
  • Bit 10
8
8
  • Minimal journal entries accepted
    0 =
    Journal does NOT accept minimal journal entries for this object.
    1 =
    Journal does accept minimal journal entries for this object.
  • Bit 11
8
8
  • Current implicit journaling status
    0 =
    Object is not currently implicitly journaled.
    1 =
    Object is currently implicitly journaled.
  • Bit 12
8
8
  • Partial transaction state of the object
    0 =
    Object has no partial transactions.
    1 =
    Object has partial transactions.
  • Bit 13
8
8
  • Reserved
  • Bits 14-16
8
8
  • Remote journal filtering status of the object
    0 =
    Object has no remote journal filtering.
    1 =
    Object has remote journal filtering enabled.
  • Bit 17
8
8
  • Reserved
  • Bits 18-30
8
8
  • Perpetually implicitly journaled
    0 =
    Object is not perpetually journaled
    1 =
    Object is perpetually journaled.
  • Bit 31
8
8
  • Reserved
  • Bits 32-33
8
8
  • Use extended MATJOAT template
    0 =
    No MATJOAT extended template.
    1 =
    MATJOAT extended template is available.
  • Bit 34
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:

Offset  
Dec Hex Field Name Data Type and Length
42 2A Extended MATJOAT template Char(262)
42 2A
  • Reserved (binary 0)
  • Char(6)
48 30
  • Apply information
  • Char(64)
112 70
  • Object dependent information
  • Char(32)
144 90
  • Reserved (binary 0)
  • Char(160)
304
130
--- End ---
 

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

Offset  
Dec Hex Field Name Data Type and Length
0 0 Dump timestamp Char(8)
8 8 Load timestamp Char(8)
16 10 Reserved (binary 0) Char(16)
32
20
--- End ---
 

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:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Apply information Char(64)
0 0
  • Generation number for start apply
  • UBin(4)
4 4
  • Start apply journal entry sequence number
  • Char(8)
12 C
  • Earliest needed journal space sort value
  • Char(12)
24 18
  • Name of earliest needed journal space
  • Char(10)
34 22
  • Name of context for journal space
  • Char(10)
44 2C
  • Name of IASP of context for journal space
  • Char(10)
54 36
  • Reserved (binary 0)
  • Char(2)
56
38
  • Partial transaction indicator
    Hex 00 =
    Object has no partial transactions.
    Hex 01 =
    Loaded object has partial transactions.
    Hex 02 =
    Rollback abruptly ended prior to full completion.

  • Char(1)
57 39
  • Reserved (binary 0)
  • Char(7)
64
40
--- End ---
 

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:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Materialization template Char(48)
0 0
  • Object
  • System pointer
16 10
  • Control attributes
  • Char(2)
16
10
    • Signal damage exceptions for journal port
      0 =
      Do not signal damage exceptions for the journal port
      1 =
      Signal damage exceptions if the journal port is damaged
    • Bit 0
16
10
    • Reserved
    • Bit 1
16
10
    • Reveal current implicit journaling status
      0 =
      Do not reveal the objects implicit journaling status
      1 =
      Reveal the objects current implicit journaling status
    • Bit 2
16 10
    • Reserved
    • Bit 3
16 10
    • Reserved (binary 0)
    • Bits 4-15
18 12
  • Reserved (binary 0)
  • Char(30)
48
30
--- End ---
 

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