<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation"> <title>Add Remote Journal (QjoAddRemoteJournal) API</title> <!-- Begin Header Records ========================================== --> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- JC1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 --> <!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 --> <!-- Change History: --> <!-- YYMMDD USERID Change description --> <!--File Edited Oct 2001 --> <!--End Header Records --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <a name="Top_Of_Page"></a> <!-- Java sync-link --> <script language="Javascript" src="../rzahg/synch.js" type="text/javascript"> </script> <h2>Add Remote Journal (QjoAddRemoteJournal) API</h2> <div class="box" style="width: 80%;"><br> Required Parameter Group:<br> <!-- iddvc RMBR --> <br> <table width="100%"> <tr> <td align="center" valign="top" width="10%">1</td> <td align="left" valign="top" width="50%">Qualified journal name</td> <td align="left" valign="top" width="20%">Input</td> <td align="left" valign="top" width="20%">Char(20)</td> </tr> <tr> <td align="center" valign="top">2</td> <td align="left" valign="top">Relational database directory entry</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Char(18)</td> </tr> </table> <br> Omissible Parameter Group:<br> <!-- iddvc RMBR --> <br> <table width="100%"> <tr> <td align="center" valign="top" width="10%">3</td> <td align="left" valign="top" width="50%">Request variable</td> <td align="left" valign="top" width="20%">Input</td> <td align="left" valign="top" width="20%">Char(*)</td> </tr> <tr> <td align="center" valign="top">4</td> <td align="left" valign="top">Length of request variable</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Binary(4)</td> </tr> <tr> <td align="center" valign="top">5</td> <td align="left" valign="top">Format name of request variable</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Char(8)</td> </tr> <tr> <td align="center" valign="top">6</td> <td align="left" valign="top">Error code</td> <td align="left" valign="top">I/O</td> <td align="left" valign="top">Char(*)</td> </tr> </table> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Service Program: QJOURNAL<br> <!-- iddvc RMBR --> <br> Header File: QSYSINC/H.QJOURNAL <br> <!-- iddvc RMBR --> <br> Threadsafe: No<br> <!-- iddvc RMBR --> <br> </div> <p>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.</p> <p>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.</p> <p>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.</p> <p>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 <a href= "../rzaki/rzakikickoff.htm">Journal management</a> topic for detailed descriptions of the differences.</p> <p>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.</p> <p>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.</p> <p>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.</p> <br> <h3>Restrictions</h3> <p>The following restrictions apply:</p> <ul> <li>The Add Remote Journal (QjoAddRemoteJournal) API may only be used from the source system for a local or remote journal.</li> <li>A user profile must exist on the target system by the same name as the user profile that is running the Add Remote Journal (QjoAddRemoteJournal) API on the source system.</li> <li>When adding a *TYPE1 remote journal to a source journal, the same journal and journal receiver library redirection must be specified that exists for any *TYPE1 remote journals which have already been added to the source journal. A remote journal will always use the redirected library, if any, that is specified for the local journal. <p><strong>Note:</strong> 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:</p> <ol> <li>Remove all *TYPE1 remote journals.</li> <li>Change the local journal and attach a new journal receiver.</li> <li>Delete the remote journal from the target system.</li> <li>Add the *TYPE1 remote journal, and specify the new library redirection, if any.</li> </ol> </li> <li>QTEMP cannot be specified for the remote journal library, remote journal receiver library, or remote message queue library.</li> <li>A remote journal whose name starts with a Q cannot specify a remote journal library that starts with a Q, unless the remote journal library is QGPL. This is required to prevent collisions between local and remote journals that are used for system functions.</li> <li>A *TYPE1 remote journal cannot be added to a *TYPE2 remote journal.</li> <li>The remote journal message queue on the remote journal system must be either in the same ASP group as the remote journal, or in the system ASP, or a basic user ASP.</li> <li>The remote receiver library and remote journal library on the remote system must both exist in either the system and basic user ASPs or in the same ASP group. They cannot be in two different ASP groups.</li> </ul> <br> <h3>Authorities and Locks</h3> <dl> <dt><em>Source Journal Authority</em></dt> <dd>*CHANGE, *OBJMGT</dd> <dt><em>Source Journal Library Authority</em></dt> <dd>*EXECUTE</dd> <dt><em>Target Journal Library Authority</em></dt> <dd>*EXECUTE, *ADD</dd> <dt><em>Service Program Authority</em></dt> <dd>*EXECUTE</dd> <dt><em>Source Journal Lock</em></dt> <dd>*EXCLRD</dd> <dt><em>Target Journal Library Lock</em></dt> <dd>*SHRUPD</dd> <dt><em>Target Journal Lock</em></dt> <dd>*SHRUPD</dd> </dl> <br> <h3>Required Parameter Group</h3> <dl> <dt><strong>Qualified journal name</strong></dt> <dd>INPUT; CHAR(20) <p>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.</p> <p>The special values supported for the library name follow:</p> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td valign="top"><em>*LIBL</em></td> <td valign="top">Library list</td> </tr> <tr> <td valign="top"><em>*CURLIB</em></td> <td valign="top">Current library</td> </tr> </table> <br> </dd> <dt><strong>Relational database directory entry</strong></dt> <dd>INPUT; CHAR(18) <p>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.</p> </dd> </dl> <br> <h3>Omissible Parameter Group</h3> <dl> <dt><strong>Request variable</strong></dt> <dd>INPUT; CHAR(*) <p>The request variable structure that describes the input for the Add Remote Journal (QjoAddRemoteJournal) API.</p> </dd> <dt><strong>Length of request variable</strong></dt> <dd>INPUT; BINARY(4) <p>The length of the request variable, in bytes. The length of the request variable must be 102 bytes or greater.</p> </dd> <dt><strong>Format name of request variable</strong></dt> <dd>INPUT; CHAR(8) <p>The format ADRJ0100 is the only supported format that is used by this API. See <a href="#HDRADRJ100">ADRJ0100 Format</a> for more information on the ADRJ0100 format.</p> </dd> <dt><strong>Error code</strong></dt> <dd>I/O; CHAR(*) <p>The structure in which to return error information. For the format of the structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>. If this parameter is omitted, diagnostic and escape messages are issued to the application.</p> </dd> </dl> <br> <h3><a name="HDRADRJ100">ADRJ0100 Format</a></h3> <p>The following table defines the information that may be provided for format ADRJ0100 when you add a remote journal.</p> <table border width="80%"> <tr> <th align="center" valign="bottom" colspan="2">Offset</th> <th align="left" valign="bottom" rowspan="2">Type</th> <th align="left" valign="bottom" rowspan="2">Field</th> </tr> <tr> <th align="center" valign="bottom">Dec</th> <th align="center" valign="bottom">Hex</th> </tr> <tr> <td align="center" valign="top" width="10%">0</td> <td align="center" valign="top" width="10%">0</td> <td align="left" valign="top" width="20%">CHAR(20)</td> <td align="left" valign="top" width="60%">Qualified remote journal name</td> </tr> <tr> <td align="center" valign="top">20</td> <td align="center" valign="top">14</td> <td align="left" valign="top">CHAR(10)</td> <td align="left" valign="top">Remote journal receiver library</td> </tr> <tr> <td align="center" valign="top">30</td> <td align="center" valign="top">1E</td> <td align="left" valign="top">CHAR(1)</td> <td align="left" valign="top">Remote journal type</td> </tr> <tr> <td align="center" valign="top">31</td> <td align="center" valign="top">1F</td> <td align="left" valign="top">CHAR(20)</td> <td align="left" valign="top">Qualified journal message queue</td> </tr> <tr> <td align="center" valign="top">51</td> <td align="center" valign="top">33</td> <td align="left" valign="top">CHAR(1)</td> <td align="left" valign="top">Delete receivers</td> </tr> <tr> <td align="center" valign="top">52</td> <td align="center" valign="top">34</td> <td align="left" valign="top">CHAR(50)</td> <td align="left" valign="top">Text</td> </tr> <tr> <td align="center" valign="top"> 102</td> <td align="center" valign="top">66</td> <td align="left" valign="top">CHAR(2)</td> <td align="left" valign="top">Reserved</td> </tr> <tr> <td align="center" valign="top">104</td> <td align="center" valign="top">68</td> <td align="left" valign="top">BINARY(4)</td> <td align="left" valign="top">Delete receivers delay</td> </tr> </table> <br> <br> <h3><a name="HDRADRJFLD">Field Descriptions</a></h3> <p><strong>Delete receivers.</strong> 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.</p> <p>The possible values are:</p> <table cellpadding="5"> <!-- cols="5 95" --> <tr> <td valign="top"><em>0</em></td> <td valign="top">The target journal receivers are not deleted by the target system.</td> </tr> <tr> <td valign="top"><em>1</em></td> <td valign="top">The target journal receivers are deleted by the target system.</td> </tr> </table> <p><strong>Delete receivers delay.</strong> 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.</p> <p>The possible values are:</p> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td valign="top"><em>Number</em></td> <td valign="top">The number of minutes to delay, from 1 through 1440.</td> </tr> </table> <p><strong>Qualified journal message queue.</strong> 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.</p> <p>The possible values are:</p> <table width="100%" cellpadding="5"> <tr> <td width="25%" valign="top"><em>QSYSOPR QSYS</em></td> <td width="75%" valign="top">The message is sent to the QSYSOPR message queue in library QSYS.</td> </tr> <tr> <td valign="top"><em>Journal message queue</em></td> <td valign="top">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.</td> </tr> </table> <p><strong>Qualified remote journal name.</strong> 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.</p> <p>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.</p> <p><strong>Remote journal receiver library.</strong> 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.</p> <p><strong>Remote journal type.</strong> 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 <a href="../rzaki/rzakikickoff.htm">Journal management</a> topic for detailed descriptions of the differences. If this field is not provided or is blank, a value of 1 is assumed.</p> <p>The possible values are:</p> <table cellpadding="5"> <!-- cols="5 95" --> <tr> <td valign="top"><em>1</em></td> <td valign="top">A *TYPE1 remote journal will be added.</td> </tr> <tr> <td valign="top"><em>2</em></td> <td valign="top">A *TYPE2 remote journal will be added.</td> </tr> </table> <p><br> <strong>Reserved.</strong> The bytes reserved to align binary fields or for future use. This field must be set to hexadecimal zero.</p> <p><strong>Text.</strong> 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.</p> <p>The possible values are:</p> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td valign="top"><em>Text</em></td> <td valign="top">No more than 50 characters of text.</td> </tr> </table> <br> <h3>Error Messages</h3> <table width="100%" cellpadding="5"> <!-- cols="15 85" --> <tr> <th align="left" valign="top">Message ID</th> <th align="left" valign="top">Error Message Text</th> </tr> <tr> <td width="15%" valign="top">CPF24B4 E</td> <td width="85%" valign="top">Severe error while addressing parameter list.</td> </tr> <tr> <td valign="top">CPF3CF1 E</td> <td valign="top">Error code parameter not valid.</td> </tr> <tr> <td valign="top">CPF3C21 E</td> <td valign="top">Format name &1 is not valid.</td> </tr> <tr> <td valign="top">CPF3C39 E</td> <td valign="top">Value for reserved field not valid.</td> </tr> <tr> <td valign="top">CPF3C4E E</td> <td valign="top">Value not valid for field &1.</td> </tr> <tr> <td valign="top">CPF3C90 E</td> <td valign="top">Literal value cannot be changed.</td> </tr> <tr> <td valign="top">CPF69A4 E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF695A E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF695B E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF695C E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF695D E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF695E E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF695F E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF696A E</td> <td valign="top">Request variable length &1 not valid.</td> </tr> <tr> <td valign="top">CPF6973 E</td> <td valign="top">Systems not compatible.</td> </tr> <tr> <td valign="top">CPF6982 E</td> <td valign="top">Relational database directory entry &1 not valid.</td> </tr> <tr> <td valign="top">CPF6983 E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF6984 E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF6985 E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF6986 E</td> <td valign="top">The request variable parameters are in error.</td> </tr> <tr> <td valign="top">CPF6987 E</td> <td valign="top">Field value &1 specified incorrectly.</td> </tr> <tr> <td valign="top">CPF6988 E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF6989 E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF699B E</td> <td valign="top">User profile &8 not found.</td> </tr> <tr> <td valign="top">CPF6991 E</td> <td valign="top">Remote journal &1 in &2 not added.</td> </tr> <tr> <td valign="top">CPF70DB E</td> <td valign="top">Remote journal function failed.</td> </tr> <tr> <td valign="top">CPF70D6 E</td> <td valign="top">Remote journal ended, reason code &6.</td> </tr> <tr> <td valign="top">CPF701B E</td> <td valign="top">Journal recovery of interrupted operation failed.</td> </tr> <tr> <td valign="top">CPF7010 E</td> <td valign="top">Object &1 in &2 type *&3 already exists.</td> </tr> <tr> <td valign="top">CPF7011 E</td> <td valign="top">Not enough storage.</td> </tr> <tr> <td valign="top">CPF8100 E</td> <td valign="top">All CPF81xx messages could be returned. xx is from 01 to FF.</td> </tr> <tr> <td valign="top">CPF9801 E</td> <td valign="top">Object &2 in library &3 not found.</td> </tr> <tr> <td valign="top">CPF9802 E</td> <td valign="top">Not authorized to object &2 in &3.</td> </tr> <tr> <td valign="top">CPF9803 E</td> <td valign="top">Cannot allocate object &2 in library &3.</td> </tr> <tr> <td valign="top">CPF9810 E</td> <td valign="top">Library &1 not found.</td> </tr> <tr> <td valign="top">CPF9820 E</td> <td valign="top">Not authorized to use library &1.</td> </tr> <tr> <td valign="top">CPF9830 E</td> <td valign="top">Cannot assign library &1.</td> </tr> <tr> <td valign="top">CPF9872 E</td> <td valign="top">Program or service program &1 in library &2 ended. Reason code &3.</td> </tr> </table> <br> <hr> API Introduced: V4R2 <hr> <table cellpadding="2" cellspacing="2" align="center"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "jc1.htm">Journal and Commit APIs</a> | <a href="aplist.htm">APIs by category</a></td> </tr> </table> </body> </html>