1075 lines
33 KiB
HTML
1075 lines
33 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>Start Journal (QjoStartJournal) 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. -->
|
|
<!-- QJOSJOBJ SCR510 A converted by B2H R4.1 (346) (CMS) by V2CDIJAB -->
|
|
<!-- at RCHVMW2 on 6 Nov 2000 at 09:42:57 -->
|
|
<!-- Change history -->
|
|
<!-- 030531 v5r3 mel clarified 250,000 object limit -->
|
|
<!-- 040614 v5r4 akf corrected &path name to just &path in example -->
|
|
<!-- 040812 V5R4 MEL D99794 Strjrn restriction for virtual tape -->
|
|
<!--File Edited by 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>Start Journal (QjoStartJournal) API</h2>
|
|
|
|
<div class="box" style="width: 65%;">
|
|
<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%">Object entry array</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">2</td>
|
|
<td align="left" valign="top">File ID entry array</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">Journal</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Omissible Parameter Group:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">4</td>
|
|
<td align="left" valign="top" width="50%">Start journal options</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">5</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>
|
|
Service Program Name: QJOURNAL<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Start Journal (QjoStartJournal) API is used to start journaling changes
|
|
(made to an object or list of objects) to a specific journal. The object types
|
|
that are supported through this API are Data Areas (*DTAARA), Data Queues
|
|
(*DTAQ), Byte Stream Files (*STMF), Directories (*DIR), and Symbolic Links
|
|
(*SYMLNK). For objects of type *STMF, *DIR, or *SYMLNK, only objects in the
|
|
"root" (/), QOpenSys, and user-defined file systems are supported. For more
|
|
information about the possible journal entries that can be sent, see the <a
|
|
href="../rzaki/rzakikickoff.htm">Journal management</a> topic.</p>
|
|
|
|
<p>After journaling begins for the object, the user should save the journaled
|
|
objects. The objects must be saved because, for example, journaled changes
|
|
cannot be applied to a version of the object that was saved before journaling
|
|
was in effect.</p>
|
|
|
|
<p><strong>Note:</strong> For other ways to start journaling, see the following
|
|
commands in the <a href="../rbam6/rbam6clmain.htm">Control Language
|
|
(CL)</a> information:</p>
|
|
|
|
<ul>
|
|
<li>Integrated File System objects - <a href="../cl/strjrn.htm">Start Journal
|
|
(STRJRN)</a></li>
|
|
|
|
<li>Access Paths - <a href="../cl/strjrnap.htm">Start Journal Access Path
|
|
(STRJRNAP)</a></li>
|
|
|
|
<li>Data Areas and Data Queues - <a href="../cl/strjrnobj.htm">Start Journal
|
|
Object (STRJRNOBJ)</a></li>
|
|
|
|
<li>Physical Files - <a href="../cl/strjrnpf.htm">Start Journal Physical File
|
|
(STRJRNPF)</a></li>
|
|
</ul>
|
|
|
|
<p><strong>Restrictions:</strong></p>
|
|
|
|
<ol>
|
|
<li>The object must not be journaling changes to another journal.</li>
|
|
|
|
<li>The maximum number of objects that can be associated with one journal is
|
|
250,000 or 10,000,000. To get 10,000,000, the value of *MAX10M must have been
|
|
specified for the JRNOBJLMT parameter on either the Create Journal (CRTJRN)
|
|
command or on the Change Journal (CHGJRN) command. This maximum number
|
|
includes objects whose changes are currently being
|
|
journaled, objects for which journaling was ended while the current
|
|
receiver was attached, and journal receivers that were associated with the
|
|
journal while the current receiver was attached. If the number of
|
|
objects is larger than this maximum number, journaling does not start.</li>
|
|
|
|
<li>The specified journal must be a local journal. Although all object types
|
|
which can be journaled to a local journal can also have their changes sent to
|
|
a remote journal, this is accomplished by a two step process. First start
|
|
journaling to the local journal. Then connect the local journal to a remote
|
|
instance. To initiate such a connection, use the
|
|
<a href="../cl/addrmtjrn.htm">Add Remote Journal (ADDRMTJRN)</a>
|
|
command or the <a href="QJOADDRJ.htm">Add Remote Journal
|
|
(QjoAddRemoteJournal) API</a>. For information
|
|
about remote journaling, see the <a href="../rzaki/rzakikickoff.htm">Journal
|
|
management</a> topic.
|
|
</li>
|
|
|
|
<li>The specified journal and object must reside in the same Auxiliary Storage
|
|
Pool (ASP).</li>
|
|
|
|
<li>
|
|
Byte stream files that are currently memory mapped,
|
|
<img src="delta.gif" alt="Start of change">
|
|
are virtual volume files,
|
|
<img src="deltaend.gif" alt="End of change">
|
|
or are being used as IXS network storage spaces cannot be journaled.</li>
|
|
|
|
<li>Objects that are internally marked as not eligible for journaling cannot
|
|
be journaled. The system may mark system working directories that are created
|
|
inside of user directories as not eligible for journaling.
|
|
</li>
|
|
|
|
<li>For data areas, only local external data area objects may be journaled. The
|
|
special data areas (*LDA, *GDA, *PDA) and DDM data areas cannot be
|
|
journaled.</li>
|
|
|
|
<li>For data queues, only local data queues are supported. DDM data queues
|
|
cannot be journaled.</li>
|
|
|
|
<li>At least one of parameter object entry or file ID entry must not be
|
|
NULL.</li>
|
|
</ol>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<dl>
|
|
<dt><em>Journal Authority</em></dt>
|
|
|
|
<dd>*OBJOPR, *OBJMGT<br>
|
|
</dd>
|
|
|
|
<dt><em>Non-IFS Object Authority (if specified)</em></dt>
|
|
|
|
<dd>*OBJOPR, *READ, *OBJMGT<br>
|
|
</dd>
|
|
|
|
<dt><em>IFS Object Authority (if specified)</em></dt>
|
|
|
|
<dd>*R, *OBJMGT (also *X if object is a directory and *ALL is specified for the
|
|
directory subtree key)</dd>
|
|
|
|
<dt><em>Directory Authority (for each directory preceding the last component in
|
|
the path name)</em></dt>
|
|
|
|
<dd>*X</dd>
|
|
|
|
<dt><em>Journal Lock</em></dt>
|
|
|
|
<dd>*SHRUPD<br>
|
|
</dd>
|
|
|
|
<dt><em>Non-IFS Object Lock (if specified)</em></dt>
|
|
|
|
<dd>*SHRUPD</dd>
|
|
|
|
<dt><em>IFS Object Lock (if specified)</em></dt>
|
|
|
|
<dd>O_RDONLY | O_SHARE_RDWR</dd>
|
|
</dl>
|
|
|
|
<h3>Required Parameters</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Object entry array</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>The path name of the object for which changes are to be journaled.</p>
|
|
|
|
<p>If this parameter is NULL, the file ID entry must not be NULL.</p>
|
|
|
|
<p>The object entry must be in the following format.</p>
|
|
|
|
<p><strong>Object Entry Format</strong></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%">Number in array</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">CHAR(12)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="4"><strong>Note:</strong>These fields
|
|
repeat for each object path name.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">16</td>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of this object path name entry</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">Include or omit</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">30</td>
|
|
<td align="center" valign="top">1E</td>
|
|
<td align="left" valign="top">CHAR(2)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="left" valign="top">PTR(16)</td>
|
|
<td align="left" valign="top">Pointer to an object path name</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Number in array.</strong> The number of objects in the object entry
|
|
array. The possible values are 1 through 300.</p>
|
|
|
|
<p><strong>Length of this object path name entry.</strong> The length of the
|
|
current object path name entry that can be used as the displacement from the
|
|
start of this path name entry to the next path name entry. The length must be a
|
|
minimum of 32 bytes and must be a multiple of 16.</p>
|
|
|
|
<p><strong>Include or omit.</strong> Whether the path name is included or
|
|
omitted from the start journal operation.</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*INCLUDE</em></td>
|
|
<td align="left" valign="top">Objects that match the object name path are to be
|
|
journaled, unless overridden by an *OMIT specification.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*OMIT</em></td>
|
|
<td align="left" valign="top">Objects that match the object name path are not
|
|
to be journaled. This overrides any *INCLUDE specification and is intended to
|
|
be used to omit a subset of a previously selected path.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Pointer to an object path name.</strong> A pointer to the object
|
|
path name for which changes are to be journaled. All relative path names are
|
|
relative to the current directory at the time of the call to
|
|
QjoStartJournal.</p>
|
|
|
|
<p>In the last component of the path name, an asterisk (*) or a question mark
|
|
(?) can be used to search for patterns of names. The * tells the system to
|
|
search for names that have any number of characters in the position of the *
|
|
character. The ? tells the system to search for names that have a single
|
|
character in the position of the ? character. Symbolic links within the path
|
|
name will not be followed. If the path name begins with the tilde (~)
|
|
character, then the path is assumed to be relative to the appropriate home
|
|
directory.</p>
|
|
|
|
<p>Additional information about path name patterns is in the
|
|
<a href="../ifs/rzaaxkickoff.htm">Integrated file system</a> information
|
|
in the Files and file systems topic.</p>
|
|
|
|
<p>The pointer given points to a path name structure. If that path name
|
|
structure contains a pointer, it must be 16-byte aligned. If not, unpredictable
|
|
results may occur.</p>
|
|
|
|
<p>For more information on the path name format, see <a href="../apiref/pns.htm">Path
|
|
name format</a>.</p>
|
|
|
|
<p><strong>Reserved.</strong> A reserved field that must be set to hexadecimal
|
|
zeros.</p>
|
|
</dd>
|
|
|
|
<dt><strong>File ID entry array</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>The object file identifiers (FID) for which changes are to be journaled.</p>
|
|
|
|
<p>If this parameter is NULL, the object entry parameter must not be NULL.</p>
|
|
|
|
<p>The structure of this parameter follows.</p>
|
|
|
|
<p><strong>Object Identifier Array Format</strong></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%">Number in array</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">CHAR(12)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="4"><strong>Note:</strong> These fields
|
|
repeat for each file identifier.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">16</td>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="left" valign="top">CHAR(16)</td>
|
|
<td align="left" valign="top">Object file identifier</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Number in array.</strong> The number of objects in the object file
|
|
identifier list. The possible values are 1 through 300.</p>
|
|
|
|
<p><strong>Reserved.</strong> A reserved field that must be set to hexadecimal
|
|
zeros.</p>
|
|
|
|
<p><strong>Object file identifier.</strong> The unique 16-byte file identifier
|
|
(FID) associated with integrated file system related objects.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Journal</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>The path name of the journal that receives the journal entries. All relative
|
|
path names are relative to the current directory at the time of the call to
|
|
QjoStartJournal.</p>
|
|
|
|
<p>If a pointer is specified in the path name of the journal, it must be
|
|
16-byte aligned. If not, unpredictable results may occur.</p>
|
|
|
|
<p>For more information on the journal path name format, see <a href=
|
|
"../apiref/pns.htm">Path name format</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Omissible Parameters</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Start journal options</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>The start journal options, if any, to use for the selection of objects to
|
|
start journaling changes and how those changes should be journaled. If this
|
|
parameter is not specified, objects will be journaled using the default actions
|
|
described in the field descriptions of the valid keys. See <a href=
|
|
"#HDRSJRNEKY">Keys</a> for the list of valid keys.</p>
|
|
|
|
<p>This parameter must be specified, but may be a NULL pointer.</p>
|
|
|
|
<p>You may specify a key more than once. If duplicate keys are specified, the
|
|
last specified value for that key is used.</p>
|
|
|
|
<p>Each option record must be 16-byte aligned. If not, unpredictable results
|
|
may occur.</p>
|
|
|
|
<p>The information must be in the following format:</p>
|
|
|
|
<p><strong>Journal Options Format</strong></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%">Number of option records</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">CHAR(12)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="4"><strong>Note:</strong>These fields
|
|
repeat for each option record.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">16</td>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of option record</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="center" valign="top">14</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Key</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">24</td>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of data</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">28</td>
|
|
<td align="center" valign="top">1C</td>
|
|
<td align="left" valign="top">CHAR(4)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Data</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Number of option records.</strong> The total number of all option
|
|
records. If this field is zero, an error will be returned.</p>
|
|
|
|
<p><strong>Length of option record.</strong> The length of the option record.
|
|
This length is used to calculate the starting position of the next option
|
|
record. If you specify a length of option record that is not equal to the key
|
|
field's required option record length, an error message will be returned.</p>
|
|
|
|
<p><strong>Key.</strong> Specific action for start journal. See <a href=
|
|
"#HDRSJRNEKY">Keys</a> for the list of valid keys.</p>
|
|
|
|
<p><strong>Length of data.</strong> The length of the option record. This
|
|
length is used to calculate the ending position of the data for this
|
|
option.</p>
|
|
|
|
<p>If you specify a length of data that is not equal to the key field's
|
|
required data length, an error message will be returned.</p>
|
|
|
|
<p><strong>Reserved.</strong> A reserved field that must be set to hexadecimal
|
|
zeros.</p>
|
|
|
|
<p><strong>Data.</strong> The data that is used to determine the journal
|
|
option. All values are validity checked.</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="HDRSJRNEKY">Keys</a></h3>
|
|
|
|
<p>The following table lists the valid keys for the key field area of the
|
|
journal options record. For detailed descriptions of the keys, see the <a href=
|
|
"#HDRSTJRNE2">Field Descriptions</a>.</p>
|
|
|
|
<p>Some messages for this API refer to parameters and values for the <a href=
|
|
"../cl/strjrn.htm">Start Journal</a> (STRJRN) command. This table also can be
|
|
used to locate the key names that correspond to the STRJRN command
|
|
parameters.</p>
|
|
|
|
<table border>
|
|
<tr>
|
|
<th align="center" valign="bottom">Key</th>
|
|
<th align="left" valign="bottom">Input Type</th>
|
|
<th align="left" valign="bottom">Field</th>
|
|
<th align="center" valign="bottom">Length of<br>
|
|
Option<br>
|
|
Record</th>
|
|
<th align="center" valign="bottom">Length<br>
|
|
of Data</th>
|
|
<th align="left" valign="bottom">STRJRN Command Parameter</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">1</td>
|
|
<td align="left" valign="top" width="20%">CHAR(5)</td>
|
|
<td align="left" valign="top" width="20%">Directory Subtree</td>
|
|
<td align="center" valign="top" width="15%">32</td>
|
|
<td align="center" valign="top" width="15%">5</td>
|
|
<td align="left" valign="top" width="20%">SUBTREE</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">CHAR(48)</td>
|
|
<td align="left" valign="top">Name Pattern</td>
|
|
<td align="center" valign="top">64</td>
|
|
<td align="center" valign="top">48</td>
|
|
<td align="left" valign="top">PATTERN</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">CHAR(4)</td>
|
|
<td align="left" valign="top">New objects inherit journaling</td>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">INHERIT</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">CHAR(7)</td>
|
|
<td align="left" valign="top">Images</td>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="center" valign="top">7</td>
|
|
<td align="left" valign="top">IMAGES</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Omit journal entry</td>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="left" valign="top">OMTJRNE</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRSTJRNE2">Field Descriptions</a></h3>
|
|
|
|
<p><strong>Directory subtree.</strong> Whether the directory subtrees are
|
|
included in the start journal operation. The default is *NONE.</p>
|
|
|
|
<p><strong>Note:</strong> This parameter is ignored if the object entry
|
|
parameter is not specified or if the object is not a directory.</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*NONE</em></td>
|
|
<td align="left" valign="top">Only the objects that match the selection
|
|
criteria are processed. The objects within selected directories are not
|
|
processed implicitly.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*ALL</em></td>
|
|
<td align="left" valign="top">All objects that meet the selection criteria are
|
|
processed in addition to the entire subtree of each directory that matches the
|
|
selection criteria. The subtree includes all subdirectories and the objects
|
|
within those subdirectories.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Name pattern.</strong> The patterns to be used to include or omit
|
|
objects for the start journal operation. The default will be to include all
|
|
patterns that match.</p>
|
|
|
|
<p>Additional information about path name patterns is in the
|
|
<a href="../ifs/rzaaxkickoff.htm">Integrated file system</a> information
|
|
in the Files and file systems topic.</p>
|
|
|
|
<p><strong>Note:</strong> This parameter is ignored if the object entry
|
|
parameter is not specified.</p>
|
|
|
|
<p><strong>Name Pattern Format</strong></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%">Number in array</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">CHAR(12)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" colspan="4"><strong>Note:</strong> These fields
|
|
repeat for each name pattern.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">16</td>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of this pattern entry</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">Include or omit</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">30</td>
|
|
<td align="center" valign="top">1E</td>
|
|
<td align="left" valign="top">CHAR(2)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="left" valign="top">PTR(16)</td>
|
|
<td align="left" valign="top">Pointer to pattern path structure</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Number in array.</strong> The number of patterns in the pattern
|
|
list. The possible values are 1 through 20.</p>
|
|
|
|
<p><strong>Reserved.</strong> A reserved field that must be set to hexadecimal
|
|
zeros.</p>
|
|
|
|
<p><strong>Length of this pattern entry.</strong> The length of this pattern
|
|
entry. It is used to calculate the position of the next pattern entry. This
|
|
must be set to 32.</p>
|
|
|
|
<p><strong>Include or omit.</strong> Whether the name pattern is included or
|
|
omitted from the start journal operation.</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*INCLUDE</em></td>
|
|
<td align="left" valign="top">Objects that match the object name pattern are to
|
|
be journaled, unless overridden by an *OMIT specification.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*OMIT</em></td>
|
|
<td align="left" valign="top">Objects that match the object name pattern are
|
|
not to be journaled. This overrides an *INCLUDE specification and is intended
|
|
to be used to omit a subset of a previously selected pattern.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Pointer to pattern path structure.</strong> A pointer to a path
|
|
structure.</p>
|
|
|
|
<p>This pointer must be 16-byte aligned. If not, unpredictable results may
|
|
occur.</p>
|
|
|
|
<p>For more information on the pattern path name format, see <a href=
|
|
"../apiref/pns.htm">Path name format</a>.</p>
|
|
|
|
<p><strong>New objects inherit journaling.</strong> Whether new objects created
|
|
in an object can inherit the journaling options and the journal state of the
|
|
parent directory. If the new objects inherit journaling parameter is not
|
|
specified, the default will be to not inherit journaling options and the
|
|
journal state of the parent directory.</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*NO</em></td>
|
|
<td align="left" valign="top">New objects created within a directory will not
|
|
inherit the journaling options and journal state of the parent directory.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*YES</em></td>
|
|
<td align="left" valign="top">New objects created within a directory will
|
|
inherit the journaling options and journal state of the parent directory.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Images.</strong> The kinds of images that are written to the journal
|
|
receiver for updates to objects. The value *BOTH is only supported for objects
|
|
of type *DTAARA.</p>
|
|
|
|
<p>If the images parameter is not specified, the default value will be
|
|
*AFTER.</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*AFTER</em></td>
|
|
<td align="left" valign="top">Only <em>after</em> images are generated for
|
|
changes to the objects.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*BOTH</em></td>
|
|
<td align="left" valign="top">The system generates both <em>before</em> and
|
|
<em>after</em> images for changes to the objects.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Omit journal entry.</strong> The journal entries that are omitted.
|
|
This parameter only supports objects of type *STMF, *DIR, or *SYMLNK that are
|
|
in the "root" (/), QOpenSys, and user-defined file systems. If the omit journal
|
|
entry parameter is not specified, the default will be *NONE.</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*NONE</em></td>
|
|
<td align="left" valign="top">No entries are omitted.<br>
|
|
<br>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*OPNCLOSYN</em></td>
|
|
<td align="left" valign="top">Open, close, and force operations on the
|
|
specified objects do not generate open, close, and force journal entries. This
|
|
prevents the use of TOJOBO and TOJOBC entries on the Apply Journal Changes
|
|
(APYJRNCHG) command, but it saves some storage space in the journal
|
|
receivers.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Messages</h3>
|
|
|
|
<p>The following messages may be sent from this API:</p>
|
|
|
|
<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">CPFA0D4 E</td>
|
|
<td width="85%" valign="top">File system error occurred.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF6979 E</td>
|
|
<td valign="top">Journal is unusable.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF700A E</td>
|
|
<td valign="top">&1 of &2 objects started journaling.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF70EF E</td>
|
|
<td valign="top">Parameters cannot be used together.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF705A E</td>
|
|
<td valign="top">Operation failed due to remote journal.</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>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Example</h3>
|
|
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
|
|
for information pertaining to code examples.</p>
|
|
<p>The following example starts journaling a directory object and all objects
|
|
within that directory subtree. Additionally, it starts journaling on another
|
|
object identified by its file ID.</p>
|
|
|
|
<pre>
|
|
#include <string.h>
|
|
#include <qjournal.h>
|
|
|
|
void main()
|
|
{
|
|
Qjo_Object_Entry_Array_t objectEntryArray;
|
|
Qjo_File_ID_Entry_Array_t fileIDEntryArray;
|
|
|
|
struct PathNameStruct
|
|
{
|
|
Qlg_Path_Name_T header;
|
|
char p[50];
|
|
};
|
|
|
|
struct PathNameStruct path;
|
|
struct PathNameStruct journalPath;
|
|
|
|
char pathName[] = "/CustomerData";
|
|
char jrnPathName[] = "/QSYS.LIB/ADMIN.LIB/CUSTDATA.JRN";
|
|
|
|
Qp0lFID_t fileID;
|
|
|
|
struct JournalOptionsStruct
|
|
{
|
|
Qjo_Journal_Options_t opts;
|
|
char spaceForAdditionalOptions[200];
|
|
};
|
|
|
|
struct JournalOptionsStruct journalOptions;
|
|
Qjo_Option_t *optionP;
|
|
|
|
Qus_EC_t errorCode;
|
|
|
|
|
|
/* Setup the object's path name structure. */
|
|
memset(&path, 0, sizeof(path));
|
|
path.header.CCSID = 37;
|
|
memcpy(path.header.Country_ID,"US",2);
|
|
memcpy(path.header.Language_ID,"ENU",3);
|
|
path.header.Path_Type = QLG_CHAR_SINGLE;
|
|
path.header.Path_Length = strlen(pathName);
|
|
path.header.Path_Name_Delimiter[0] = '/';
|
|
memcpy(path.p, pathName, path.header.Path_Length);
|
|
|
|
/* Setup the object entry array. */
|
|
memset(&objectEntryArray,0,sizeof(objectEntryArray));
|
|
objectEntryArray.Number_In_Array = 1;
|
|
|
|
objectEntryArray.Entry[0].Length_Of_Object_Entry =
|
|
sizeof(objectEntryArray.Entry[0]);
|
|
memcpy(objectEntryArray.Entry[0].Include_Or_Omit,
|
|
QJO_INC_ENT_INCLUDE,
|
|
sizeof(objectEntryArray.Entry[0].Include_Or_Omit));
|
|
objectEntryArray.Entry[0].Path_Name =
|
|
(Qlg_Path_Name_T *)&path;
|
|
|
|
/* Get an object's file ID.
|
|
This example is not including the retrieval of the
|
|
file ID for an object. The user can see the
|
|
Qp0lGetAttr API for information on retrieving an
|
|
object's file ID. This example will proceed as if the
|
|
fileID variable is set to a valid file ID. */
|
|
|
|
/* Setup the file ID entry array. */
|
|
memset(&fileIDEntryArray,0,sizeof(fileIDEntryArray));
|
|
fileIDEntryArray.Number_In_Array = 1;
|
|
memcpy(&fileIDEntryArray.Entry,
|
|
fileID,
|
|
sizeof(fileIDEntryArray.Entry));
|
|
|
|
|
|
/* Setup the journal's path name structure. */
|
|
memset(&journalPath, 0, sizeof(journalPath));
|
|
journalPath.header.CCSID = 37;
|
|
memcpy(journalPath.header.Country_ID,"US",2);
|
|
memcpy(journalPath.header.Language_ID,"ENU",3);
|
|
journalPath.header.Path_Type = QLG_CHAR_SINGLE;
|
|
journalPath.header.Path_Length = strlen(jrnPathName);
|
|
journalPath.header.Path_Name_Delimiter[0] = '/';
|
|
memcpy(journalPath.p,
|
|
jrnPathName,
|
|
journalPath.header.Path_Length);
|
|
|
|
/* Set the journal options. */
|
|
memset(&journalOptions,0,sizeof(journalOptions));
|
|
journalOptions.opts.Number_Of_Options = 3;
|
|
|
|
/* Set the *AFTER images key. */
|
|
optionP = (Qjo_Option_t *)&journalOptions.opts.Option[0];
|
|
|
|
optionP->Length_Of_Record = QJO_KEY_MINIMUM_RECORD_LENGTH;
|
|
optionP->Key = QJO_KEY_IMAGES;
|
|
optionP->Length_Of_Data = QJO_KEY_IMAGES_LENGTH;
|
|
memcpy(optionP->Data,
|
|
QJO_IMAGES_AFTER,
|
|
QJO_KEY_IMAGES_LENGTH);
|
|
|
|
/* Set the inherit directory journaling attributes key. */
|
|
optionP = (Qjo_Option_t *)((char *)optionP +
|
|
optionP->Length_Of_Record);
|
|
|
|
optionP->Length_Of_Record = QJO_KEY_MINIMUM_RECORD_LENGTH;
|
|
optionP->Key = QJO_KEY_INHERIT;
|
|
optionP->Length_Of_Data = QJO_KEY_INHERIT_LENGTH;
|
|
memcpy(optionP->Data,
|
|
QJO_INHERIT_YES,
|
|
QJO_KEY_INHERIT_LENGTH);
|
|
|
|
/* Set the subtree processing images key. */
|
|
optionP = (Qjo_Option_t *)((char *)optionP +
|
|
optionP->Length_Of_Record);
|
|
|
|
optionP->Length_Of_Record = QJO_KEY_MINIMUM_RECORD_LENGTH;
|
|
optionP->Key = QJO_KEY_SUBTREE;
|
|
optionP->Length_Of_Data = QJO_KEY_SUBTREE_LENGTH;
|
|
memcpy(optionP->Data,
|
|
QJO_SUBTREE_ALL,
|
|
QJO_KEY_SUBTREE_LENGTH);
|
|
|
|
/* Setup the error code structure to cause an exception
|
|
to be sent upon error. */
|
|
memset(&errorCode,0,sizeof(errorCode));
|
|
errorCode.Bytes_Provided = 0;
|
|
|
|
QjoStartJournal(&objectEntryArray,
|
|
&fileIDEntryArray,
|
|
(Qlg_Path_Name_T *)&journalPath,
|
|
(Qjo_Journal_Options_t *)&journalOptions,
|
|
&errorCode);
|
|
}
|
|
</pre>
|
|
|
|
<br>
|
|
<hr>
|
|
API introduced: V5R1
|
|
|
|
<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>
|
|
|