ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/QJOADDRJ.htm

762 lines
22 KiB
HTML

<!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>
&nbsp;&nbsp;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>
&nbsp;&nbsp;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>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Service Program: QJOURNAL<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Header File: QSYSINC/H.QJOURNAL <br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;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 &amp;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 &amp;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 &amp;1 in &amp;2 not added.</td>
</tr>
<tr>
<td valign="top">CPF695A E</td>
<td valign="top">Remote journal &amp;1 in &amp;2 not added.</td>
</tr>
<tr>
<td valign="top">CPF695B E</td>
<td valign="top">Remote journal &amp;1 in &amp;2 not added.</td>
</tr>
<tr>
<td valign="top">CPF695C E</td>
<td valign="top">Remote journal &amp;1 in &amp;2 not added.</td>
</tr>
<tr>
<td valign="top">CPF695D E</td>
<td valign="top">Remote journal &amp;1 in &amp;2 not added.</td>
</tr>
<tr>
<td valign="top">CPF695E E</td>
<td valign="top">Remote journal &amp;1 in &amp;2 not added.</td>
</tr>
<tr>
<td valign="top">CPF695F E</td>
<td valign="top">Remote journal &amp;1 in &amp;2 not added.</td>
</tr>
<tr>
<td valign="top">CPF696A E</td>
<td valign="top">Request variable length &amp;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 &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF6983 E</td>
<td valign="top">Remote journal &amp;1 in &amp;2 not added.</td>
</tr>
<tr>
<td valign="top">CPF6984 E</td>
<td valign="top">Remote journal &amp;1 in &amp;2 not added.</td>
</tr>
<tr>
<td valign="top">CPF6985 E</td>
<td valign="top">Remote journal &amp;1 in &amp;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 &amp;1 specified incorrectly.</td>
</tr>
<tr>
<td valign="top">CPF6988 E</td>
<td valign="top">Remote journal &amp;1 in &amp;2 not added.</td>
</tr>
<tr>
<td valign="top">CPF6989 E</td>
<td valign="top">Remote journal &amp;1 in &amp;2 not added.</td>
</tr>
<tr>
<td valign="top">CPF699B E</td>
<td valign="top">User profile &amp;8 not found.</td>
</tr>
<tr>
<td valign="top">CPF6991 E</td>
<td valign="top">Remote journal &amp;1 in &amp;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 &amp;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 &amp;1 in &amp;2 type *&amp;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 &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td valign="top">CPF9802 E</td>
<td valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td valign="top">CPF9803 E</td>
<td valign="top">Cannot allocate object &amp;2 in library &amp;3.</td>
</tr>
<tr>
<td valign="top">CPF9810 E</td>
<td valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td valign="top">CPF9820 E</td>
<td valign="top">Not authorized to use library &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF9830 E</td>
<td valign="top">Cannot assign library &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;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>