Materialize Journal Space Attributes (MATJSAT)

Instruction Syntax

Op Code (Hex) Operand 1 Operand 2
05BE Receiver Journal space
Operand 1: Space pointer.

Operand 2: System pointer.

Bound Program Access 
Built-in number for MATJSAT is 85.
MATJSAT (
         receiver        : address
         journal_space   : address of system pointer
)

Warning

The following information is subject to change from release to release. Use it with caution and be prepared to adjust for changes with each new release.

Description:

This instruction materializes the current attributes of the journal space specified by operand 2 and places the attributes in the receiver specified by operand 1.

The format of the materialization data is as follows:

Offset  
Dec Hex Field Name Data Type and Length
0 0 Materialization length Char(8)
0 0
  • Number of bytes provided by user
  • Bin(4)
4 4
  • Number of bytes available to be materialized
  • Bin(4)
8 8 Object identification Char(32)
8 8
  • Object type
  • Char(1)
9 9
  • Object subtype
  • Char(1)
10 A
  • Object name
  • Char(30)
40 28 Object creation options Char(4)
40 28
  • Existence attributes (binary 1)
  • Bit 0

40

28

  • Primary associated space attributes

    0 =
    Fixed-length
    1 =
    Variable-length

  • Bit 1
40 28
  • Initial context
  • Bit 2
40 28
  • Access group
  • Bit 3
40 28
  • Replace option
  • Bit 4
40 28
  • Reserved
  • Bits 5-12
40 28
  • Initialize primary associated space
  • Bit 13
40 28
  • Reserved
  • Bits 14-18

40

28

  • Use system storage

    0 = System storage not used
    1 = System storage used

  • Bit 19
40 28
  • Reserved (binary 0)
  • Bits 20-31
44 2C Recovery options Char(4)
48 30 Size of primary associated space Bin(4)
52 34 Initial value of primary associated space Char(1)
53 35 Performance class Char(4)
57 39 Reserved (binary 0) Char(7)
64 40 Context System pointer
80 50 Access group System pointer
96 60 Narrow maximum threshold (in bytes) Bin(4)
100 64 Narrow minimum threshold value (in bytes) Bin(4)
104 68 Percent threshold Bin(2)
106 6A Journal space flags Char(1)
106 6A
  • Reserved (binary 0)
  • Bit 0

106

6A

  • Default journal space

    0 =
    Not a default journal space
    1 =
    Default journal space

  • Bit 1

106

6A

  • Remote journal

    0 =
    Journal space is not remote
    1 =
    Journal space is remote

  • Bit 2

106

6A

  • Remote journal object filtering

    0 =
    Journal space is not object filtering
    1 =
    Journal space is object filtering

  • Bit 3

106

6A

  • Remote journal before image filtering

    0 =
    Journal space is not before image filtering
    1 =
    Journal space is before image filtering

  • Bit 4

106

6A

  • Remote journal program filtering

    0 =
    Journal space is not program filtering
    1 =
    Journal space is program filtering

  • Bit 5
106 6A
  • Reserved (binary 0)
  • Bits 6-7

107

6B

Journal space capacity value

Hex 00 =
Maximum sequence number: 2,147,483,136 and maximum journal space size: 2 Gigabytes
Hex 01 =
Maximum sequence number: 9,999,999,999 and maximum journal space size: 1 Terabyte
Hex 02 =
Maximum sequence number: 9,999,999,999 and maximum journal space size: 1 Terabyte and Maximum entry size: 4,000,000,000 bytes
Hex 03 =
Maximum sequence number: 18,446,744,073,709,551,600 and maximum journal space size: 1 Terabyte and Maximum entry size: 4,000,000,000 bytes

Char(1)
108 6C Reserved (binary 0) Char(10)
118 76 Maximum alternate nullmap length Bin(2)
120 78 Maximum entry length UBin(4)
124 7C Narrow last confirmed sequence number Bin(4)
128 80 Journal port System pointer
144 90 Narrow number of journal entries Bin(4)
148 94 Narrow first sequence number Bin(4)
152 98 Narrow last sequence number Bin(4)
156 9C Generation number UBin(4)
160 A0 Time journal space attached to journal port Char(8)
168 A8 Time journal space detached from journal port Char(8)
176 B0 Length of timestamp Bin(2)
178 B2 Length of process name Bin(2)
180 B4 Length of user profile name Bin(2)
182 B6 Length of program name Bin(2)
184 B8 Fixed length data Char(1)

