Materialize Journaled Objects (MATJOBJ)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2 Operand 3
05A7 Input/Output template Journal port Materialization options
Operand 1: Space pointer.

Operand 2: System pointer.

Operand 3: Character(1) scalar.

Bound Program Access 
Built-in number for MATJOBJ is 87.
MATJOBJ (
         input/output_template     : address
         journal_port              : address of system pointer
         materialization_options   : address
)

Description:

This instruction materializes the system pointers to the objects that are currently being journaled through the journal port specified by operand 2 and places them in the input/output template (operand 1). It also returns the object ID and journal object information of the object if these options are specified by operand 3.

The materialization options are as follows:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Materialize options Char(1)
0
0
  • Materialize pointer to object
    0 =
    Do not materialize pointer to object
    1 =
    Materialize pointer to object
  • Bit 0
0
0
  • Materialize object ID
    0 =
    Do not materialize object ID
    1 =
    Materialize object ID
  • Bit 1
0
0
  • Materialize journal object information
    0 =
    Do not materialize journal object information
    1 =
    Materialize journal object information
  • Bit 2
0
0
  • Materialize only implicitly journaled objects
    0 =
    Materialize journaled objects requested in materialize implicitly and explicitly journaled objects field
    1 =
    Materialize only implicitly journaled objects
  • Bit 3
0
0
  • Materialize implicitly and explicitly journaled objects
    0 =
    Materialize explicitly journaled objects
    1 =
    Materialize implicitly and explicitly journaled objects
  • Bit 4
0
0
  • Materialize byte stream file and directory journaled objects
    0 =
    Do not materialize byte stream file and directory journaled objects
    1 =
    Materialize byte stream file and directory journaled objects
  • Bit 5
0
0
  • Materialize attached commit blocks
    0 =
    Do not materialize attached commit blocks only
    1 =
    Materialize attached commit blocks only
  • Bit 6
0
0
  • Extended input/output template
    0 =
    Do not use extended input/output template
    1 =
    Use extended input/output template
  • Bit 7
1
1
--- End ---
 

If at least one of the first three materialize options is not set to binary 1, a scalar value invalid (hex 3203) exception is signaled.

The default, if neither materialize only implicitly journaled objects or materialize implicitly and explicitly journaled objects is set to binary 1, is to return only information about explicitly journaled objects. If materialize only implicitly journaled objects is set to binary 1, then only information about implicitly journaled objects will be returned. If materialize implicitly and explicitly journaled objects is set to binary 1, then information about both explicitly and implicitly journaled objects will be returned. Setting both options to binary 1 will result in a scalar value invalid (hex 3203) exception being signaled. Implicitly journaled objects are those that are journaled by the system for object protection.

If materialize attached commit blocks is set to binary 1, then only information for attached commit blocks will be returned. The materialize only implicitly journaled objects, materialize implicitly and explicitly journaled objects, materialize byte stream file and directory journaled objects, and selection operation options are ignored.

If materialize byte stream file and directory journaled objects is set to binary 1, then information about journaled byte stream file and directory objects will be returned. If materialize pointer to object is set to binary 1 and materialize only byte stream file and directory objects is set to binary 1 and the caller is NOT system state, then a scalar value invalid (hex 3203) exception is signaled.

The input/output template identified by operand 1 must be 16-byte aligned in the space and have 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 by the user
  • Bin(4)
4 4
  • Number of bytes available for materialization
  • Bin(4)
8 8 Number of object data entries materialized UBin(4)
12
C
Reserved (binary 0)
If extended input/output template specifies a value of binary 0, then immediately following the reserved field above are the object data entries. If extended input/output template specifies a value of binary 1, then following the reserved field above is the template extension, and the object data entries are located by the offset to object data field in the template extension.  All fields included in the template extension are required to be set (binary 0 if unused) when extended input/output template is set to binary 1 (this includes all reserved areas). Note the object data entries must start on a 16-byte boundary.
Char(4)
16 10 Template extension Char(*)
16 10
  • Extended materialize options
  • Char(1)
16 10
    • Selection operation
    • Bits 0-1
16
10
      • Return objects matching the object type data specification
        0 =
        Do not return objects matching the object type data specification
        1 =
        Return objects matching the object type data specification
      • Bit 0
16
10
      • Omit objects matching the object type data specification
        0 =
        Do not omit objects matching the object type data specification
        1 =
        Omit objects matching the object type data specification
      • Bit 1
16 10
    • Materialize object apply information and object dependent information
    • Bit 2
16
10
    • Materialize information units
      0 =
      Materialization size is in 1 byte units
      1 =
      Materialization size is in 4K (4096 bytes) units
    • Bit 3
16
10
    • Return journaled object counts
      0 =
      Do not return journaled object counts
      1 =
      Return journaled object counts
    • Bit 4
16 10
    • Reserved (binary 0)
    • Bits 5-7
17 11
  • Reserved (binary 0)
  • Char(1)
18 12
  • Number of entry type data entries
  • UBin(2)
20 14
  • Offset to object data
  • UBin(4)
24 18
  • Total number of objects journaled
  • UBin(4)
28 1C
  • Offset to array of journaled object count fields
  • UBin(4)
32 20
  • Reserved (binary 0)
  • Char(16)
48 30
  • Array of journaled object count fields
  • [256] UBin(4)
1072 430
  • Entry type data (0 to m)
  • [*] Char(1)
* * Object data (0 to n) [*] Char(*)
*
*
--- End ---
 

