Change Journal State (QjoChangeJournalState) API


  Required Parameter Group:


  Omissible Parameter Group:


  Default Public Authority: *USE

  Service Program: QJOURNAL

  Header File: QSYSINC/H.QJOURNAL

  Threadsafe: No

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.


Restrictions

The following restrictions apply:


Authorities and Locks

Source Journal Authority
*CHANGE, *OBJMGT
Source Journal Library Authority
*EXECUTE
Source Journal Receiver Authority
*USE, *OBJMGT
Source Journal Receiver Library Authority
*EXECUTE
Service Program Authority
*EXECUTE
Source Journal Lock
*SHRUPD
Source Journal Receiver Lock
*SHRRD
Target Journal Lock
*SHRUPD
Target Journal Receiver Lock
*SHRRD
Target Journal Receiver Library Lock
*SHRUPD

Required Parameter Group

Qualified journal name
INPUT; CHAR(20)

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:


Request variable
INPUT; CHAR(*)

The request variable structure that describes the input for the Change Journal State (QjoChangeJournalState) API.

Length of request variable
INPUT; BINARY(4)

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.

Format name of request variable
INPUT; CHAR(8)

The format of the information that is provided as input for the Change Journal State (QjoChangeJournalState) API.

The possible format names follow:


Omissible Parameter Group

Receiver variable
OUTPUT; CHAR(*)

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.

Length of receiver variable
INPUT; BINARY(4)

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.

Error code
I/O; CHAR(*)

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.


CJST0100 Format

The following table defines the information required for format CJST0100 to activate a local journal from the source system.


CJST0300 Format

The following table defines the information required for format CJST0300 to inactivate a remote journal from the source system.


The following table defines the information returned in the receiver variable for format CJST0300 after a remote journal has been inactivated:


CJST0400 Format

The following table defines the information required for format CJST0400 to activate a synchronously maintained remote journal from the source system.


CJST0500 Format

The following table defines the information required for format CJST0500 to activate an asynchronously maintained remote journal from the source system.


Field Descriptions

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.

The possible values follow:


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.

The possible values for program library name are:


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.

The possible values follow:


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:


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:


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:


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:


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:


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:


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:



Error Messages



API Introduced: V4R2