80
| 1 | Qualified journal name | Input | Char(20) |
| 2 | Request variable | Input | Char(*) |
| 3 | Length of request variable | Input | Binary(4) |
| 4 | Format name of request variable | Input | Char(8) |
| 5 | Receiver variable | Output | Char(*) |
| 6 | Length of receiver variable | Input | Binary(4) |
| 7 | Error code | I/O | Char(*) |
The Change Journal State (QjoChangeJournalState) API is used to change the journal state for local and remote journals.
When this API is called from the source system for a local journal, the journal state may be changed from *STANDBY to *ACTIVE. A journal state of *ACTIVE for a local journal indicates that journal entries are allowed to be deposited into the attached journal receiver of the journal. A request to change the journal state of a local journal from *ACTIVE to *INACTIVE is ignored.
When this API is called from the source system for a remote journal that is associated with a source system journal, the remote journal state may be changed from *ACTIVE to *INACTIVE or from *INACTIVE to *ACTIVE. This API also allows additional attributes that are associated with the journal state to be set. For additional details on the other attributes that are associated with the journal state, see Field Descriptions.
When this API is called from the target system for a remote journal that is associated with a source system journal, the journal state may be changed from *ACTIVE to *INACTIVE.
A journal state of *ACTIVE for a remote journal indicates that journal entries can be received from the associated journal on the source system. A journal state of *INACTIVE for a remote journal indicates that journal entries are currently not being received.
The following restrictions apply:
For formats CJST0100 and CJST0200 the name of the journal for which the journal state is being changed, and the library in which it resides. For formats CJST0300, CJST0400, and CJST0500 the name of the source journal that is associated with the remote journal for which the journal state is being changed, and the library in which it resides. The first 10 characters contain the journal name, and the second 10 characters contain the name of the library where the journal is located.
The special values supported for the library name follow:
| *LIBL | Library list |
| *CURLIB | Current library |
The request variable structure that describes the input for the Change Journal State (QjoChangeJournalState) API.
The length of the request variable, in bytes. The length of the request variable must be equal to the length of the input format specified when using CJST0100 and CJST0300. Zero must be specified for this parameter when you use format CJST0200. The length of the request variable must be 58 bytes or greater when using formats CJST0400 and CJST0500.
The format of the information that is provided as input for the Change Journal State (QjoChangeJournalState) API.
The possible format names follow:
| CJST0100 | Activate a local journal from the source system. See CJST0100 Format for more information on the CJST0100 format. |
| CJST0200 | Inactivate a remote journal from the target system. There is no additional information required for format CJST0200. |
| CJST0300 | Inactivate a remote journal from the source system. See CJST0300 Format for more information on the CJST0300 format. |
| CJST0400 | Activate a synchronously maintained remote journal from the source system. See CJST0400 Format for more information on the CJST0400 format. |
| CJST0500 | Activate an asynchronously maintained remote journal from the source system. See CJST0500 Format for more information on the CJST0500 format. |
The receiver variable that is to receive output from the API. The size of the area to receive the output can be smaller than the output returned for the format requested as long as the length of receiver variable parameter is specified correctly. Only format CJST0300 returns output. If this parameter is omitted, the length of receiver variable parameter must also be omitted. If this parameter is specified, the length of receiver variable parameter must also be specified.
The length of the receiver variable, in bytes. The length of the receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of the receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. For formats other than CJST0300 this value must be 0 or the parameter must be omitted. For format CJST0300 this value must be greater than or equal to 8 or the parameter must be omitted. If this parameter is omitted, the receiver variable parameter must also be omitted.
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
The following table defines the information required for format CJST0100 to activate a local journal from the source system.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | New journal state |
The following table defines the information required for format CJST0300 to inactivate a remote journal from the source system.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(18) | Relational database directory entry |
| 18 | 12 | CHAR(20) | Remote journal |
| 38 | 26 | CHAR(1) | Preferred inactivate type |
The following table defines the information returned in the receiver variable for format CJST0300 after a remote journal has been inactivated:
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(18) | Relational database directory entry |
| 26 | 1A | CHAR(20) | Remote journal |
| 46 | 2E | CHAR(1) | Preferred inactivate type |
| 47 | 2F | CHAR(1) | Inactivate type |
| 48 | 30 | CHAR(10) | Inactivate journal receiver name |
| 58 | 3A | CHAR(10) | Inactivate journal receiver library |
| 68 | 44 | BINARY(4) | Inactivate sequence number |
| 72 | 48 | CHAR(20) | Inactivate sequence number - long |
The following table defines the information required for format CJST0400 to activate a synchronously maintained remote journal from the source system.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(18) | Relational database directory entry |
| 18 | 12 | CHAR(20) | Remote journal |
| 38 | 26 | CHAR(20) | Starting journal receiver |
| 58 | 3A | CHAR(1) | Validity checking |
| 59 | 3B | CHAR(1) | Reserved |
| 60 | 3C | BINARY(4) | Synchronous sending time-out |
| 64 | 40 | CHAR(8) | Node identifier |
| 72 | 48 | BINARY(4) | Offset to internet address array |
| 76 | 4C | BINARY(4) | Number of internet addresses |
|
80 |
50 | BINARY(4) | Maximum restart attempts |
| 84 | 54 | BINARY(4) | Restart delay time |
| 88 | 58 | CHAR(168) | Reserved
|
| * | * | Array(*) of CHAR(45) | Internet address |
The following table defines the information required for format CJST0500 to activate an asynchronously maintained remote journal from the source system.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(18) | Relational database directory entry |
| 18 | 12 | CHAR(20) | Remote journal |
| 38 | 26 | CHAR(20) | Starting journal receiver |
| 58 | 3A | CHAR(1) | Validity checking |
| 59 | 3B | CHAR(1) | Reserved |
| 60 | 3C | BINARY(4) | Sending task priority |
| 64 | 40 | CHAR(8) | Node identifier |
| 72 | 48 | BINARY(4) | Offset to internet address array |
| 76 | 4C | BINARY(4) | Number of internet addresses |
|
80 |
50 | BINARY(4) | Maximum restart attempts |
| 84 | 54 | BINARY(4) | Restart delay time |
 88 |
