Operand 2: System pointer or space pointer data object.
Bound program access
Built-in number for MATJPAT is 84.
MATJPAT (
receiver : address
journal_port_or_materialize_template : address of system pointer OR
address of space pointer(16)
)
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.
This instruction materializes the creation
attributes of the journal port
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
Space attributes
Bit 1
0 =
Fixed-length
1 =
Variable-length
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 space
Bit 13
40
28
Reserved
Bits 14-18
40
28
Use system storage
Bit 19
0 =
System storage not used
1 =
System storage used
40
28
Reserved
Bits 20-31
44
2C
Recovery options
Char(4)
48
30
Size of space
Bin(4)
52
34
Initial value of space
Char(1)
53
35
Performance class
Char(4)
57
39
Reserved
Char(7)
64
40
Context
System pointer
80
50
Access group
System pointer
96
60
Length of timestamp in prefix
Bin(2)
98
62
Length of process name in prefix
Bin(2)
100
64
Length of user profile name in prefix
Bin(2)
102
66
Length of program name in prefix
Bin(2)
104
68
Number of journal spaces attached to the journal port
Bin(2)
106
6A
Journal entry force count
Bin(4)
110
6E
Journal port flags
Char(1)
110
6E
Default journal port
Bit 0
0 =
Not a default journal port for
implicitly journaled objects.
1 =
Default journal port for
implicitly journaled objects.
110
6E
Journal port commit quiesce status
Bit 1
0 =
No quiesce of all commit activity to a
transaction boundary is in progress against this
journal port.
1 =
The quiesce of all commit activity to a
transaction boundary is in progress against this
journal port.
110
6E
Discard transient entries
Bit 2
0 =
Do not discard transient entries in the permanent
journal space.
1 =
Discard transient entries in the
permanent journal space.
110
6E
Remote journal port
Bit 3
0 =
Not a remote journal port
1 =
Remote journal port
110
6E
Obsolete
Bit 4
110
6E
Prevent objects from being journaled
Bit 5
0 =
Objects are allowed to be journaled to this journal port
1 =
Objects are prevented from being journaled to this journal port
110
6E
Standby mode
Bit 6
0 =
Port is not in standby mode
1 =
Port is in standby mode
110
6E
Caching mode
Bit 7
0 =
Port is not in caching mode
1 =
Port is in caching mode
111
6F
Default journal port ID
Char(2)
113
71
Remote journal attributes
Char(3)
113
71
Receiving environment attribute flags
Char(1)
113
71
Remote journal environment
Bit 0
0 =
A remote journal receiving environment does not exist for this
journal port
1 =
A remote journal receiving environment does exist for this journal port
113
71
Delivery mode
Bit 1
0 =
Synchronous delivery mode
1 =
Asynchronous delivery mode
113
71
Reserved (binary 0)
Bits 2-7
114
72
Transport mechanism
Char(1)
Hex 01 = Bus transport
Hex 02 = SNA
Hex 03 = TCP/IP
Hex 04 = Data port services
Hex 05 = Sockets
115
73
Environment status
Char(1)
Hex 00 = Unknown
Hex 01 = Active
Hex 02 = Catch-up in progress
Hex 03 = Controlled end in progress
Hex 04 = Suspended
Hex 05 = Error
116
74
Number of remote sending environments
UBin(4)
120
78
Number of journaled objects
UBin(4)
124
7C
Fixed length data
Char(1)
124
7C
Include program context name and ASP number
Bit 0
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.
124
7C
Include system sequence number
Bit 1
0 =
System sequence number
will not be in journal entries.
1 =
System sequence number
will be in journal entries.
124
7C
Include remote address
Bit 2
0 =
Remote address
will not be in journal entries.
1 =
Remote address
will be in journal entries.
124
7C
Include thread ID
Bit 3
0 =
Thread identifier
will not be in journal entries.
1 =
Thread identifier
will be in journal entries.
124
7C
Include logical unit of work
Bit 4
0 =
Logical unit of work
will not be in journal entries.
1 =
Logical unit of work
will be in journal entries.
124
7C
Include transaction identifier
Bit 5
0 =
Transaction identifier
will not be in journal entries.
1 =
Transaction identifier
will be in journal entries.
124
7C
Reserved (binary 0)
Bits 6-7
125
7D
Quiesced Status
Char(1)
Hex 00 =
Journal port is not currently quiesced
'S'=
Journal port has been quiesced such that there are
no current open commit cycles and no additional
cycles are allowed to start (this is the quiesced
state achieved in support of traditional
Save While Active)
'R'=
Journal port has been quiesced only to the point where
no operations are in flux. This does not assure that
commit cycles are closed. (this is the quiesced
state achieved in support of Ragged
Save While Active)
126
7E
Additional journal port flags
Char(1)
126
7E
Journal port object limit
Bit 0
0 =
Up to 250,000 journaled objects can be simultaneously
journaled to this port
1 =
Up to 100,000,000 journaled objects can be simultaneously
journaled to this port
126
7E
Minimal entry status
Bit 1
0 =
Minimized entries will not be deposited.
1 =
Minimized entries may be deposited.
126
7E
Minimal entry type
Bit 2
0 =
Minimized entries are deposited without ensuring
data space field boundaries
1 =
Minimized entries are deposited with data on data space field
boundaries
126
7E
Reserved (binary 0)
Bits 3-7
127
7F
Reserved (binary 0)
Char(1)
128
80
Journal spaces (0 to n)
[*] System pointer
*
*
Sending environment templates (0 to m)
[*] Char(48)
*
*
Minimal entry array
Char(32)
*
*
Journal recovery ratio
UBin(4)
*
*
Reserved (binary 0)
Char(108)
*
*
Receiving environment template (0 or 1)
[*] Char(96)
*
*
--- 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
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.
Each journal space currently attached to the journal port will
be identified in the journal space
list. This list has as many entries as are identified in the number of journal spaces attached to the journal port field.
The journal entry force count is the value
which is used to determine how many journal
entries are allowed to be deposited on the journal before forcing those
entries to disk.
The discard transient entries value indicates whether
entries of a transient nature, those used strictly for the recovery of
objects at IPL time, should be permanently associated with the journal
space.
The remote journal port field indicates whether this is
a remote journal port. A remote journal port
receives entries from another journal port via a remote journal receiving
environment. No entries can be deposited to a remote journal port.
The default journal port ID
will be zeros if the journal port is
not a default journal.
The prevent objects from being journaled field indicates
whether objects are allowed to be journaled to this journal port.
The standby mode field indicates
whether the port is currently in standby mode.
Those ports which are in standby mode allow only a small select
subset of critical journal entries to be deposited into the journal
space.
The caching mode field indicates
whether the port is currently in caching mode.
Those ports which are in caching mode do not immediately write all
journal entries to disk. Rather, they allow most journal entries
to linger within a main memory cache until the cache is nearly full.
The remote journal attributes fields indicate the status of
the receiving environment for remote journal ports. The values in
these fields only apply to remote journal ports and will be
binary 0's for non-remote journal ports.
The remote journal environment field indicates whether
a remote journal receiving environment exists for this journal port.
If remote journal environment contains a binary 1, then
the receiving environment template is returned.
The delivery mode field indicates how journal entries are
sent to this journal port. A synchronous delivery mode means that
journal entries are sent to this journal concurrently with the
entry being deposited on the journal port on the source system. An asynchronous delivery mode means that journal entries are
sent to this journal port at some time after entries have been deposited
on the journal port on the source system. The delivery mode
does not apply and will contain a value of binary 0 if a remote
journal receiving environment does not exist for the journal port or
the environment status field indicates that the environment
is in a suspended or unknown state.
The transport mechanism field indicates whether bus-level
support or communications-level support
or data port services or sockets
is being used to transport the
journal entries. The transport mechanism field in the remote journal attributes section of the materialize template
indicates the mechanism used by this remote journal port to receive
entries from another source journal port. The transport
mechanism field does not apply and will contain a value of binary
0 if a remote journal receiving environment does not exist for the
journal port. The transport mechanism field in the sending environment template(s) indicates the mechanism used
to send journal entries from this journal port to the remote journal
port.
The environment status field indicates the current state of
the remote journal environment. A value of hex 01 indicates an
active remote journaling environment. A value of hex 02 indicates
a remote journal port is currently in the process of catching up journal
entries from a source journal port. The catch-up phase is considered
complete when the transition is made to either synchronous or
asynchronous remote journaling. A value of hex 02 in the environment status field in the remote journal
attributes section of the materialize template indicates
this remote journal port is currently catching up entries
from another source journal port. A value of hex 02 in the environment status field in the sending environment
template(s) indicates the remote journal port is currently in the
process of catching up journal entries from this journal port. A
value of hex 03 indicates that the remote environment is ending
controlled. A value of hex 04 indicates that the environment has been
suspended because the environment did not successfully transition to
an active state following the catch-up phase. A value of hex 05
indicates that an error has been detected and the environment is
waiting to be deleted. The environment status field in the remote journaling attributes section of the materialize
template does not apply and will have a value of binary 0 if a remote
journal receiving environment does not exist for the journal port.
The number of remote sending environments field indicates the
number of remote journal ports that this journal port is actively sending
journal entries to. Information about each of the remote
journal ports is provided in the sending environment template(s)
below.
The number of journaled objects field indicates the number of
objects actively being journaled to this port. This includes both
implicitly and explicitly journaled objects.
The fixed length data field indicates whether various
fixed length data is in the journal entries. A value
of binary 1 for any of 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 journal port object limit field indicates whether
the port can simultaneously journal up to 250,000 objects or
100,000,000 objects.
The phrase minimized entries used below refers to a
technique by which the machine is able to sense that some but not all of
the bytes within a database record have been altered.
Upon sensing such a state, the machine may attempt to
produce a journal entry that contains only the changes rather than
a copy of the entire record. The resulting reduced-size image is
referred to as a minimized entry since it generally
consumes less space than a copy of the entire record. These
resulting minimized entry images come in two forms: those that
honor field boundaries and those that do not. The variety
selected is determined by attributes associated with the journal
port.
The minimal entry status field indicates whether minimized
entries may be deposited. 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 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 for data spaces
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 journal recovery ratio field indicates an upper limit
regarding the preferred number of
journal entries per journal port that
will be processed following an abnormal IPL. A value of 0 (zero)
signifies that a system determined value will be used.
The minimal entry array field is defined as an array
of bits, numbered from 0 to 255, one bit per entry type.
Each bit indicates that minimal
journal entries may or may not be deposited to this port for the
corresponding entry type. For an entry type N, minimal entry
by entry type bit N = 0 indicates that minimal entries are NOT accepted
for the entry type N. Minimal entry
by entry type bit N = 1 indicates that minimal entries are accepted
for the entry type N.
The entry type indicates the type of object which is having its
change activity journaled. In most cases, the entry type corresponds
directly to the object's MI type. However, some MI types are used to represent
more than one flavor of object. For this reason, the entry type
for Data Area's is hex A0. All other objects use the MI type.
If the remote journal environment contains a binary 1, then
the receiving environment template is returned as follows:
Offset
Dec
Hex
Field Name
Data Type and Length
0
0
Receiving environment template
Char(96)
0
0
Receiving environment statistics
Char(48)
0
0
Timestamp when catch-up started
Char(8)
8
8
Timestamp when transitioned to active
Char(8)
16
10
Estimated 100ths of seconds behind
UBin(4)
20
14
Maximum 100ths of seconds behind
UBin(4)
24
18
Maximum 100ths of seconds behind timestamp
Char(8)
32
20
Reserved (binary 0)
Char(16)
48
30
Reserved (binary 0)
Char(48)
96
60
--- End ---
The receiving environment statistics are reset to binary zero
when a receiving environment is activated.
The timestamp when catch-up started indicates when
catch-up was started.
The timestamp when transitioned to active indicates when
the receiving environment went active.
The estimated 100ths of seconds behind is the amount of
time from when a journal bundle has been written to disk on the
source system to when the bundle arrives on the target system.
This field only applies to asynchronous remote journal
environments and will contain a value of hex 0 for synchronous
remote journal environments.
The maximum 100ths of seconds behind indicates the maximum estimated 100ths of seconds behind recorded since the
remote journal was activated.
The maximum
100ths of seconds behind timestamp is when maximum 100ths of seconds behind was captured.
This field only applies to asynchronous remote journal
environments and will contain a value of hex 0 for synchronous
remote journal environments.
The sending environment template is repeated for each sending
environment.
If operand 2 is a system pointer, or if operand 2 is a space pointer
and extended sending environment template contains a value
of binary zero, then the format of the sending environment template is as follows:
Offset
Dec
Hex
Field Name
Data Type and Length
0
0
Sending environment template
Char(48)
0
0
Remote journal ID
Char(10)
10
A
Sending enviroment attributes
Char(1)
10
A
Delivery mode
Bit 0
0 =
Synchronous delivery mode
1 =
Asynchronous delivery mode
10
A
Checksum validity checking
Bit 1
0 =
Checksum validity checking disabled
1 =
Checksum validity checking enabled
10
A
Reserved (binary 0)
Bits 2-7
11
B
Transport mechanism
Char(1)
Hex 01 = Bus transport
Hex 02 = SNA
Hex 03 = TCP/IP
Hex 04 = Data port services
Hex 05 = Sockets
12
C
Environment status
Char(1)
Hex 00 = Unknown
Hex 01 = Active
Hex 02 = Catch-up in progress
Hex 03 = Controlled end in progress
Hex 04 = Suspended
Hex 05 = Error
13
D
Reserved (binary 0)
Char(3)
16
10
Priority of asynchronous sending task
Char(1)
17
11
Reserved (binary 0)
Char(3)
20
14
Timeout for synchronous sending environment
UBin(4)
24
18
Timestamp of last change in number of dataport lines
Char(8)
32
20
Reserved (binary 0)
Char(2)
34
22
Number of active dataport lines
UBin(2)
36
24
Reserved (binary 0)
Char(12)
48
30
--- End ---
If operand 2 is a space pointer and extended sending environment template contains a value of
binary one, then the format of the sending environment template is as follows:
Offset
Dec
Hex
Field Name
Data Type and Length
0
0
Sending environment template
Char(160)
0
0
Remote journal ID
Char(10)
10
A
Sending enviroment attributes
Char(1)
10
A
Delivery mode
Bit 0
0 =
Synchronous delivery mode
1 =
Asynchronous delivery mode
10
A
Checksum validity checking
Bit 1
0 =
Checksum validity checking disabled
1 =
Checksum validity checking enabled
10
A
Reserved (binary 0)
Bits 2-7
11
B
Transport mechanism
Char(1)
Hex 01 = Bus transport
Hex 02 = SNA
Hex 03 = TCP/IP
Hex 04 = Data port services
Hex 05 = Sockets
12
C
Environment status
Char(1)
Hex 00 = Unknown
Hex 01 = Active
Hex 02 = Catch-up in progress
Hex 03 = Controlled end in progress
Hex 04 = Suspended
Hex 05 = Error
13
D
Reserved (binary 0)
Char(3)
16
10
Priority of asynchronous sending task
Char(1)
17
11
Reserved (binary 0)
Char(3)
20
14
Timeout for synchronous sending environment
UBin(4)
24
18
Timestamp of last change in number of dataport lines
Char(8)
32
20
Reserved (binary 0)
Char(2)
34
22
Number of active dataport lines
UBin(2)
36
24
Reserved (binary 0)
Char(12)
48
30
Sending environment statistics
Char(68)
48
30
Sending environment activation timestamp
Char(8)
56
38
Catchup timestamp
Char(8)
64
40
Number of bundles
UBin(4)
68
44
Largest bundle
UBin(4)
72
48
Largest bundle timestamp
Char(8)
80
50
Number of 100ths of seconds behind
UBin(4)
84
54
Maximum number of 100ths of seconds behind
UBin(4)
88
58
Maximum number of 100ths of seconds behind timestamp
Char(8)
96
60
Number of entries behind
UBin(4)
100
64
Maximum number of entries behind
UBin(4)
104
68
Maximum number of entries behind timestamp
Char(8)
112
70
Super bundle count
UBin(4)
116
74
Socket IP information
Char(44)
116
74
Local port number
UBin(2)
118
76
Remote port number
UBin(2)
120
78
Length of local IP address
UBin(4)
124
7C
Length of remote IP address
UBin(4)
128
80
Local IP address
Char(16)
144
90
Remote IP address
Char(16)
160
A0
--- End ---
The priority of asynchronous sending task field contains the
priority of the task sending journal entries to the remote journal
port relative to the priority of processes on the machine.
This field only applies to asynchronous remote journal sending
environments and will contain a value of binary 0 for synchronous
remote journal sending environments associated with the journal port.
The timeout for synchronous sending environment field
contains the maximum amount of time in milliseconds to wait
for a response from the remote system when a response is required.
This field only applies when the delivery mode
indicates synchronous delivery mode. This field
will contain a value of binary 0 when the delivery mode
indicates asynchronous delivery mode for
the sending environment attributes
associated with the journal port.
A value of zero for this field when synchronous delivery mode
is configured indicates that the machine determines the timeout value
to use.
The checksum validity checking field indicates whether
a checksum (a sum derived from the data to be sent) is generated
on the source system. If a checksum is generated then
the checksum is validated when the data arrives on the target system
to assure the data is free from errors or tampering.
The timestamp of last change in number of dataport lines
indicates the last time the number of active dataport lines
changed. If the transport mechanism is not Hex 04 Data port
services, this field will be binary zero.
The number of active dataport lines
indicates how many dataport lines currently are active to send
data. If the transport mechanism is not Hex 04 Data port
services, this field will be binary zero.
The sending environment statistics are reset to binary zero
when a sending environment is activated. Also
the sending environment statistics will wrap.
The sending environment activation timestamp indicates the
date and time that the environment status transitioned from catch-up in progress to active.
The catch-up timestamp indicates the date and time that the environment status transitioned to catch-up in progress.
The number of bundles is the number of bundles of journal
entries transmitted since the environment status
transitioned to active.
The largest bundle is the largest number of bytes of a bundle
of journal entries transmitted. The largest bundle timestamp
is the date and time that the largest bundle was sent.
The number of 100ths of seconds behind indicates
how far behind an asynchronous remote journal is compared to
the current deposits to the journal.
This field only applies to asynchronous remote journal sending
environments and will contain a value of hex 0 for synchronous
remote journal sending environments associated with the journal port.
The maximum number of 100ths of seconds behind indicates
the furthest behind an asynchronous remote journal was compared to
the current deposits to the journal at that time. A value of hex
FFFFFFFF indicates that the sending environment was over 497 days
behind. The maximum number of
100ths of seconds behind timestamp is that date and time that maximum number of 100ths of seconds behind was captured.
This field only applies to asynchronous remote journal sending
environments and will contain a value of hex 0 for synchronous
remote journal sending environments associated with the journal port.
The number of entries behind indicates
how far behind an asynchronous remote journal is compared to
the current deposits to the journal.
This field only applies to asynchronous remote journal sending
environments and will contain a value of hex 0 for synchronous
remote journal sending environments associated with the journal port.
The maximum number of entries behind indicates the
furthest behind an asynchronous remote journal was compared to the
current deposits to the journal at that time. Maximum number of
entries behind timestamp is that date and time that maximum number of entries behind was captured.
This field only applies to asynchronous remote journal sending
environments and will contain a value of hex 0 for synchronous
remote journal sending environments associated with the journal port.
The super bundle count indicates the number of times
an asynchronous remote journal has gone into super bundle mode.
Super bundling mode can be viewed as an overdrive behavior.
As the quantity of unsent journal bundles begins to accumulate
on the source side, the machine senses this
growing set of unsent bundles and elects to combine together
consecutive journal bundles
into a longer combined string and sends the resulting
super bundle across the communication wire as a single packet
rather than sending each such bundle individually.
This field only applies to asynchronous remote journal sending
environments and will contain a value of hex 0 for synchronous
remote journal sending environments associated with the journal port.
The socket port information and socket IP information is returned for
the sending environment if the transport mechanism is
Hex 05 Sockets, otherwise these fields will be binary zero.
The local port number returns the port number for the
local connection. The remote port number returns the
port number for the remote connection.
The length of local IP address
and length of remote IP address specify a length of 4
bytes for an IPv4 address or a length of 16 bytes for an IPv6
address.
The local IP address returns the IP address of the
local socket,
and will be left-aligned.
The remote IP address returns the IP address of the
remote peer,
and will be left-aligned.
If operand 2 is a system pointer,
it identifies the input journal port
object. If operand 2 is a space pointer, it provides addressability to
the materialize template.
The materialize template is used
to
identify default journal ports by ASP and default journal port ID.
Returned in the materialize template is
a system pointer to the
currently known default journal port with the specified ID.
The format of the materialize
template is as follows:
Offset
Dec
Hex
Field Name
Data Type and Length
0
0
Materialize template
Char(32)
0
0
ASP
Char(2)
+
2
2
Default journal port ID
Char(2)
+
4
4
Template options
Char(1)
4
4
Extended sending environment template
Bit 0
0 =
Do not use the extended sending environment format
1 =
Use the extended sending environment format
4
4
Reserved (binary 0)
Bits 1-7
5
5
Reserved (binary 0)
Char(11)
16
10
Journal port
System pointer
32
20
--- End ---
Note:
The fields marked with a plus sign (+) are input to this instruction.
The materialize template must be aligned on a 16-byte boundary.
The ASP field
indicates the ASP on which the default journal port
resides.
The default journal port ID
uniquely identifies the default journal port
on the specified ASP.
The extended sending environment template indicates
which variety of sending template should be processed.
The journal port currently known as the default journal port of the
specified ID and ASP is returned. If there is no known default port,
a null pointer value will be returned.
*