184

B8

  • Include program context name and ASP number

    0 =
    Program context name and ASP number will not be in journal entries.
    1 =
    Program context name and ASP number will be in journal entries.

  • Bit 0

184

B8

  • Include system sequence number

    0 =
    System sequence number will not be in journal entries.
    1 =
    System sequence number will be in journal entries.

  • Bit 1

184

B8

  • Include remote address

    0 =
    Remote address will not be in journal entries.
    1 =
    Remote address will be in journal entries.

  • Bit 2

184

B8

  • Include thread ID

    0 =
    Thread identifier will not be in journal entries.
    1 =
    Thread identifier will be in journal entries.

  • Bit 3

184

B8

  • Include logical unit of work

    0 =
    Logical unit of work will not be in journal entries.
    1 =
    Logical unit of work will be in journal entries.

  • Bit 4

184

B8

  • Include transaction identifier

    0 =
    Transaction identifier will not be in journal entries.
    1 =
    Transaction identifier will be in journal entries.

  • Bit 5
184 B8
  • Reserved (binary 0)
  • Bits 6-7
185 B9 Reserved (binary 0) Char(1)
186 BA Length of system sequence number UBin(2)
188 BC Narrow last journal entry dumped Bin(4)
192 C0 Journal space status Char(2)

192

C0

  • Operable journal space

    0 =
    Journal space is operable
    1 =
    Journal space is not operable

  • Bit 0

192

C0

  • Missing journal entries

    0 =
    No entries missing
    1 =
    1 or more entries missing

  • Bit 1

192

C0

  • Journal space size extension

    0 =
    Journal space could be extended
    1 =
    Journal space could not be extended

  • Bit 2

192

C0

  • Maximum sequence number reached

    0 =
    Maximum sequence number has not been reached
    1 =
    Maximum sequence number has been reached

  • Bit 3

192

C0

  • Journal failure

    0 =
    No journal failure has occurred
    1 =
    A journal failure has occurred

  • Bit 4

192

C0

  • Recoverable commit boundary

    0 =
    All objects with changes journaled to this journal space are at a recoverable commit boundary
    1 =
    One or more objects with changes journaled to this journal space are not at a recoverable commit boundary

  • Bit 5

192

C0

  • Journal space is attached

    0 =
    Journal space is not attached to a journal port
    1 =
    Journal space is attached to a journal port

  • Bit 6

192

C0

  • Journal space STANDBY status

    0 =
    Journal space has never been in STANDBY
    1 =
    Journal space has at 1 time been in STANDBY

  • Bit 7

192

C0

  • Journal port object limit

    0 =
    The journal port to which this journal space has been attached supports up to 250,000 objects being simultaneously journaled.
    1 =
    The journal port to which this journal space has been attached supports up to 100,000,000 objects being simultaneously journaled.

  • Bit 8

192

C0

  • Minimal entry status

    0 =
    Minimized entries will not be deposited into this journal space.
    1 =
    Minimized entries may be deposited into this journal space.

  • Bit 9

192

C0

  • Minimal entry type

    0 =
    Minimized entries are deposited without ensuring data space field boundaries
    1 =
    Minimized entries are deposited with data on data space field boundaries

  • Bit 10
192 C0
  • Reserved (binary 0)
  • Bits 11-15
194 C2 Entry specific data longest length table Char(*)
194 C2
  • Number of entries in table
  • Bin(4)
198 C6
  • Entry specific data length elements
  • [*] Char(6)
198 C6
    • Entry specific data ID
    • Char(2)
200 C8
    • Entry specific data longest length
    • UBin(4)
* *
  • Maximum threshold (in basic storage units)
  • Bin(4)
* *
  • Minimum threshold value (in basic storage units)
  • Bin(4)
* *
  • Last confirmed sequence number
  • Char(8)
* *
  • Number of journal entries
  • Char(8)
* *
  • First sequence number
  • Char(8)
* *
  • Last sequence number
  • Char(8)
* *
  • Last journal entry dumped
  • Char(8)
* *
  • Minimal entry array by entry type
  • Char(32)
* * Reserved (binary 0) Char(128)
* * Remote journal program filter table Char(*)
* *
  • Number of program filter entries in table
  • UBin(4)
* *
  • Program filter entry
  • [*] Char(20)