The first 4 bytes of the input/output template 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. The materialize information units field specifies the units used for the number of bytes provided by the user. A minimum of 8 bytes must be provided for number of bytes provided by the user. When materialization information units is a simple byte count, a value of less than 8 causes the materialization length invalid (hex 3803) exception to be signaled. When materialization information units is in 4k increments it takes only one 4k increment to assure 8 bytes are present so the materialization length invalid (hex 3803) exception will only be signaled if the value is 0.

The second 4 bytes of the input/output template identify the total number of bytes available to be materialized. The materialize information units field specifies the units used for the number of bytes available for materialization. The instruction materializes as many bytes as can be contained within the area allowed for the object data. If the bytes provided is greater than the bytes available, the excess bytes are unchanged.

Only one selection operation may have a value of binary 1, all other selection operations must have a value of binary 0, or a template value invalid (hex 3801) exception will be signaled. If one selection operation has a value of binary 1 but number of entry type data entries is zero, a template value invalid (hex 3801) exception will be signaled. If one selection operation has a value of binary 1, and number of entry type data entries is non-zero, the entry type data specification will be processed to determine which journaled objects to materialize.

If all selection operations have a value of binary 0, the number of entry type data entries and entry type data array fields are ignored and not used to determine which journaled objects to materialize.

The materialize information units states in what units the fields number of bytes provided by the user and number of bytes available for materialization are specified. If it is binary 0, the information is in 1 byte units. If it is binary 1, then both of these fields are in 4K (4096 bytes) units.

The return journaled object counts field specifies whether or not the journaled object counts should be materialized. If return journaled object counts has a value of binary 0, the journaled object counts are not returned. If return journaled object counts has a value of binary 1, the journaled object counts are returned in the array of journaled object count fields.

The total number of objects journaled is returned to reflect how many objects are journaled to the journal port regardless of the number of object data entries materialized (because of materialize options and/or selection operation these are not necessarily the same).

The offset to object data specifies the offset to the object data from the start of the template extension.

The array of journaled object count fields is defined as an array of fields, numbered from 0 to 255. The index entry of the array is the journal entry type. Each entry of the array is a 4 byte unsigned count revealing how many journaled objects of the matching journal entry type are associated with the journal port. For example, if the count at element hex 0B is 3, the journal port currently has three instances of objects with journal entry type hex 0B journaled. Since hex 0B is the journal entry type associated with Data Spaces, the journal currently has three Data Spaces journaled.

Note that the sum of all these object count fields is NOT assured to equal the total number of objects journaled. Implicitly journaled access paths, for instance, are among the objects which contribute to the total count but are not separately materialized.

For each journaled object that is materialized there is an entry. These entries are in arbitrary order. The number of object data entries materialized will depend on materialize options chosen.

If materialize pointer to object is set to binary 1, then the following system pointer is returned first in each object data entry.

Offset  
Dec Hex Field Name Data Type and Length
0 0 Journal object System pointer
16
10
--- End ---
 

If materialize object ID is set to binary 1, then the journal object system pointer (if requested) is immediately followed by the object ID of the form:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Object ID Char(32)
0 0
  • Object type
  • Char(1)
1 1
  • Object subtype
  • Char(1)
2 2
  • Object name
  • Char(30)
32
20
--- End ---
 

If materialize byte stream file and directory journaled objects is set to binary 1 and materialize object ID is set to binary 1, then the object name field has the format in the following template:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Reserved (binary 0) Char(14)
14 E Byte stream file and directory object file ID Char(16)
30
1E
--- End ---
 

Usage note: The byte stream file and directory object file ID field can be used as input to the Qp0lGetPathFromFileID() API to get the path name of the object.

If materialize journal object information is set to binary 1, then the journal object information immediately follows the object ID (if requested) and/or the journal object system pointer (if requested). The journal object information is in the form:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Journal object information Char(16)
0 0
  • Journal ID
  • Char(10)
10 A
  • Entry type
  • Char(1)
11 B
  • Object journal attributes
  • Char(1)
11
B
    • 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 0
11
B
    • 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 1
11
B
    • Do not journal optional entries
      0 =
      Journal all entries defined for this object type
      1 =
      Do not journal optional entries defined for this object type
    • Bit 2
11
B
    • 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 3
11
B
    • Allow remote journal filtering
      0 =
      Object is not considered for remote journal object level filtering
      1 =
      Object is considered for remote journal object level filtering
    • Bit 4
11 B
    • Reserved
    • Bits 5-7
12 C
  • Reserved (binary 0)
  • Char(4)
16
10
--- End ---
 

Journal ID is the unique identifier associated with the object when journalling is started for that object.

Entry type is the journal entry type for the object.

If materialize object apply information and object dependent information is set to binary 1, then the apply information immediately follows the journal object information (if requested), and/or the object ID (if requested), and/or the journal object system pointer (if requested). Note the apply information will not have meaningful data (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 =
    Object loaded with partial transactions.
    Hex 02 =
    Rollback abruptly ended prior to full completion.

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

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

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 journaled 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 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 journaled when it was saved and now has been restored.

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.

When materialize object apply information and object dependent information is set to binary 1, the object dependent information immediately follows the apply information, and is of the form:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Object dependent information Char(32)
32
20
--- 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.

Authorization Required

  • Retrieve
    • Operand 2
  • Execute
    • Contexts referenced for address resolution

Lock Enforcement

  • Materialization
    • Contexts referenced for address resolution
    • 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
    • 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
    • 2403 Pointer Addressing Invalid Object Type
  • 2E Resource Control Limit
    • 2E01 User Profile Storage Limit Exceeded
  • 32 Scalar Specification
    • 3201 Scalar Type 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