Change Journal State (QjoChangeJournalState) API

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:

• A user profile must exist on the target system by the same name as the user profile that is running this API on the source system.
• Synchronous delivery mode is not supported when a remote journal is specified for the qualified journal name parameter.
• The journal state of the remote journal to be activated cannot already be *ACTIVE.
• The journal state of the remote journal to be inactivated cannot already be *INACTIVE.
• If the remote journal state is *CTLINACT, then the remote journal cannot be inactivated by specifying a preferred inactivate type of controlled inactivate.
• The remote journal to be activated cannot already be replicating journal entries to other remote journals.
• A journal receiver that was never attached to a journal after Version 4 Release 2 Modification 0 has been installed cannot be replicated.
• Format CJST0100 cannot be used with a journal whose names starts with a Q, in a library that starts with Q, unless that library is QGPL.

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:

*LIBL	Library list
*CURLIB	Current library

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. Zero must be specified for this parameter when you use format CJST0200.

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:

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.

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.

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:

New journal state. Whether the depositing of journal entries into the local journal should be activated.

The possible values follow:

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.

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 higher than 1.

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:

Error Messages