friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qp0lrro.htm

1166 lines
41 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- saved from url=(0072)https://w3.rchland.ibm.com/projects/api-cl/api/templates/iletemplate.htm -->
<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 Referenced Objects (QP0LRRO) 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. -->
<!-- file cleaned -->
<!-- Created by Dale Erickson for V5R3 -->
<!-- Change History: -->
<!-- 020328 ericksd: New document -->
<!-- 030326 JTROUS: Fix up cross links etc -->
<!-- 030612 ericksd: Fix up example program. -->
<!-- 031024 VONBERGE: Make example program compile. Minor wording-->
<!-- fixups. -->
<!-- 040106 VONBERGE: Correct pathname description for XPF -->
<!-- PTR 9A48021. -->
<!-- 050503 VONBERGE: Change threadsafety to No -->
<!--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 Referenced Objects
(QP0LRRO) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;qp0lrro.h&gt;
void QP0LRRO(
void * Receiver_Variable,
unsigned int Length_Of_Receiver_Variable,
char * Receiver_Format_Name,
void * Job_Identification,
char * Job_Identification_Format,
void * Error_Code
);
</pre>
&nbsp;&nbsp; Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
<img src="delta.gif" alt="Start of change">
&nbsp;&nbsp;Threadsafe: No
<img src="deltaend.gif" alt="End of change">
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>QP0LRRO()</strong> API is used to retrieve information
about integrated file system objects that are currently referenced by a
specific job.</p>
<p>A reference is an individual type of access or lock obtained on the object
when using integrated file system interfaces. An object may have multiple
references concurrently held, provided that the reference types do not conflict
with one another.</p>
<p>This API will not return information about byte range locks that may
currently be held on an object.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>Receiver_Variable</strong></dt>
<dd>(Output)
<p>The variable that is to receive the information requested. You can specify
the size of this area to be smaller than the format requested as long as you
specify the length parameter correctly. As a result, the API will return only
complete records that the area can hold. A complete record is defined as the
object list output structure (Qp0l_PObj_List_Output_T) along with the extended
reference types, the Qlg_Path_Name_T structure and path of the object if it can
be returned.</p>
<p>The format of the output is described by the RROO0100 output format.
See <a href="#objref2">RROO0100 Output Format Description</a> for a detailed
description of these output formats.</p>
</dd>
<dt><strong>Length_Of_Receiver_Variable</strong></dt>
<dd>(Input)
<p>The length of the receiver variable. If the length specified is larger than the
size allocated for the receiver variable, the results may not be predictable. The minimum
length is 8 bytes.</p>
</dd>
<dt><strong>Receiver_Format_Name</strong></dt>
<dd>(Input)
<p>Pointer to an 8-byte character string that identifies the desired output format.
It must be one of the following values.</p>
<dl>
<dt><em>RROO0100</em></dt>
<dd>The reference type output will be formatted in the RROO0100 output format. See
<a href="#objref2">RROO0100 Output Format Description</a> for a detailed
description of this output format.<br>
<br>
</dd>
</dl>
</dd>
<dt><strong>Job_Identification</strong></dt>
<dd>(Input)
<p>Pointer to the structure that is used to identify the job or thread for
which the integrated file system objects
are referenced. See the various job formats available in the
<a href="qwcrjblk.htm">Retrieve Job Locks (QWCRJBLK) API</a>
for a detailed description of this input format.</p>
</dd>
<dt><strong>Job_Identification_Format</strong></dt>
<dd>(Input)
<p>Pointer to an 8-byte character string that is used to identify the format of the job or thread identification
information.
The format name must be one of the following values.</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>JIDF0100</em></td>
<td align="left" valign="top">This format is used to retrieve the references that a
job and threads are holding. See
<a href="qwcrjblk.htm#JIDF0100">JIDF0100 Format</a> in
<a href="qwcrjblk.htm">Retrieve Job Locks (QWCRJBLK) API</a>
for more information.<br>
<br>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>JIDF0200</em></td>
<td align="left" valign="top">This format is used to retrieve the references that a
specific thread is holding. See
<a href="qwcrjblk.htm#JIDF0200">JIDF0200 Format</a> in
<a href="qwcrjblk.htm">Retrieve Job Locks (QWCRJBLK) API</a>
for more information.</td>
</tr>
</table>
<p>Note: The Internal Job Identifier within job formats JIDF0100 and JIDF0200 is not supported by QP0LRRO at this time. If the internal job identifier is specified, CPE3440 (Operation not supported) will be returned in the error code structure.</p>
<p>This API is thread independent. This means QP0LRRO returns references for integrated file system objects for all threads within a specified job. Therefore the thread indicator fields in the job format structures will be ignored.</p>
</dd>
<dt><strong>Error_Code</strong></dt>
<dd>(Input/Output)
<p>Pointer to an error code structure to receive error information. See <a
href="../apiref/error.htm#hdrerrcod">Error code parameter</a> for more information.</p>
</dd>
</dl>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Job Authority</em></dt>
<dd>The job authority must be one of the following:
<ol type="1">
<li>The API must be called from within the job for which the information is
being retrieved.</li>
<li>The caller of the API must be running under a user profile
that is the same as the job user identity of the job for which the information
is being retrieved.</li>
<li>The caller of the API must be running under a user profile that
has job control (*JOBCTL) special authority.</li>
</ol>
<p>The <strong>job user identity</strong> is the name of the user profile by
which a job is known to other jobs. It is described in more detail in the
<a href="../rzaks/rzaks1.htm">Work Management</a> topic.</p>
</dd>
</dl>
<br>
<h3><a name="structureheader">Input Structure Formats</a></h3>
<p>The input structure formats are used to input job or thread information.
for a detailed description of this input format. See
<a href="qwcrjblk.htm#JIDF0100">JIDF0100 Format</a> and
<a href="qwcrjblk.htm#JIDF0200">JIDF0200 Format</a> in
<a href="qwcrjblk.htm">Retrieve Job Locks (QWCRJBLK) API</a>.</p>
<br>
<br>
<h3><a name="structureheader">Output Structure Formats</a></h3>
<h4><a name="objref2">RROO0100 Output Format Description
(<em>Qp0l_RROO0100_Output_T</em>)</a></h4>
<p>This output format is used to return integrated file system objects that
have been referenced by a specific job.</p>
<table border width="100%">
<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="30%">BINARY(4), UNSIGNED</td>
<td align="left" valign="top" width="50%">Bytes returned</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">4</td>
<td align="center" valign="top" width="10%">4</td>
<td align="left" valign="top" width="30%">BINARY(4), UNSIGNED</td>
<td align="left" valign="top" width="50%">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Objects returned count</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">0C</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Objects available count</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Offset to objects list output structure</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Retrieve referenced object status</td>
</tr>
<tr>
<td align="left" valign="top" colspan="2">Offset determined from <em>Offset to
objects list output structure</em> field</td>
<td align="left" valign="top">Qp0l_Obj_List_Output Structure</td>
<td align="left" valign="top">Objects list output structure. See <a href=
"#objref3">Objects List Output Structure Description</a>
for a description of this structure. The Objects List Output structure is repeated
for each integrated file system object referenced by the job.</td>
</tr>
</table>
<br>
<br>
<h4><a name="objref3">Objects List Output Structure Description
(<em>Qp0l_Obj_List_Output_T</em>)</a></h4>
<p>This structure is embedded within the RROO0100 format. It is used to return
the list of integrated file system objects that have been referenced by a
specific job. This structure is repeated for each integrated file system object
referenced by the job.</p>
<table border width="100%">
<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="30%">BINARY(4), UNSIGNED</td>
<td align="left" valign="top" width="50%">Displacement to next object list output structure</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Displacement to extended reference types</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Length of extended reference types</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">0C</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Reference count</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Displacement to Qlg_Path_Name_T structure</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Length of Qlg_Path_Name_T structure</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">CHAR(16)</td>
<td align="left" valign="top">File identifier.</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">BINARY(8), UNSIGNED</td>
<td align="left" valign="top">File system identifier.</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">File system type.</td>
</tr>
<tr>
<td align="center" valign="top">52</td>
<td align="center" valign="top">34</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">File identifier number.</td>
</tr>
<tr>
<td align="center" valign="top">56</td>
<td align="center" valign="top">38</td>
<td align="left" valign="top">BINARY(4), UNSIGNED</td>
<td align="left" valign="top">Generation identifier.</td>
</tr>
<tr>
<td align="left" valign="top" colspan="2">Offset determined from <em>Displacement to
extended reference types</em> field</td>
<td align="left" valign="top">Qp0l_ExtRef_Types_Output_T Structure</td>
<td align="left" valign="top">Extended reference types structure. See <a href=
"#ObjTypesStruct">Extended object reference types structure description</a>
for a description of this structure.</td>
</tr>
<tr>
<td align="left" valign="top" colspan="2">Offset determined from <em>Displacement to
Qlg_Path_Name_T structure</em> field</td>
<td align="left" valign="top">Qlg_Path_Name_T Structure</td>
<td align="left" valign="top">Qlg path name structure. See <a href=
"#PathNameStruct">Qlg Path Name Structure</a>
for a description of this structure.</td>
</tr>
</table>
<br>
<br>
<h4><a name="PathNameStruct">Qlg Path Name Structure
Description (<em>Qlg_Path_Name_T</em>)</a></h4>
<p>This structure is embedded within the RROO0100 format.
It is an NLS-enabled Qlg_Path_Name_T format structure that contains a path name or
pointer to a path name of an integrated file system object that is referenced
by the job. For more information on the Qlg_Path_Name_T structure,
see <a href="../apiref/pns.htm">Path name format.</a></p>
<p>Some integrated file system objects may have multiple links. In this case the QP0LRRO API will only return a single path name to the object.</p>
<p>If the last element of the <em>path</em> is a symbolic link, QP0LRRO
does not resolve the contents of the symbolic link.
The reference information will be obtained for the symbolic link itself.</p>
<p><img src="v5r4adelta.gif" alt="Start of change">
The Qlg_Path_Name_T structure will have a path length of zero (0) if no path name was available to be returned.
A path name may not be returned under the following conditions:</p>
<ul>
<li>
The object is in the "root" (/), QOpenSys or a user-defined file system and is not linked to a directory path.</li>
<li>
The object is in a remote file system or the optical file system (QOPT).</li>
<img alt="End of change" src="v5r4adeltaend.gif">
</ul>
<h4><a name="ObjTypesStruct">Extended Object Reference Types Structure
Description (<em>Qp0l_Ext_Ref_Types_Output</em>)</a></h4>
<p>This structure is embedded within the RROO0100 format. It is used to return
object reference type information.</p>
<p>The Qp0l_Ext_Ref_Types_Output contains the references for the returned
object contained in the Qlg_Path_Name_T structure. For more information on the
Qp0l_Ext_Ref_Types_Output_T structure see
<a href="qp0lror.htm#ObjTypesStruct">Extended object reference types structure description</a> in
<a href="qp0lror.htm">Retrieve Object References (QP0LROR)</a> API.</p>
<br>
<br>
<h3><a name="rrooutfields">Field Descriptions for RROO0100 Output Structure and the
embedded structures</a></h3>
<p><strong>Bytes available.</strong> Number of bytes of output data that was
available to be returned.</p>
<p><strong>Bytes returned.</strong> Number of bytes returned in the output
buffer.</p>
<p><strong>Displacement to extended reference types.</strong> Displacement from
the beginning of the Objects list output structure containing this field to the
beginning of the Extended reference types structure.</p>
<p><strong>Displacement to next Object list output structure.</strong> Displacement from
the beginning of Object list output structure to the beginning of the next
Object list output structure. If this field is 0, then there are no more Object list output
structures available to be returned, or not enough space was provided to complete the next Object list output structure.</p>
<p><strong>Displacement to Qlg_Path_Name_T structure.</strong> Displacement from
the beginning of the Object list output structure containing this field to the beginning of the
Qlg_Path_Name_T structure. </p>
<p><strong>Extended reference types structure.</strong> This is a
Qp0l_Ext_Ref_Types_Output_T structure containing fields that indicate different
types of references that may be held on an object. For more information on the
Qp0l_Ext_Ref_Types_Output_T structure see <a href="qp0lror.htm#ObjTypesStruct">Extended object reference types structure description</a> in
<a href="qp0lror.htm">Retrieve Object References (QP0LROR)</a> API.</p>
<p><strong>File identifier.</strong> An identifier
associated with the referred to object. A file ID can be used with <a href=
"getpthff.htm">Qp0lGetPathFromFileID()</a> to retrieve an object's path name from
some file systems.
The file identifier is defined in header file Qp0lstdi.h as data type Qp0lFID_t.</p>
<p><strong>File identifier number.</strong> The file identifier number of the object. This
number uniquely identifies the object within a file system. When the file identifier number, generation identifier and file system identifier are used together, they uniquely identify the object on the system.</p>
<p><strong>File system identifier.</strong> The file system ID to which the object belongs.
This number uniquely identifies the file system to which the object belongs.
When the file identifier number, generation identifier and file system identifier are used together, they uniquely identify the object on the system. </p>
<p><strong>File system type.</strong> An integer representation of the file system the object belongs. The file system type may be one of the following values. </p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">QP0L_ROOT_FS: The "root" (/) file system </td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">QP0L_QOPENSYS_FS: The QOpenSys file system. </td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">QP0L_UDFS_FS: A user-defined file system. </td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">QP0L_UDFS_MANAGEMENT_FS: A file system that manages the block special files (*BLKSF) for the user-defined file systems. </td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">QP0L_QSYS_FS: The QSYS.LIB file system. </td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td align="left" valign="top">QP0L_IASPQSYS_FS: An independent ASP QSYS.LIB file system. </td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td align="left" valign="top">QP0L_QDLS_FS: The QDLS file system. </td>
</tr>
<tr>
<td align="left" valign="top"><em>7</em></td>
<td align="left" valign="top">QP0L_NFS_FS: The Network File System (NFS). </td>
</tr>
<tr>
<td align="left" valign="top"><em>8</em></td>
<td align="left" valign="top">QP0L_QNETWARE_FS: The QNetWare file system. </td>
</tr>
<tr>
<td align="left" valign="top"><em>9</em></td>
<td align="left" valign="top">QP0L_QOPT_FS: The optical file system (QOPT). </td>
</tr>
<tr>
<td align="left" valign="top"><em>10</em></td>
<td align="left" valign="top">QP0L_QFILSVR400_FS: The QFileSvr.400 file system. </td>
</tr>
<tr>
<td align="left" valign="top"><em>11</em></td>
<td align="left" valign="top">QP0L_QNTC_FS: The Windows NT Server file system. </td>
</tr>
</table>
<p><strong>Generation identifier.</strong> The generation identifier associated with the
object. When the file identifier number, generation identifier and file system identifier are used together, they uniquely identify the object on the system.</p>
<p><strong>Length of extended reference types.</strong> Length of the Extended
reference types information.</p>
<p><strong>Length of Qlg_Path_Name structure.</strong> Length of the Qlg_Path_Name
structure.</p>
<p><strong>Objects returned count.</strong> The number of integrated file system objects that are returned in the Objects list output structure. The number of objects returned is limited by the amount of space allocated to receive the list of objects.</p>
<p><strong>Objects available count.</strong> The number of integrated file system objects that are available to be returned in the Objects list output structure. This value may be larger than the value in the Objects returned count.</p>
<p><strong>Offset to objects list output structure.</strong> Offset from the
beginning of the <em>Receiver_Variable</em> to the beginning of the Objects list output
structure. If this field is 0, then no integrated file system
objects were available to be returned, or not enough space was provided to complete an
Objects list output structure.</p>
<p><strong>Qlg Path Name structure.</strong> An NLS enabled Qlg_Path_Name_T format structure that
contains a path name of an integrated file system object that is referenced by the job.</p>
<p><strong>Reference count.</strong> Current number of references on the
object for the specified job. </p>
<p><strong>Retrieve referenced object status.</strong> An integer space to return potential error conditions back to the caller that may have been ignored by the QP0LRRO() API. The following feedback conditions may be returned (NOTE: If non-zero, this condition value may indicate more than one error condition):</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>0x00000000 (Hex)</em></td>
<td align="left" valign="top">QP0L_NO_ERROR: No errors were encountered that were ignored
by QP0LRRO API.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0x00000001 (Hex)</em></td>
<td align="left" valign="top">QP0L_ERROR: An error was encountered while retrieving
referenced objects. Not all referenced objects were returned. The job log will contain a diagnostic message that was sent by the job. </td>
</tr>
<tr>
<td align="left" valign="top"><em>0x00000002 (Hex)</em></td>
<td align="left" valign="top">QP0L_SPACE_ERROR: An error was encountered while trying to allocate space to retrieve all referenced objects. Not all referenced objects were returned. Additionally, the Bytes available value that is returned will not be the correct number of bytes available. Instead, it will contain the maximum number of bytes available that the API was able to determine prior to the space allocation failure. </td>
</tr>
</table>
<br>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top" nowrap>Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPE3440 E</td>
<td align="left" valign="top">Operation not supported.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not correct.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C36 E</td>
<td align="left" valign="top">Number of parameters, &amp;1, entered for this
API was not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C3C E</td>
<td align="left" valign="top">Value for parameter &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C53 E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C55 E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 does not exist.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C57 E</td>
<td align="left" valign="top">Not authorized to retrieve job information.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C59 E</td>
<td align="left" valign="top">Internal identifier is not blanks and job name is not *INT.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1 API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA0D4 E</td>
<td align="left" valign="top">File system error occurred. Error number
&amp;1.</td>
</tr>
</table>
<br>
<h3><a name="usage">Usage Notes</a></h3>
<ol type="1">
<li>The QP0LRRO API will return references for the file systems whose types are
listed above in the <strong>file system type</strong> definition.<br><br>
</li>
<li>The list of objects returned in the RROO0100 output format may be
incomplete for objects residing in file systems other than the "root" (/),
QOpenSys, and user-defined file systems. Objects in some of the other file
systems can be locked with interfaces that do not use the integrated file
system. Therefore, objects referenced by a job will only have references that
were obtained as part of an integrated file system operation, or an operation
that causes an integrated file system operation to occur.<br><br></li>
<li>Jobs using file systems that access remote objects, such as Network File
System (NFS) and the QFileSvr.400 file systems, will only be returning object
references that are locally obtained. Any remote object references held by the
job are not returned by this API.<br><br></li>
<li>Since the output format is variable length, the following is recommended
for obtaining a minimum output buffer size to receive the information:<br><br>
<ul>
<li>RROO0100: Programs may consider first calling QP0LRRO and specifying the
minimum eight bytes for the input Length_Of_Receiver_Variable and assigning a
space of at least eight bytes to the output Receiver_Variable. QP0LRRO will
then return the number of bytes required for this operation in the bytes
available field in output structure RROO0100. The program could then allocate a
buffer equal in size to the returned value in bytes available.
<p>The number of referenced objects for a particular job may change between
multiple calls to this API. Therefore, the output buffer size for a RROO0100
format may not be enough space under all conditions.</p>
</li>
<li>If not enough is space provided to receive a complete list of object
information, then only those object entries that completely fit in the buffer
will be returned. The RROO0100 output structure contains a field called <em>
Object available count</em> that will always contain the total number of
integrated file system objects that were available for returning to the caller
at that instance in time.<br>
<br>
</li>
</ul>
</li>
<li>This API will only capture the object references at an instant in time. By
the time this API has completed and returns to the caller, the reference
information may already be out of date. This behavior is characteristic of this
type of interface.<br><br></li>
<li>There are some reference types that are obtained on an object without
incrementing the object's reference count. This could result in an object not
being returned by this API for a job even though that job is holding a lock on
that object.
<p>For example: At some instances during the save or restore of an integrated
file system object, the job may have references on an object even though its
reference count is zero.</p>
</li>
<li>Under some circumstances, the list of objects that are referenced by a job
may be incomplete. Some system programs obtain object references directly on an
object without obtaining an open descriptor for the object.<br><br>
</li>
<!-- COMMENT out the QDLS statement. We currently aren't going to encounter
this anymore, but keep around in case this changes again.
<li>For jobs referencing the QDLS file system, the jobs user profile must be
enrolled in the system distribution directory. If QDLS file system objects are
referenced by a job and the jobs user profile is not enrolled in the system
distribution directory; those objects will not be returned and message CPE3498
"User not enrolled in system distribution directory." will be returned in the
users job log. The retrieve referenced object status filed will also be set to
QP0L_ERROR.<br><br>
</li>
-->
<li>This type of reference information can also be viewed through the iSeries
Navigator application. The terminology, however, differs in that iSeries
Navigator refers to this type of information as "Usage" information instead of
"Reference" information.</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The <strong>&lt;qp0lrro.h&gt;</strong> file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)</li>
<li>The <strong>&lt;qp0lror.h&gt;</strong> file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)</li>
<li>The <strong>&lt;qlg.h&gt;</strong> file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)</li>
<li><a href="qwcrjblk.htm">Retrieve Job Locks API (QWCRJBLK) API</a> </li>
<li><a href="qp0lror.htm">Retrieve Object References (QP0LROR) API</a> </li>
</ul>
<br>
<h3>Example</h3>
<p>The following is an example use of this API.</p>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<pre>
#include &lt;qp0lrro.h&gt;
#include &lt;qp0wpid.h&gt;
#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;iconv.h&gt
#include &lt;qtqiconv.h&gt
#include &lt;errno.h&gt
/* Function convertData for converting a National Language Support */
/* path name */
int convertData(int in_ccsid,
int out_ccsid,
char *in_buf,
char *out_buf,
size_t *in_bytes_left,
size_t *out_bytes_left)
{
QtqCode_T from_code =
{
0, /* input CCSID. */
0, /* (conversion alternative)
IBM default conversion. */
0, /* (substitution alternative)
do not return substitution
count. */
0, /* (shift-state alternative)
conv descriptor is not
returned to initial shift
state. */
0, /* (input length option) valid
inbytesleft required.
(input/output are NOT
null-terminated) */
0 /* (error option for mixed data)
No mixed byte errors. */
};
QtqCode_T to_code =
{
0, /* output CCSID. */
0, /* ignored on output */
0, /* ignored on output */
0, /* ignored on output */
0, /* ignored on output */
0 /* ignored on output */
};
iconv_t cd; /* conversion descriptor. */
/* Set the to and from ccsids. */
from_code.CCSID = in_ccsid;
to_code.CCSID = out_ccsid;
errno = 0;
/* Call code conversion allocation API to get a conversion */
/* descriptor. */
cd = QtqIconvOpen(&amp;to_code, &amp;from_code);
/* verify conversion descriptor */
if ( cd.return_value == -1 )
{
printf("ERROR: iconv_open failed (errno=%d).",
errno);
return(-1);
}
/* Do the conversion. */
if ( iconv(cd,
&amp;in_buf,
in_bytes_left,
&amp;out_buf,
out_bytes_left) == -1 )
{
printf("ERROR: iconv failed (errno=%d).",
errno);
printf("The input ccsid=%d, and the output ccsid=%d.",
in_ccsid, out_ccsid);
printf("The input data=%s.\n", in_buf);
return(-1);
}
/* Close the conversion descriptor. */
if ( iconv_close(cd) == -1 )
{
printf("ERROR: iconv_close failed (errno=%d).",
errno);
return(-1);
}
return(0);
} /* end convertData */
/*************************/
/* Start of main program */
/*************************/
void main()
{
/* Define a Path name structure */
struct PathNameStruct
{
Qlg_Path_Name_T pn_header;
char pn[500];
};
struct PathNameStruct *pathP;
char path_buffer[500]; /* buffer to receive a converted
path name */
size_t out_bytes; /* path buffer size */
Qus_EC_t errorCode;
/* Define an input job structure */
struct myjob100_struct
{
char Job_Name[10];
char User_Name[10];
char Job_Number[6];
char Int_Job_ID[16];
char Reserved[2];
int Thread_Indicator;
char Thread_Id[8];
}myjob100_struct_t;
char output_format[8]; /* declare an output format variable */
unsigned outputBufSize; /* Declare an output buffer size
variable */
/* declare a pointer fro retrieving the Object list output */
Qp0l_Obj_List_Output_T *Obj_ListP;
/* Declare a pointer for retrieving the RROO0100 format. */
Qp0l_RROO0100_Output_T *output100P;
/* Declare a job pointer. */
struct QP0W_Job_ID_T jobP;
struct myjob100_struct Job_ID;
char job_format[8]; /* declare a job format variable. */
/* Declare a process ID */
pid_t Process_ID = 0; /* zero = current process */
/*********************************************************/
/* Define a constant for the number of output buffer */
/* bytes provided for the RROO0100 format. */
/*********************************************************/
outputBufSize = \
(sizeof(Qp0l_RROO0100_Output_T) + \
sizeof(Qp0l_Obj_List_Output_T) + \
sizeof(Qlg_Path_Name_T) + \
sizeof(Qp0l_Ext_Ref_Types_Output_T) + \
5000); /* Pad space for the returned path
name */
/*************************************/
/* Get the job ID of the current job */
/*************************************/
int rv = Qp0wGetJobID(Process_ID, &amp;jobP);
if(rv != 0)
{
printf("Error occurred for Qp0lGetJobID.\n");
return;
}
/*********************************************************/
/* Set the Qp0l_RROI0100 information from the Process_ID */
/*********************************************************/
memset(&amp;Job_ID, 0x00, sizeof(Job_ID));
memcpy(Job_ID.Job_Name, jobP.jobname, sizeof(Job_ID.Job_Name));
memcpy(Job_ID.User_Name, jobP.username, sizeof(Job_ID.User_Name));
memcpy(Job_ID.Job_Number, jobP.jobnumber, sizeof(Job_ID.Job_Number));
memset(Job_ID.Int_Job_ID, 0x40, sizeof(Job_ID.Int_Job_ID));
/*********************************************************/
/* Setup the error code structure to cause the error to */
/* be returned within the error structure. */
/*********************************************************/
errorCode.Bytes_Provided = sizeof(errorCode);
errorCode.Bytes_Available = 0;
/****************************************************/
/* Allocate space to receive output from QP0LRRO */
/****************************************************/
if (NULL == (output100P = (Qp0l_RROO0100_Output_T *)
malloc(outputBufSize)))
{
printf("No space available.\n");
return;
}
/****************************************************/
/* Clear the allocated space */
/****************************************************/
memset(output100P, 0x00, outputBufSize);
/****************************************************/
/* set output format and job format */
/****************************************************/
memcpy(output_format,
QP0LRRO_RROO0100_FORMAT,
sizeof(output_format));
memcpy(job_format,
QP0LRRO_RROI0100_FORMAT,
sizeof(job_format));
/*********************************************************/
/* Call QP0LRRO. We will compare the number of bytes */
/* to the number of bytes available to allocate more */
/* space if required */
/*********************************************************/
QP0LRRO(output100P,
outputBufSize,
output_format,
&amp;Job_ID,
job_format,
&amp;errorCode);
/* Check if an error occurred. */
if (errorCode.Bytes_Available != 0)
{
printf("Error occurred for RROO0100.\n");
free(output100P); /* free space */
return;
}
/************************************************************/
/* If there was more information available than we had */
/* provided receiver space for, then we will allocate a */
/* larger buffer and try once again. This could potentially*/
/* keep re-occurring, but this example will stop after this */
/* second retry. */
/************************************************************/
if (output100P->BytesReturned &lt; output100P->BytesAvailable)
{
/*********************************************************/
/* Use the bytes available value to determine how much */
/* more buffer size is needed. We will pad it with an */
/* extra 1000 bytes to try and handle more jobs obtaining*/
/* references between calls to QP0LRRO. */
/*********************************************************/
outputBufSize = output100P->BytesAvailable + 1000;
/* reallocate more space to output100P */
output100P = (Qp0l_RROO0100_Output_T *)(realloc((void *)output100P,
outputBufSize));
if (output100P ==NULL)
{
printf("No space available.\n");
free(output100P); /* free space */
return;
}
QP0LRRO(output100P,
outputBufSize,
output_format,
&amp;Job_ID,
job_format,
&amp;errorCode);
/* Check if an error occurred. */
if (errorCode.Bytes_Available != 0)
{
free(output100P);
printf("Error occurred for RROO0100 (2nd call).\n");
return;
}
}
/***************************************************/
/* Check if we received any objects that might be */
/* associated with a job. If not, return. */
/***************************************************/
if (output100P->ObjectsReturned == 0)
{
printf("QP0LRRO returned an object count of: %d\n",
output100P->ObjectsReturned);
printf("Number of objects available: %d\n",
output100P->ObjectsAvailable);
free(output100P);
return;
}
printf("Number of objects referenced by the job: %d\n",
output100P->ObjectsReturned);
printf("Number of objects available: %d\n",
output100P->ObjectsAvailable);
printf("Paths referenced by the current job:\n");
/* Get a pointer to the object list structure */
Obj_ListP = (Qp0l_Obj_List_Output_T *)((char *)output100P + output100P->ObjListOffset);
/* Loop through the output buffer and return the path names */
for(int i = 0; i &lt; output100P->ObjectsReturned; i++)
{
/* Get a pointer to the Qlg_Path_Name structure */
pathP = (PathNameStruct *)((char *)Obj_ListP + Obj_ListP->PathDisp);
/* clear the returned path buffer */
memset(path_buffer, 0x00, sizeof(path_buffer));
out_bytes = sizeof(path_buffer); /* get size of path buffer */
/**********************************************/
/* convert the returned object from the ccsid */
/* in the Qlg path structure to the jobccsid */
/**********************************************/
convertData(pathP->pn_header.CCSID,
0,
pathP->pn,
path_buffer,
(size_t *)&amp;pathP->pn_header.Path_Length,
(size_t *)&amp;out_bytes);
/* print the path name */
printf(" %s\n",path_buffer);
/* increment to next list entry */
Obj_ListP = (Qp0l_Obj_List_Output_T *)((char *)Obj_ListP + Obj_ListP->NextListEntryDisp);
}
free(output100P);
return;
}
</pre>
<p><strong>Example Output:</strong></p>
<pre>Number of objects referenced by the job: 3
Number of objects available: 3
Paths referenced by the current job:
/
/home/myprofile
/mydir/mystmf1
</pre>
<hr>
API introduced: V5R3
<hr>
<table align="center" cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink