| 1 | Qualified journal name | Input | Char(20) |
| 2 | Relational database directory entry | Input | Char(18) |
| 3 | Request variable | Input | Char(*) |
| 4 | Length of request variable | Input | Binary(4) |
| 5 | Format name of request variable | Input | Char(8) |
| 6 | Error code | I/O | Char(*) |
The Add Remote Journal (QjoAddRemoteJournal) API associates a remote journal on the target system, as identified by the relational database directory entry, with the specified journal on the source system. The journal on the source system may be either a local journal or another remote journal. A maximum of 255 remote journals may be associated with a single journal on a source system.
When adding a remote journal to a source journal, the remote journal is created on the target system using a combination of the attributes from the source journal and the input parameters provided on this API. The library that the remote journal will be created in must already exist on the target system prior to this API being called on the source system. When created by this API, the remote journal will be created with a journal type of *REMOTE and the remote journal will not have an attached journal receiver.
When adding the remote journal, the remote journal can either be created into the same named library as that of the source journal or into a redirected library on the target system. A redirected library provides a means for remote journals and any of their associated journal receivers to reside in different named libraries on the target system from the corresponding local journal and journal receivers on the local system. When specified, all validation for the journal library on the target system will be performed using the redirected library name. Similarly, the journal receivers that will later be created and associated with this remote journal can either reside in the same library as the source journal receivers on the source system, or into a distinct redirected library name on the target system. The journal receiver library redirection, if desired, must be specified when the remote journal is added using this API.
When adding a remote journal on a target system, two remote journal types can be specified, *TYPE1 and *TYPE2. The remote journal type influences the redirection capabilities, journal receiver restore operations, and remote journal association characteristics. See the Journal management topic for detailed descriptions of the differences.
If the specified journal already exists on the target system, the journal can be associated with the source journal, but only if the journal is of type *REMOTE, the remote journal type matches the specified journal type, and the journal was previously associated with this same source journal. Also, the journal may or may not have an attached journal receiver.
After the remote journal has been successfully added on the target system, the remote journal will have a journal state of *INACTIVE. A journal state of *INACTIVE for a remote journal means that the remote journal is currently not receiving journal entries from its source journal on the source system. The Change Remote Journal (CHGRMTJRN) command or the Change Journal State (QjoChangeJournalState) API is used to activate a remote journal and start the replication of journal entries from the source journal to the remote journal.
Once a remote journal has been added to a journal, the journal receiver which was attached at that time on the source system, and any journal receivers attached after that time on the source system, will be protected from deletion if all journal entries for a given journal receiver have not yet been replicated to the remote journal. This protection ends when the remote journal is removed using the Remove Remote Journal (RMVRMTJRN) command or the Remove Remote Journal (QjoRemoveRemoteJournal) API.
The following restrictions apply:
Note: The only way to change the remote journal library field and the remote journal receiver library field for a *TYPE1 journal is to do all of the following:
The name of the journal on the source system to which the remote journal is being added, and the library where it resides. The journal on the source system may be either a local journal or another remote journal. 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 name of the relational database directory entry that contains the remote location name of the target system. This name should match the name of the *LOCAL relational database directory entry on the target system.
The request variable structure that describes the input for the Add Remote Journal (QjoAddRemoteJournal) API.
The length of the request variable, in bytes. The length of the request variable must be 102 bytes or greater.
The format ADRJ0100 is the only supported format that is used by this API. See ADRJ0100 Format for more information on the ADRJ0100 format.
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 that may be provided for format ADRJ0100 when you add a remote journal.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(20) | Qualified remote journal name |
| 20 | 14 | CHAR(10) | Remote journal receiver library |
| 30 | 1E | CHAR(1) | Remote journal type |
| 31 | 1F | CHAR(20) | Qualified journal message queue |
| 51 | 33 | CHAR(1) | Delete receivers |
| 52 | 34 | CHAR(50) | Text |
| 102 | 66 | CHAR(2) | Reserved |
| 104 | 68 | BINARY(4) | Delete receivers delay |
Delete receivers. Whether the system deletes the target journal receivers when they are no longer needed or keeps them on the target system for the user to delete after they have been detached by the target system. If this field is not provided or is blank, a value of 0 is assumed. A value is only set for a journal that is created on the target system.
The possible values are:
| 0 | The target journal receivers are not deleted by the target system. |
| 1 | The target journal receivers are deleted by the target system. |
Delete receivers delay. The number of minutes (from 1 to 1440) the target system waits to retry deleting a target journal receiver if it cannot be allocated on the target system. If this field is not provided, a value of 10 minutes is assumed. A value is set for a journal that is created on the target system only.
The possible values are:
| Number | The number of minutes to delay, from 1 through 1440. |
Qualified journal message queue. The qualified name of the message queue that is associated with this remote journal. If this field is not provided or is blank, a value of QSYSOPR QSYS is assumed. A value is only set for a journal that is created on the target system.
The possible values are:
| QSYSOPR QSYS | The message is sent to the QSYSOPR message queue in library QSYS. |
| Journal message queue | The name of the message queue to which the remote journal messages are sent on the target system. If this message queue is not available when a message is to be sent, the message is sent to the QSYSOPR message queue. The first 10 characters contain the message queue name, and the second 10 characters contain the name of the library where the message queue is located. |
Qualified remote journal name. The qualified name of the remote journal on the target system. The first 10 characters contain the remote journal name; the second 10 characters contain the name of the library where the remote journal is to be located. If this field is not provided or is blank, the resolved qualified journal name is assumed.
If the remote journal type is *TYPE1, then the remote journal name must match the specified journal name. Whether a *TYPE1 or *TYPE2 remote journal is being added, the library name can be any name which will become the redirected journal library name.
Remote journal receiver library. The name of the library for the remote journal receivers on the target system that is associated with this remote journal. If this field is not provided or is blank, the journal receivers are created on the target system in the same library as they exist on the source system.
Remote journal type. The type of remote journal on the target system. The remote journal type influences the redirection capabilities, journal receiver restore operations, and remote journal association characteristics. See the Journal management topic for detailed descriptions of the differences. If this field is not provided or is blank, a value of 1 is assumed.
The possible values are:
| 1 | A *TYPE1 remote journal will be added. |
| 2 | A *TYPE2 remote journal will be added. |
Reserved. The bytes reserved to align binary fields or for
future use. This field must be set to hexadecimal zero.
Text. The text that briefly describes the remote journal on the target system. If this field is not provided, a value of all blanks is assumed. A value is only set for a journal that is created on the target system.
The possible values are:
| Text | No more than 50 characters of text. |
| 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. |
| CPF3C39 E | Value for reserved field not valid. |
| CPF3C4E E | Value not valid for field &1. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF69A4 E | Remote journal &1 in &2 not added. |
| CPF695A E | Remote journal &1 in &2 not added. |
| CPF695B E | Remote journal &1 in &2 not added. |
| CPF695C E | Remote journal &1 in &2 not added. |
| CPF695D E | Remote journal &1 in &2 not added. |
| CPF695E E | Remote journal &1 in &2 not added. |
| CPF695F E | Remote journal &1 in &2 not added. |
| CPF696A E | Request variable length &1 not valid. |
| CPF6973 E | Systems not compatible. |
| CPF6982 E | Relational database directory entry &1 not valid. |
| CPF6983 E | Remote journal &1 in &2 not added. |
| CPF6984 E | Remote journal &1 in &2 not added. |
| CPF6985 E | Remote journal &1 in &2 not added. |
| CPF6986 E | The request variable parameters are in error. |
| CPF6987 E | Field value &1 specified incorrectly. |
| CPF6988 E | Remote journal &1 in &2 not added. |
| CPF6989 E | Remote journal &1 in &2 not added. |
| CPF699B E | User profile &8 not found. |
| CPF6991 E | Remote journal &1 in &2 not added. |
| CPF70DB E | Remote journal function failed. |
| CPF70D6 E | Remote journal ended, reason code &6. |
| CPF701B E | Journal recovery of interrupted operation failed. |
| CPF7010 E | Object &1 in &2 type *&3 already exists. |
| CPF7011 E | Not enough storage. |
| 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. |
| 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. |
| Top | Journal and Commit APIs | APIs by category |