620 lines
18 KiB
HTML
620 lines
18 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>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>
|
|
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>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
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 &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 &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">CPF9825 E</td>
|
|
<td valign="top">Not authorized to device &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: 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>
|
|
|