58 | BINARY(4) | Offset to filter by program array |
| 92 | 5C | BINARY(4) | Number of programs to filter |
| 96 | 60 | CHAR(1) | Filter by object |
| 97 | 61 | CHAR(1) | Filter images |
| 98 | 62 | CHAR(158) | Reserved
|
| * | * | Array(*) of CHAR(45) | Internet address |
|
* |
* | Array(*) of CHAR(20) | Filter by program
|
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
Filter by object. Specifies whether or not journal entries
sent to the remote journal should be filtered by object. If this field is
not provided, a value of hexadecimal zero will be assumed.
Note: When changing the filtering criteria, the Starting journal receiver (STRJRNRCV) parameter may not specify *ATTACHED or the journal receiver currently attached to the remote journal.
Note: Journal receivers on the target system that may have had journal entries filtered due to this option may not be used with the Apply Journaled Changes (APYJRNCHG), Apply Journaled Changes Extend (APYJRNCHGX), or Remove Journaled Changes (RMVJRNCHG) commands.
Note: Remote journal receivers with this attribute cannot be saved and restored to any releases prior to V7R1M0 nor can this attribute be specified if the remote system is at a release prior to V7R1M0.
The possible values follow:
| hex 00 | Journal entries sent to the remote journal will not be filtered by object. |
| 1 | Journal entries deposited for objects that indicated remote journal filtering at the time they were deposited will not be sent to the remote journal. |
Filter by program. Specifies up to ten qualified program names. The number of qualified program names in the array is controlled by the Number of programs to filter field. Journal entries sent on behalf of these programs will not be sent to the remote journal.
The first 10 characters contain the program name, and the second 10 characters contain the name of the program's library.
Note: When changing the filtering criteria, the Starting journal receiver (STRJRNRCV) parameter may not specify *ATTACHED or the journal receiver currently attached to the remote journal.
Note: Journal receivers on the target system that may have had journal entries filtered due to this option may not be used with the Apply Journaled Changes (APYJRNCHG), Apply Journaled Changes Extend (APYJRNCHGX), or Remove Journaled Changes (RMVJRNCHG) commands.
Note: Remote journal receivers with this attribute cannot be saved and restored to any releases prior to V7R1M0 nor can this attribute be specified if the remote system is at a release prior to V7R1M0.
The possible values for program library name are:
| *ALL | Journal entries for all programs that match the specified name in all libraries will not be sent to the remote journal. |
| name | The name of the program's library for which journal entries will not be sent to the remote journal. |
If the program library name has been omitted from the journal entries, no journal entries will be filtered by program name and program library name unless *ALL is specified for the program library name. If the program name has been omitted, no journal entries will be filtered by program name and program library name.
Filter images. Specifies whether or not before images will be sent to the remote journal. If this field is not provided, a value of hexadecimal zero will be assumed.
Note: When changing the filtering criteria, the Starting journal receiver (STRJRNRCV) parameter may not specify *ATTACHED or the journal receiver currently attached to the remote journal.
Note: Journal receivers on the target system that may have had journal entries filtered due to this option may not be used with the Remove Journaled Changes (RMVJRNCHG) command.
Note: Remote journal receivers with this attribute cannot be saved and restored to any releases prior to V7R1M0 nor can this attribute be specified if the remote system is at a release prior to V7R1M0.
The possible values follow:
| hex 00 | All journal entries will be sent to the remote journal, unless they are filtered by the Filter by object or Filter by program specifications. |
| 1 | Before images will not be sent to the remote journal.
|
Inactivate journal receiver library. The library of the journal receiver that contains the inactivate sequence number. This field will be blank if the system was unable to determine the library name.
Inactivate journal receiver name. The name of the journal receiver that contains the inactivate sequence number. This field will be blank if the system was unable to determine the journal receiver name.
Inactivate sequence number. If a controlled inactivate was initiated, this is the sequence number of the last journal entry that was queued for replication before the API was called. If an immediate inactivate was performed, this is the sequence number of the last journal entry that was replicated to the remote journal. This field will be 0 if the system was unable to determine the last entry that would have been, or was, replicated.
This field will be -1 if the value could not fit in the specified Binary(4) field. The complete value will be in the Inactivate sequence number - long field.
Inactivate sequence number - long. The same field as Inactivate sequence number except the information is in a Char(20) field that is treated as Zoned(20,0).
Inactivate type. How the replication of journal entries was actually ended.
The possible values follow:
| 0 | A controlled inactivate of journal entry replication is being performed. All journal entries already queued to be sent from the source system to the target system will be replicated before the inactivate operation completes. |
| 1 | An immediate inactivate of journal entry replication was performed. The system did not continue to replicate queued journal entries before inactivating the remote journal. |
Internet address. Up to four internet addresses for data port services to use when communicating to the target system. If you desire to use data port services as an alternate communication method to the target system, you must specify the name of the cluster node identifier and up to four internet addresses to the target system. Configuring clustering and data port services with multiple communication lines can provide better communications resiliency and higher data throughput. The user is responsible for configuring the TCP/IP internet addresses. The internet addresses must be configured between the source system and target system prior to activating the remote journal. See the Configuring TCP/IP topic to configure up to four distinct TCP/IP routes between the source system and the target system. Any duplicate addresses will be ignored. If this field is not provided, the internet addresses will be set to blanks and the relational database directory entry will be used for all communications to the target system.
Maximum restart attempts. The number of times
the operating system will attempt to reactivate the remote
journal after a recoverable failure. Valid values range from
0 to 200. If this field is not provided, a value of 0 will be assumed.
New journal state. Whether the depositing of journal entries into the local journal should be activated.
The possible values follow:
| 1 | *ACTIVE |
Node identifier. The node identifier for data port services to use when identifying the target system in a cluster environment. If you desire to use data port services as an alternate communication method to the target system, you must specify the name of the cluster node identifier and up to four internet addresses to the target system. Configuring clustering and data port services with multiple communication lines can provide better communications resiliency and higher data throughput. The user is responsible for configuring a cluster environment with the target system as one of its nodes. The cluster node for the target system must be active prior to activating the remote journal. For more information about setting up a cluster, see the Configuring clusters topic. If this field is not provided, a value of *NONE will be assumed and the relational database will be used for all communications to the target system.
The possible values follow:
| *NONE | The remote journal environment will not use data port services. The relational database will be used for all communications to the target system. |
| Node-Identifier | The cluster node identifier for the target system. |
Number of internet addresses. The number of addresses specified in the internet address array. The maximum value is 4. If this field is not provided, a value of 0 will be assumed.
Number of programs to filter. The number of programs
specified in the filter by program array. The maximum value is 10.
If this field is not provided, a value of 0 will be assumed.
Offset to filter by program array. The byte offset from
the beginning of the request variable to the first program to be filtered.
If this field is not provided, a value of 0 will be assumed.
Offset to internet address array. The byte offset from the beginning of the request variable to the first internet address. If this field is not provided, a value of 0 will be assumed.
Preferred inactivate type. How the replication of journal entries should be ended.
The possible values follow:
| 0 | A controlled inactivate of journal entry replication should be performed. A controlled inactivate means that the system should replicate all journal entries already queued to be sent from the source system to the target system before inactivating the remote journal. No additional journal entries will be queued after a request to perform a controlled inactivate. A controlled inactivate is not possible when a journal is in catch-up, or when it is being synchronously maintained. In both of these cases, the request to perform a controlled inactivate will be implicitly changed by the system to an immediate inactivate request. |
| 1 | An immediate inactivate of journal entry replication should be performed. An immediate inactivate means that the system should not continue to replicate any journal entries that are already queued before inactivating the remote journal. |
Relational database directory entry. The name of the relational database directory entry that contains the remote location name of the target system.
Remote journal. The name of the remote journal on the target system for which the journal state is being changed, and the library in which it resides. The first 10 characters contain the remote journal name, and the second 10 characters contain the name of the library where the remote journal is located.
Reserved. A reserved space for the purpose of alignment. This field must be initialized to binary 0.
Restart delay time. The time (in seconds) between attempts
to reactivate the remote journal after a recoverable failure. Valid values
range from 10 to 3600. This field will be ignored if Maximum restart attempts
is zero. If this field is not provided, a value of 0 will be assumed.
Sending task priority. The priority of the sending task on the source system for asynchronously maintained remote journals. The priority is a value from 1 (highest priority) through 99 (lowest priority), which represents the importance of the task when it competes with other tasks for machine resources. This value represents the relative (not absolute) importance of the task. A special value of 0 indicates that the system will choose a system default for the priority. When the system chooses a priority it is a priority value lower than 1. If this field is not provided, a value of 0 will be assumed.
Starting journal receiver. The journal receiver where the replication of journal entries from the source system to the target system will start.
The possible values follow:
| *ATTACHED | The replication of journal entries starts with the journal receiver that is currently attached to the remote journal on the target system. The journal entries are replicated from the corresponding journal receiver that is associated with the journal on the source system. The replication starts with the journal entries that follow the last journal entry that currently exists in the attached journal receiver on the target system. | ||||
| If the remote journal on the target system does not have an attached journal receiver, the journal receiver that is currently attached to the journal on the source system is created on the target system and attached to the remote journal on the target system. Then journal entries are replicated starting with the first journal entry in the journal receiver that is currently attached to the journal on the source system. | |||||
| If the journal on the source system does not have an attached journal receiver, which is only possible in the case of a remote journal that is associated with another remote journal, no journal entries can be replicated and an error is returned. | |||||
| *SRCSYS | The replication of journal entries starts with the journal receiver that is currently attached to the journal on the source system. | ||||
| If the corresponding journal receiver exists and is attached to the remote journal on the target system, journal entries are replicated starting with the journal entries that follow the last journal entry that currently exists in the attached journal receiver on the target system. Otherwise, if the corresponding journal receiver exists but is not attached to the remote journal on the target system, no journal entries can be replicated and an error is returned. | |||||
| If the corresponding journal receiver does not exist on the target system, the journal receiver is created on the target system and attached to the remote journal on the target system. Then journal entries are replicated starting with the first journal entry in the journal receiver that is currently attached to the journal on the source system. | |||||
| If the journal on the source system does not have an attached journal receiver, which is only possible in the case of a remote journal that is associated with another remote journal, no journal entries can be replicated and an error is returned. | |||||
| Qualified journal receiver name | The replication of journal entries starts with the specified
journal receiver name for the journal on the source system. The first 10
characters contain the journal receiver name, and the second 10 characters
contain the name of the library where the journal receiver is located on the
source system. The special values supported for the library name follow:
|
||||
| If the corresponding journal receiver exists and is attached to the remote journal on the target system, journal entries are replicated starting with the journal entries that follow the last journal entry that currently exists in the attached journal receiver on the target system. Otherwise, if the corresponding journal receiver exists but is not attached to the remote journal on the target system, no journal entries can be replicated and an error is returned. | |||||
| If the corresponding journal receiver does not exist on the target system, then the journal receiver is created on the target system and attached to the remote journal on the target system. Then journal entries are replicated starting with the first journal entry in the specified journal receiver on the source system. | |||||
| If the journal on the source system does not have an attached journal receiver, which is only possible in the case of a remote journal that is associated with another remote journal, no journal entries can be replicated and an error is returned. |
Synchronous sending time-out. The maximum amount of time in seconds to wait for a response from the remote system when a response is required in a synchronous remote journal environment. If a response is not received within the number of seconds specified, the remote journal environment will be inactivated. If this field is not provided, a value of 0 will be assumed.
The possible values follow:
| 0 | The system chooses the system default of 60 seconds to wait for a response from the remote system. |
| 1-3600 | Specify the maximum number of seconds to wait for a response from the remote system. |
Validity checking. Specifies whether or not to use communications validity checking. When communications validity checking is enabled, the remote journal environment will provide additional checking to verify that the data which is received by the target system matches the data that was sent from the source system. If the data does not match, the data will not be written to the target system, the remote journal environment will be inactivated, and messages indicating the communications failure will be issued to the journal message queue and QHST. If this field is not provided, a value of 0 will be assumed.
The possible values follow:
| 0 | Communications validity checking will be disabled for this remote journal environment. |
| 1 | Communications validity checking will be enabled
for this remote journal environment.
Note: Communications validity checking may impact performance. |
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF69A2 E | State of journal &1 in &2 not changed. |
| CPF69A3 E | State of journal &1 in &2 not changed. |
| CPF69AC E | Synchronous timeout &1 not valid. |
|
CPF69A8 E |
State of journal &1 in &2 not changed.
|
|
CPF69AF E |
Value not valid, reason code &1.
|
| CPF694D E | Unexpected journal receiver &8 found. |
| CPF694F E | Communications failure. |
|
CPF6942 E |
Type of journal &1 in &2 not valid.
|
|
CPF6943 E |
Receiver size options for journal &1 in
&2 not valid.
|
| CPF696A E | Request variable length &1 not valid. |
| CPF696B E | New journal state &1 not valid. |
| CPF696C E | Sending task priority &1 not valid. |
| CPF696D E | Length of receiver variable &1 not valid. |
| CPF696E E | Type of journal &1 in &2 not valid. |
| CPF696F E | State of journal &1 in &2 not changed. |
| CPF697A E | State of journal &1 in &2 not changed. |
| CPF697B E | State of journal &1 in &2 not changed. |
| CPF697C E | State of journal &1 in &2 not changed. |
| CPF697D E | State of journal &1 in &2 not changed. |
| CPF697E E | State of journal &1 in &2 not changed. |
| CPF697F E | State of journal &1 in &2 not changed. |
| CPF6973 E | Systems not compatible. |
| CPF6974 E | State of journal &1 in &2 not changed. |
| CPF698A E | State of journal &1 in &2 not changed. |
| CPF698B E | Unexpected journal receiver attached to &1. |
| CPF698C E | State of journal &1 in &2 not changed. |
| CPF698D E | Journal &1 not a remote journal. |
| CPF698E E | Journal &1 not associated with source journal. |
| CPF698F E | State of journal &1 in &2 not changed. |
| CPF6982 E | Relational database directory entry &1 not valid. |
| CPF699A E | Unexpected journal receiver &8 found. |
| CPF699C E | Receiver variable parameters not valid. |
| CPF699D E | Preferred inactivate type &1 not valid. |
| CPF699E E | State of journal &1 in &2 not changed. |
| CPF6993 E | State of journal &1 in &2 not changed. |
| CPF6994 E | State of journal &1 in &2 not changed. |
| CPF6995 E | Unexpected journal receiver &8 found. |
| CPF6996 E | Replication of journal entries ended. |
| CPF6997 E | Unexpected journal receiver &8 found. |
| CPF6998 E | State of journal &1 in &2 not changed. |
| CPF6999 E | State of journal &1 in &2 not changed. |
| CPF70DB E | Remote journal function failed. |
| CPF70D9 E | Changing journal state not allowed. |
| CPF701B E | Journal recovery of interrupted operation failed. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9810 E | Library &1 not found. |
| CPF9814 E | Device &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPFBBAC E | The offset to the data port IP address array for node &1 is not valid. |
| CPFBBAD E | The number of data port IP addresses specified for node &1 is not valid. |
| TCP1901 E | Internet address &1 is not valid. |
[ Back to top | Journal and Commit APIs | APIs by category ]