Materialize Journaled Objects (MATJOBJ)

Operand 2: System pointer.

Operand 3: Character(1) scalar.

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						Bit 0
				0 = Do not materialize pointer to object 1 = Materialize pointer to object
0	0			Materialize object ID						Bit 1
				0 = Do not materialize object ID 1 = Materialize object ID
0	0			Materialize journal object information						Bit 2
				0 = Do not materialize journal object information 1 = Materialize journal object information
0	0			Materialize only implicitly journaled objects						Bit 3
				0 = Materialize journaled objects requested in materialize implicitly and explicitly journaled objects field 1 = Materialize only implicitly journaled objects
0	0			Materialize implicitly and explicitly journaled objects						Bit 4
				0 = Materialize explicitly journaled objects 1 = Materialize implicitly and explicitly journaled objects
0	0			Materialize byte stream file and directory journaled objects						Bit 5
				0 = Do not materialize byte stream file and directory journaled objects 1 = Materialize byte stream file and directory journaled objects
0	0			Reserved (binary 0)						Bit 6
0	0			Extended input/output template						Bit 7
				0 = Do not use extended input/output template 1 = Use extended input/output template
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 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:

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.

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:

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:

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						Bit 0
					0 = Journal does not contain before images whenever the entry/image is optional 1 = Journal contains before images whenever the entry is optional
11	B				After images						Bit 1
					0 = Journal does not contain after images whenever the entry or image is optional 1 = Journal contains after images whenever the entry is optional
11	B				Do not journal optional entries						Bit 2
					0 = Journal all entries defined for this object type 1 = Do not journal optional entries defined for this object type
11	B				Automatically start journaling objects						Bit 3
					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.
11	B				Allow remote journal filtering						Bit 4
					0 = Object is not considered for remote journal object level filtering 1 = Object is considered for remote journal object level filtering
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:

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:

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.

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