* *
    • Program name
    • Char(10)
* *
    • Program context
    • Char(10)

*

*

--- End ---

 

The receiver must be aligned on a 16-byte boundary. The first 4 bytes of the receiver identify the total number of bytes provided by the user for the materialization and the next 4 specify on output 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 in the event that the receiver contains insufficient space for the materialization other than the materialization length invalid (hex 3803) exception described previously.

The remote journal field indicates whether this journal space was attached to a remote journal port or not.

The remote journal object filtering field indicates whether this journal space has object filtering enabled or not. Note this field will have a value of binary 0 if this is not a remote journal space.

The remote journal before image filtering field indicates whether this journal space has before image filtering enabled or not. Note this field will have a value of binary 0 if this is not a remote journal space.

The remote journal program filtering field indicates whether this journal space has program filtering enabled or not. If the remote journal program filtering has a value of binary 1, then the remote journal program filter table will also be returned. Note this field will have a value of binary 0 if this is not a remote journal space.

The journal space capacity value field returns the upper limits that are being imposed on both the maximum size of this journal space, the maximum journal sequence number allowed, and the maximum size for a journal entry.

The last confirmed sequence number field contains the journal sequence number of the last valid journal entry contained in this journal space. If the number of journal entries field contains a value of 0, this field will also contain a value of 0.

The maximum alternate nullmap length field contains the maximum length of the nullmap when it is used to return null indicators and minimized entry field indicators. If the number of journal entries field contains a value of 0, this field will also contain a value of 0.

The maximum entry length field contains the length of the largest journal entry contained in this journal space. If the number of journal entries field contains a value of 0, this field will also contain a value of 0.

The journal port field contains a system pointer to the journal port to which the designated journal space is currently attached. If the journal space is not currently attached to a journal port, this field will contain binary 0's.

The number of journal entries field contains the number of journal entries currently in the journal space. If this field contains a value of 0, the journal space has never been attached to a journal port.

The first sequence number field contains the journal sequence number of the first journal entry contained in this journal space. If the number of journal entries field contains a value of 0, this field will also contain a value of 0.

The last sequence number field contains the journal sequence number of the last journal entry contained in this journal space. If the number of journal entries field contains a value of 0, this field will also contain a value of 0. If journal entries are cloaked in the journal space, this field will be the sequence number of the last uncloaked journal entry.

The generation number field contains the count of the number of times the sequence number had been reset at the time the journal space was attached.

The time journal space attached to journal port field contains a timestamp that indicates the time the journal space was attached to a journal port. If the journal space has never been attached to a journal port, a value of 0 will be returned in this field.

The time journal space detached from journal port field contains a timestamp that indicates the time the journal space was detached from a journal port. If the journal space has never been attached to a journal port or is currently attached to a journal port, a value of 0 will be returned in this field.

The length of timestamp field contains the length of the timestamp field in the journal prefix of journal entries contained on the journal space. If the journal space has never been attached to a journal port (number of journal entries is equal to 0), this field will contain a value of 0.

The length of process name field contains the length of the process name field in the journal prefix of journal entries contained on the journal space. If the journal space has never been attached to a journal port (number of journal entries is equal to 0), this field will contain a value of 0.

The length of user profile name field contains the length of the user profile name field in the journal prefix of journal entries contained on the journal space. If the journal space has never been attached to a journal port (number of journal entries is equal to 0), this field will contain a value of 0.

The length of program name field contains the length of the program name field in the journal prefix of journal entries contained on the journal space. If the journal space has never been attached to a journal port (number of journal entries is equal to 0), this field will contain a value of 0.

The fixed length data field indicates whether various fixed length data is in the journal entries. A value of binary 1 for the following fields indicates that that specific data will be included in each journal entry in the journal space attached to the journal port.

  • include logical unit of work
  • include transaction identifier
  • include remote address
  • include program context name and ASP number
  • include system sequence number
  • include thread identifier
A value of binary 0 indicates that that specific data will NOT be included in those journal entries.

The length of system sequence number field contains the length in bytes of the system sequence number field in the journal prefix of journal entries contained on the journal space. If the journal space has never been attached to a journal port (number of journal entries is equal to 0), this field will contain a value of 0.

The last journal entry dumped field contains the journal sequence number of the last complete journal entry that has been dumped from this journal space. If no dump operation has been performed on this journal space, a value of 0 will be returned.

