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

774 lines
22 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Verify Object (QYDOVFYO, QydoVerifyObject) 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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- QYDOVFYO SCR510 A converted by B2H R4.1 (346) (CMS) by V2CDIJAB -->
<!-- at RCHVMW2 on 17 Oct 2000 at 12:59:06 -->
<!-- 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>Verify Object (QYDOVFYO, QydoVerifyObject) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Object path name</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">Length of object path name</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">Format of object path name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Multiple objects characteristics</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Length of multiple objects characteristics</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Service Program Name: QYDOVFY1<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Verify Object (OPM, QYDOVFYO; ILE, QydoVerifyObject) API checks to see
if an object has changed since it was signed. Only certificates in the local
system's Verify Object certificate database that have signed this object will
be checked. Any other signatures will be ignored. If none of the signatures of
this object are by certificates the local system recognizes, the object is
considered unsigned. If the object is unsigned, this is reported as an error.
If any trusted signatures are valid, the object is considered successfully
verified.<br>
</p>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Authority Required</em></dt>
<dd>*AUDIT special authority is optional; if used, all objects can be verified.
If *AUDIT special authority is not used, you need to have:
<p>For objects in a library:</p>
<ul>
<li>*READ authority to the object</li>
<li>*OBJOPR and *EXECUTE authority to the library.</li>
</ul>
<p>For objects in a directory:</p>
<ul>
<li>*R authority to the object</li>
<li>*X authority to each directory in the path<br>
*R for the directory with wildcards (that is, a pattern is specified)<br>
*RX authority to each subdirectory searched if the subdirectories parameter
specifies 1.</li>
</ul>
<p>See the <a href="open.htm">open()</a> API for the authority needed to the
results path name. The file is open for append and is created if it does not
already exist.</p>
</dd>
<dt><em>Locks</em></dt>
<dd>Object will be locked shared allow read. Certificate database will be
locked while certificates are retrieved (to make up trusted certificate list
needed to verify).</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Object path name</strong></dt>
<dd>INPUT; CHAR(*)
<p>The name of the object you want to verify. If the object is not in a
library, the name may be relative to the current directory or may specify the
entire path name. If the object is in a library the name must be in the form
'/QSYS.LIB/libname.LIB/objname.objtype' if you are using format OBJN0100 object
path naming. For example to sign a program named NEWEMPL in library PAYROLL,
the qualified object name would be '/QSYS.LIB/PAYROLL.LIB/NEWEMPL.PGM' if you
are using format OBJN0100 object path naming. Also if you are using format
OBJN0100 object path naming, this parameter is assumed to be represented in the
coded character set identifier (CCSID) currently in effect for the job. If the
CCSID of the job is 65535, this parameter is assumed to be represented in the
default CCSID of the job.</p>
<p>The path name may contain
wildcard characters. '*' will represent any number of unknown characters. '?'
will represent any single unknown character. For example, to specify all the
program objects in library MYLIB, using format OBJN0100, you could specify
'/QSYS.LIB/MYLIB.LIB/*.PGM'. If you want to verify all signable objects in a
library or directory, specify the last part of the path name as simply '*'. For
example to verify all signable objects in MYLIB, assuming you are using format
OBJN0100, you could specify '/QSYS.LIB/MYLIB.LIB/*'.</p>
<p>If the object is in the QSYS
file system, it must an object type *PGM, *SRVPGM, *MODULE, *SQLPKG, *FILE
(save file),</p>
or *CMD.</dd>
<dt><strong>Length of object path name</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the object path name. If the format of object path name is
OBJN0200, this field must include the QLG path name structure in addition to
the path name itself. If the format of object path name is OBJN0100, only the
path name itself is included.</p>
</dd>
<dt><strong>Format of object path name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the object path name parameter.</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>OBJN0100</em></td>
<td align="left" valign="top">The object path name is a simple path name.</td>
</tr>
<tr>
<td align="left" valign="top"><em>OBJN0200</em></td>
<td align="left" valign="top">The object path name is an LG-type path
name.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Multiple objects characteristics</strong></dt>
<dd>INPUT; CHAR(*)
<p>How multiple objects specified on the object path name parameter are
handled. See <a href="#HDRMLTGP1">Multiple objects characteristics format</a>
for details on the format of this parameter. This field may be NULL if the
length of multiple objects characteristics is 0.</p>
</dd>
<dt><strong>Length of multiple objects characteristics</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the specified multiple objects characteristics. This length
may be 0 if you want to use the default values for all these characteristics,
or 1 or greater to indicate how many bytes of the characteristics should be
used.</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>
<br>
<h3><a name="HDRMLTGP1">Multiple objects characteristics format</a></h3>
<p>The format of the multiple objects characteristics is shown in the following
table. For detailed descriptions of the fields in the tables, see <a href=
"#HDRMLTGP2">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%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Subdirectories</td>
</tr>
<tr>
<td align="center" valign="top">1</td>
<td align="center" valign="top">1</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Stop of first error</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="center" valign="top">2</td>
<td align="left" valign="top">CHAR(6)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to results file path name</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">0C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of results file path name</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Format of results file path name</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Format of contents of the results file</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Results file path name</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRMLTGP2">Field Descriptions</a></h3>
<p><strong>Format of content of the results file.</strong> The format of the
contents of the file containing the results of this call.</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>RSLT0100</em></td>
<td align="left" valign="top">The basic information is returned for each object
specified by the object path name parameter.</td>
</tr>
</table>
<p><strong>Format of results path name.</strong> The format of the results path
name parameter.</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>OBJN0100</em></td>
<td align="left" valign="top">The results path name is a simple path name.</td>
</tr>
<tr>
<td align="left" valign="top"><em>OBJN0200</em></td>
<td align="left" valign="top">The results path name is an LG-type path
name.</td>
</tr>
</table>
<p><strong>Length of results path name.</strong> The length of the results path
name. 0 length means no results files are used, and the results path name and
format of results path name parameter values are not used. If the format of
results path name is OBJN0200, this field must include the QLG path name
structure in addition to the path name itself. If the format of results path
name is OBJN0100, only the path name itself is included.</p>
<p><strong>Offset to results path name.</strong> Offset from the beginning of
this structure to the results path name.</p>
<p><strong>Reserved.</strong> This field currently is not used. It is filled
with binary zeroes.</p>
<p><strong>Results path name.</strong> The path name of the object you want to
contain the results on this call. This object may not be in a library (that is, may
not be under the /QSYS.LIB directory). The name may be relative to the current
directory or may specify the entire path name. For example to store results in
a file called SIGNED.LST in the MYDIR directory, the results path name would be
'/MYDIR/SIGNED.LST'. If you are using format OBJN0100, this parameter is
assumed to be represented in the coded character set identifier (CCSID)
currently in effect for the job. If the CCSID of the job is 65535, this
parameter is assumed to be represented in the default CCSID of the job.</p>
<p>If this is an existing file, results will be appended to the end of the
file. Otherwise, a new file will be created.</p>
<p>The default is not to have a
results file.</p>
<p><strong>Stop on first error.</strong> Whether control should be returned on
the first error found.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Continue processing objects even if some errors
are found.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">
"Start of change">Stop on the first object that detects an error. This is the
default value.</td>
</tr>
</table>
<p><strong>Subdirectories.</strong> Whether objects in directories under the
directory specified in the object path name parameter should be processed
also.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Process objects in the directory specified in the
object path name parameter only. This is the default value.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Process objects in the directory specified in the
object name path parameter and in all directories under that directory.</td>
</tr>
</table>
<br>
<h3><a name="HDRLOBJA1A">RSLT0100 format</a></h3>
<p>The following table describes the order and format of the data returned in
the RSLT0100 format. This data is repeated for each object that was attempted
to be verified. For detailed descriptions of the fields in the tables, see <a
href="#HDRRSLTA2">Field Descriptions</a>.</p>
<p><strong>Note:</strong>All data in this file will be in CCSID 13488. New
files will be created in this CCSID. If an existing file is named that has a
different CCSID, an error will be reported.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">CHAR(7)</td>
<td align="left" valign="top" width="60%">Message identifier</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="center" valign="top">7</td>
<td align="left" valign="top">CHAR(9)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Date</td>
</tr>
<tr>
<td align="center" valign="top">24</td>
<td align="center" valign="top">18</td>
<td align="left" valign="top">CHAR(8)</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(1)</td>
<td align="left" valign="top">Operation type</td>
</tr>
<tr>
<td align="center" valign="top">33</td>
<td align="center" valign="top">21</td>
<td align="left" valign="top">CHAR(15)</td>
<td align="left" valign="top">Operation type description</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">56</td>
<td align="center" valign="top">38</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Fully qualified object name</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRSLTA2">Field Descriptions</a></h3>
<p><strong>Date.</strong> The date the operation took place. The format will be
YYYYMMDD. For example, June 30, 2002 will be 20020630.</p>
<p><strong>Fully qualified object name.</strong> The simple path name from the
root to the object whose signature is being verified. The field will be
terminated with a new line character.</p>
<p><strong>Message identifier.</strong> The error message used to report
failure. This field is blank if no error was detected for this object.</p>
<p><strong>Operation type.</strong> The operation that was attempted.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Signing operation</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Verifying operation</td>
</tr>
</table>
<p><strong>Operation type description.</strong> Short word description of the
operation that was attempted.</p>
<p><strong>Reserved.</strong> This field currently is not used. It is filled
with blanks.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPFA085 E</td>
<td width="85%" valign="top">Home directory not found for user &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA086 E</td>
<td align="left" valign="top">Matching quote not found in path name.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA087 E</td>
<td align="left" valign="top">Path name contains null character.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA088 E</td>
<td align="left" valign="top">Path name pattern not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA089 E</td>
<td align="left" valign="top">Pattern not allowed in path name.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA08B E</td>
<td align="left" valign="top">Path name cannot begin with *.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA08C E</td>
<td align="left" valign="top">Pattern not allowed in path name directory.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA08D E</td>
<td align="left" valign="top">Request information value is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA08E E</td>
<td align="left" valign="top">More than one name matches pattern.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA091 E</td>
<td align="left" valign="top">Pattern not allowed in user name.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA092 E</td>
<td align="left" valign="top">Path name not converted.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA094 E</td>
<td align="left" valign="top">Path name not specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA0A4 E</td>
<td align="left" valign="top">Too many open files for process.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA0AA E</td>
<td align="left" valign="top">Error occurred while attempting to obtain
space.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA0D4 E</td>
<td align="left" valign="top">File system error occurred.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB720 E</td>
<td align="left" valign="top">No signable object was found.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB722 E</td>
<td align="left" valign="top">Object not signed.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB723 E</td>
<td align="left" valign="top">Object signed, but signature is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB724 E</td>
<td align="left" valign="top">Option &amp;2 of the operating system is required
to work with object signatures.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB72A E</td>
<td align="left" valign="top">The object had no trusted signatures on the
object.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB72B E</td>
<td align="left" valign="top">Object not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB72C E</td>
<td align="left" valign="top">The object cannot currently be signed or
verified.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB735 E</td>
<td align="left" valign="top">The digital signing API parameter &amp;1 is not
large enough.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB736 E</td>
<td align="left" valign="top">The digital signing API parameter &amp;1 is not
small enough.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB737 E</td>
<td align="left" valign="top">The digital signing API parameter &amp;1 is a
null pointer.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB738 E</td>
<td align="left" valign="top">The digital signing API parameter &amp;1 is not a
valid format type.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB739 E</td>
<td align="left" valign="top">The digital signing API parameter &amp;1 is out
of range.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB73A E</td>
<td align="left" valign="top">The password for the certificate key database
needs to be set.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB740 E</td>
<td align="left" valign="top">The format name for the pathname is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB741 E</td>
<td align="left" valign="top">The length of the path name parameter is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB742 E</td>
<td align="left" valign="top">The subdirectory option is an invalid value.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB743 E</td>
<td align="left" valign="top">The value for stopping on the first error is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB744 E</td>
<td align="left" valign="top">The format of the results file for the digital
signing API is an incorrect v.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB745 E</td>
<td align="left" valign="top">The format name for the results file path name is
not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB746 E</td>
<td align="left" valign="top">The results file path name length is not large
enough.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB749 E</td>
<td align="left" valign="top">Object signature operation ended abnormally.
&amp;1 objects attempted, &amp;2 objects successfully processed.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB74D E</td>
<td align="left" valign="top">Results file could not be used.</td>
</tr>
<tr>
<td align="left" valign="top">CPFBC50 E</td>
<td align="left" valign="top">No path names match input path names.</td>
</tr>
</table>
<br>
<hr>
API introduced: V5R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"sec.htm">Security APIs</a> | <a href="aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>