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

620 lines
18 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!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>Retrieve Journal Identifier Information (QJORJIDI) 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 Kersten 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 type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Retrieve Journal Identifier Information (QJORJIDI) API</h2>
<div class="box" style="width: 70%;">
<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%">Receiver variable</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Length of receiver variable</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Qualified journal name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Journal identifier value</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Format name</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;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Retrieve Journal Identifier Information (QJORJIDI) API retrieves the
current name and type of the object associated with the specified journal
identifier (JID) for the specified journal. A JID is unique; it is assigned to
a particular object when journaling is started for the object. The JID
associates the journal entries with a particular object. See <a href=
"#HDRSYSJID">Maintaining a JID for a Journaled Object</a> for more information
about how the system maintains a JID value for a journaled object.</p>
<p>This API retrieves the object name and type associated with a particular JID
if:</p>
<ul>
<li>The specified JID is associated with an object that is journaled to the
specified journal.</li>
<li>The specified JID is associated with an object that was journaled to the
specified journal, but the object has since been deleted and a change journal
operation<sup>1</sup> has not yet attached a new receiver.</li>
<li>The specified JID is associated with an object that was journaled to the
specified journal, but journaling has since been ended for the object and a
change journal operation<sup>1</sup> has not yet attached a new receiver. This
is true even if the object is currently journaled to a different journal than
the one specified.</li>
</ul>
<p>This API cannot retrieve an object name for a specified JID if:</p>
<ul>
<li>The specified JID was never associated with an object journaled to the
specified journal.</li>
<li>The specified JID is associated with an object that was journaled to the
specified journal, but the object has since been deleted and a change journal
operation has attached a new receiver.</li>
<li>The specified JID is associated with an object that was journaled to the
specified journal, but journaling has since been ended for the object and a
change journal operation has attached a new receiver.</li>
</ul>
<p><strong>Note:</strong> The change journal operation can be a user initiated
Change Journal (CHGJRN) command or from system change-journal management
support. System change-journal management support is activated by a Create
Journal (CRTJRN) or Change Journal (CHGJRN) command with the MNGRCV(*SYSTEM)
parameter and value.</p>
<p>If an object name or file identifier cannot be retrieved, blanks are
returned for the object name, library name, member name, type, and object file
identifier.</p>
<p>The JID for the object associated with a particular journal entry is in the
fixed-length portion of the journal entry when specifying:</p>
<ul>
<li>OUTPUT(*OUTFILE) and OUTFILFMT(*TYPE4) on the Display Journal (DSPJRN)
command.</li>
<li>ENTFMT(*TYPE4 or *TYPEPTR) on the Receive Journal Entry (RCVJRNE)
command.</li>
<li>ENTFMT(*TYPE4) on the Retrieve Journal Entry (RTVJRNE) command.</li>
</ul>
<p><sup>1</sup> The change journal operation can be a user-initiated Change
Journal (CHGJRN) command or from system change-journal management support.
System change-journal management support is activated by a Create Journal
(CRTJRN) or Change Journal (CHGJRN) command with the MNGRCV(*SYSTEM) parameter
and value.</p>
<br>
<h3><a name="HDRSYSJID">Maintaining a JID for a Journaled Object</a></h3>
<p>The following are the system rules for maintaining a JID for a journaled
object:</p>
<ul>
<li>A JID is assigned for a journaled object when journaling is first started
for the object. For example, when journaling is started for a database file
with a single member, a JID value is assigned to the data portion of the
member. If two members exist in the file, a different JID is assigned to the
data portion for each member.<br>
<br>
</li>
<li>The JID remains the same for the journaled object if:<br>
<br>
<ul>
<li>The object is moved to a different library.</li>
<li>The object is renamed.</li>
<li>Journaling is ended for the object, and then started again to either the
same journal or to a different journal.</li>
<li>The object is saved while being journaled, deleted from the system, and
then restored from the saved version. This is true whether the object is being
restored to the original system from which it was saved or to a different
system, as long as the same version of the object does not already exist on
that system.</li>
</ul>
<br>
</li>
<li>The JID does not remain the same for the journaled object if:<br>
<br>
<ul>
<li>The object is deleted, and then created again. When journaling is started
for the newly created object, a new JID is assigned.</li>
<li>The object is saved while being journaled, then renamed or moved to another
library, and then the object is restored using the saved version. The restored
version will be assigned a new JID because the original JID for the object is
currently assigned to the original object that was renamed or moved to a
different library.</li>
</ul>
</li>
</ul>
<p>See the <a href="../rzaki/rzakikickoff.htm">Journal management</a> topic for
more information about what object types are associated with the various types
of journal entries.</p>
<h3>Restrictions</h3>
<ul>
<li>The specified journal cannot be a remote journal.</li>
</ul>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Journal Authority</em></dt>
<dd>*USE, *OBJEXIST</dd>
<dt><em>Journal Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>Currently Attached Receiver Authority</em></dt>
<dd>*USE</dd>
<dt><em>Currently Attached Receiver Library Authority</em></dt>
<dd>*EXECUTE</dd>
<dt><em>Journal Lock</em></dt>
<dd>*SHRRD</dd>
</dl>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The receiver variable that is to receive the information requested. You can
specify the size of the area smaller than the format requested as long as you
specify the length of receiver variable parameter correctly. As a result, the
API returns only the data the area can hold.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable. The length must be at least 8 bytes. If
the variable is not long enough to hold the information, the data is truncated.
If the length is larger than the size of the receiver variable, the results
beyond the length of the largest format are not predictable.</p>
</dd>
<dt><strong>Qualified journal name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The name of the journal that is to be used when retrieving the JID
information and the library in which it resides. The first 10 characters
contain the journal name and the second 10 characters contain the library name.
The special values supported for the library name are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">Library list</td>
</tr>
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">Current library</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Journal identifier (JID) value</strong></dt>
<dd>INPUT; CHAR(10)
<p>The journal identifier (JID) value that is to be used for the retrieve
operation. Information will be retrieved based on this JID value.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format name RJID0100 is the only valid format name used bythis API. For
more information, see <a href="#HDRJIDIFMT">RJID0100 Format</a>.</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>.</p>
</dd>
</dl>
<h3><a name="HDRJIDIFMT">RJID0100 Format</a></h3>
<p>The structure of the information returned is determined by the specified
format name. For detailed descriptions of the fields, see <a href=
"#HDRJIDIFLD">Field Descriptions</a>.</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%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Bytes returned</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Journal name</td>
</tr>
<tr>
<td align="center" valign="top">18</td>
<td align="center" valign="top">12</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Journal library name</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Journal identifier (JID) value</td>
</tr>
<tr>
<td align="center" valign="top">38</td>
<td align="center" valign="top">26</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Object name</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Object library name</td>
</tr>
<tr>
<td align="center" valign="top">58</td>
<td align="center" valign="top">3A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Member name</td>
</tr>
<tr>
<td align="center" valign="top">68</td>
<td align="center" valign="top">44</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Object type</td>
</tr>
<tr>
<td align="center" valign="top">78</td>
<td align="center" valign="top">4E</td>
<td align="left" valign="top">CHAR(16)</td>
<td align="left" valign="top">Object file identifier</td>
</tr>
</table>
<h3><a name="HDRJIDIFLD">Field Descriptions</a></h3>
<p><strong>Bytes available.</strong> The number of bytes of data available to
be returned. All available data is returned if enough space is provided.</p>
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
<p><strong>Journal identifier (JID) value.</strong> The JID value used to
retrieve the object name, object library name, member name, and object
type.</p>
<p><strong>Journal library name.</strong> The name of the library for the
journal. If *LIBL or *CURLIB was specified as input, then this field will
contain the actual library name for the journal.</p>
<p><strong>Journal name.</strong> The name of the journal.</p>
<p><strong>Member name.</strong> If the object type is *QDDS or *QDDSI, then
this field contains the member name. Otherwise, this field is returned as
blanks.</p>
<p><strong>Object file identifier.</strong> The file identifier of the object
associated with the specified JID value. If the object name could not be
retrieved for the specified JID value, then this field is returned as blanks.
File identifiers are unique identifiers associated with integrated file system
related objects.</p>
<p>If the object type is not *DIR, *STMF, or *SYMLNK, then this field is
returned as blanks.</p>
<p><strong>Object library name.</strong> The name of the library for the object
associated with the specified JID value. If the object name could not be
retrieved for the specified JID value, then this field is returned as
blanks.</p>
<p>If the object type is *DIR, *STMF, or *SYMLNK, then this field is returned
as blanks.</p>
<p><strong>Object name.</strong> The name of the object associated with the
specified JID value. If the object name could not be retrieved for the
specified JID value, then this field is returned as blanks.</p>
<p>If the object type is *DIR, *STMF, or *SYMLNK, then this field is returned
as blanks.</p>
<p><strong>Object type.</strong> The type of the object associated with the
specified JID value. If the object name could not be retrieved for the
specified JID value, then this field is returned as blanks. The following lists
the valid object types that can be retrieved for a specified JID value:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*DIR</em></td>
<td align="left" valign="top">Integrated file system directory</td>
</tr>
<tr>
<td align="left" valign="top"><em>*DTAARA</em></td>
<td align="left" valign="top">Data area</td>
</tr>
<tr>
<td align="left" valign="top"><em>*DTAQ</em></td>
<td align="left" valign="top">Data queue</td>
</tr>
<tr>
<td align="left" valign="top"><em>*FILE</em></td>
<td align="left" valign="top">Data base file</td>
</tr>
<tr>
<td align="left" valign="top"><em>*JRNRCV</em></td>
<td align="left" valign="top">Journal receiver</td>
</tr>
<tr>
<td align="left" valign="top"><em>*QDDS</em></td>
<td align="left" valign="top">Data portion of a database member</td>
</tr>
<tr>
<td align="left" valign="top"><em>*QDDSI</em></td>
<td align="left" valign="top">Access path for a database member</td>
</tr>
<tr>
<td align="left" valign="top"><em>*STMF</em></td>
<td align="left" valign="top">Integrated file system byte stream file</td>
</tr>
<tr>
<td align="left" valign="top"><em>*SYMLNK</em></td>
<td align="left" valign="top">Integrated file system symbolic link</td>
</tr>
</table>
<h3>Error Messages</h3>
<table width="100%" cellpadding="3">
<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">CPF3C24 E</td>
<td valign="top">Length of the receiver variable is not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C90 E</td>
<td valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td valign="top">CPF6958 E</td>
<td valign="top">No attached receiver can be used.</td>
</tr>
<tr>
<td valign="top">CPF701B E</td>
<td valign="top">Journal recovery of interrupted operation failed.</td>
</tr>
<tr>
<td valign="top">CPF705A E</td>
<td valign="top">Operation failed due to remote journal.</td>
</tr>
<tr>
<td valign="top">CPF708D E</td>
<td valign="top">Journal receiver found logically damaged.</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">CPF9825 E</td>
<td valign="top">Not authorized to device &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: V3R1
<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>