The journal space status fields indicate whether or not the journal space is currently actively receiving journal entries or successfully received all journal entries while it was attached to a journal port. These fields also indicate the reason journal entries were not placed on the journal space and whether all objects with changes journaled to this journal space are currently at a recoverable commit boundary.

The operable journal space field indicates whether or not journal entries are being placed in the journal space while it is attached to the indicated journal port. If the journal space is no longer attached to a journal port, this field indicates the status of the journal space when it was detached from the journal port.

The missing journal entries field indicates whether or not journal entries have been created, while this journal space was attached to a journal port, that were not recorded on this journal space.

The journal space size extension field indicates whether or not the journal space can be extended. A value of binary 1 in this field indicates a user profile storage limit exceeded (hex 2E01) exception was encountered while trying to extend the journal space.

The journal failure field indicates whether or not a journal failure occurred while this journal space was attached to a journal port.

The recoverable commit boundary field indicates whether all objects with changes journaled to this journal space are at a recoverable commit boundary. A value of binary 0 in this field indicates that all objects are at a recoverable commit boundary.

The journal space is attached field indicates whether this journal space is currently attached to a journal port.

The journal space STANDBY status field indicates whether this journal space has been attached to a journal port and that port has gone into STANDBY mode at least once while this journal space was attached.

The journal port object limit field indicates the limit on the number of objects which can be journaled to the journal port to which the space has been attached. A value of binary 0 indicates that the journal space has been attached to a journal port which supports up to 250,000 journaled objects. A value of binary 1 indicates that the journal space has been attached to a journal port which supports up to 100,000,000 journaled objects.

The minimal entry status field indicates whether minimized entries may be deposited into this journal space. A value of binary 0 indicates that minimized entries will not be deposited. A value of binary 1 indicates that minimized entries may be deposited into this journal space for at least one entry type.

The minimal entry type field is only valid for minimized entries deposited for data spaces. This field indicates whether minimized entries are deposited with or without ensuring that an entire data space field is deposited into the journal entry if the particular data space field has been modified. A value of binary 0 indicates that the minimized entries are deposited without ensuring data space field boundaries. A value of binary 1 indicates that the minimized entries are deposited ensuring data space field boundaries.

The entry specific data longest length table contains the longest length associated with each entry specific data ID found on the journal space. If the journal space has never been attached to a journal port or there are no entries on the journal space, a value of 0 will be returned in the number of entries in table field.

Note: A number of fields ( last confirmed sequence number, number of journal entries, first sequence number, last sequence number, last journal entry dumped ) deliberately appear twice in the materialization data, once in a 'Narrow' representation and again in a wider (UBin 8) representation. When the value returned for each such field is less than 2G (2,147,483,648) it will be returned in both the wide and narrow representation. However, when the actual value is too large to be represented in a Bin(4) field, the narrow instance of such a field will contain, instead, the value of -1. In a similar fashion, both the maximum threshold and minimum threshold value fields appear twice. The 'Narrow' designated representation is the traditional byte count while the ordinary representation is expressed in basic storage units. For a small capacity journal space both fields will contain proper values in their respective units. However, for a large capacity (i.e. 1 Terabyte) journal space the thresholds may be too large to be represented as a byte count. In that instance the 'Narrow' representations will each contain the value of -1 and the true threshold sizes will be present only in the ordinary threshold fields.

The minimal entry array by entry type field is defined as an array of bits, numbered from 0 to 255, one bit per entry type. Each bit indicates that minimized journal entries may or may not have been deposited to this space for the corresponding entry type. For an entry type N, minimal entry array by entry type bit N = 0 indicates that minimized entries do NOT exist within the space for the entry type N. Minimal entry array by entry type bit N = 1 indicates that minimized entries might exist within the space for the entry type N. Entry types are defined in the MATJPAT instruction.

The remote journal program filter table contains the list specified on the source system of which programs to filter from sending to the remote journal. The program context can be specified as *ALL so the program name alone determines whether a specific journal entry is filtered. If the remote journal program filtering field has a value of binary 0, the remote journal program filter table is not returned.

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
    • 2403 Pointer Addressing Invalid Object Type
  • 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
    • 3803 Materialization Length Invalid
  • 44 Protection Violation
    • 4401 Object Domain or Hardware Storage Protection Violation
    • 4402 Literal Values Cannot Be Changed
Parent topic: Journal Management