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

645 lines
19 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>List Validation List Certificates (QSYLSTVC,QsyListVldlCertificates)
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. -->
<!-- Sec SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Edited by Kersten Jan 02 -->
<!--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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>List Validation List Certificates (QSYLSTVC,QsyListVldlCertificates)
API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;<img src="delta.gif" alt="Start of change">Required Parameter Group for QSYLSTVC:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Qualified user space name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Validation list path name</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">Length of path</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Format name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Selection control</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<br>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Syntax for QsyListVldlCertificates:<br>
<pre>
#include &lt;qsydigid.h&gt;
void QsyListVldlCertificates
(char *<em>Qualified_user_space_name</em>,
char *<em>Validation_list_path_name</em>,
int <em>Length_of_path</em>,
char *<em>Format_name</em>,
char *<em>Selection_control</em>,
void *<em>Error_code</em>);
</pre>
&nbsp;&nbsp;Service Program: QSYDIGID<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<img src="deltaend.gif" alt="End of change"><br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The List Validation List Certificates (OPM, QSYLSTVC; ILE,
QsyListVldlCertificates) API lists the certificates in the validation list. The
generated list replaces any existing list in the user space.</p>
<p>There may be many certificates in a validation list. Because a user space
has a defined maximum length, there may be more certificates in a validation
list than can be put into the user space. The List Validation List Certificates
API allows the caller to specify additional selection processing so that only
the certificates in the validation list which have fields matching the caller's
selections are to be listed in the user space. The information status field in
the generic header is set to indicate if the results are complete or not.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Validation List Authority</em></dt>
<dd>*USE</dd>
<dt><em>Validation List Library Authority</em></dt>
<dd>*Execute</dd>
<dt><em>User Space Authority</em></dt>
<dd>*CHANGE</dd>
<dt><em>User Space Library Authority</em></dt>
<dd>*USE</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Qualified user space name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The name of the existing user space used to return the list of validation
list certificates. The first 10 characters specify the user space name, and the
second 10 characters specify the library.</p>
<p>You can use these special values for the library name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The current library is used to locate the user
space. If there is no current library, QGPL (general purpose library) is
used.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list is used to locate the user
space.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Validation list path name</strong></dt>
<dd>INPUT; CHAR(*)
<p>The fully qualified path name of the validation list.</p>
</dd>
<dt><strong>Length of path</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the validation list path name.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The content and format of the information that is returned for each
certificate in the list data section of the qualified user space name.</p>
<p>The possible formats are:</p>
<table cellpadding="5">
<!-- cols="35 65" -->
<tr>
<td align="left" valign="top"><em><a href="qsylstuc.htm#HDRCERT100">CERT0100</a></em></td>
<td align="left" valign="top">Certificates in Abstract Syntax Notation 1
(ASN.1) format</td>
</tr>
<tr>
<td align="left" valign="top"><em><a href="qsylstuc.htm#HDRCERT200">CERT0200</a></em></td>
<td align="left" valign="top">Certificates in plain text format</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Selection control</strong></dt>
<dd>INPUT; CHAR(*)
<p>The structure that contains strings which are used to limit which
certificates are returned. For the format of the structure, see <a href=
"qsylstuc.htm#HDRSELTCNT">Selection Control</a>.</p>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<br>
<h3>Usage Notes</h3>
<p>In the list data section, the Offset to EIM identifier, Length of EIM
identifier, Offset to EIM local registry name, Length of EIM local registry
name, Offset to user name, and Length of user name fields will be 0.</p>
<br>
<h3><a name="HDRRETVLST">Format</a></h3>
<p>The certificate list generated in the user space consists of:</p>
<ul>
<li>A user area</li>
<li>A generic header</li>
<li>An input parameter section</li>
<li>A list data section</li>
</ul>
<br>
<p>In the generic header, the offset and length of the header section are set
to zero because the header section is not used. The list data section has
variable length entries, so the size of each entry is set to 0 in the generic
header. For details about the user area and generic header, including which
field indicates the number of entries returned or the offset to the first
entry, see <a href="../apiref/usf.htm">User Space Format for List APIs</a>.</p>
<p>For details about the formats in the list data section, see <a href=
"qsylstuc.htm#HDRCERT100">Certificate Format CERT0100 (ASN.1)</a> and <a href=
"qsylstuc.htm#HDRCERT200">Certificate Format CERT0200 (Plain Text)</a>.</p>
<p>For details about the remaining items, see the following sections. For
descriptions of each field in the list returned, see <a href=
"#HDRCRTSDES">Field Descriptions</a>.</p>
<h4><a name="HDRCRTVPRM">Input Parameter Section</a></h4>
<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(10)</td>
<td align="left" valign="top" width="60%">User space name specified</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">User space library name specified</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">Offset to validation list path name</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 validation list path name</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Format name</td>
</tr>
<tr>
<td align="center" valign="top">36</td>
<td align="center" valign="top">24</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to selection control</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">Validation list path name</td>
</tr>
<tr>
<td align="left" valign="top" rowspan="3" colspan="2">The offset to this
selection control is specified in a previous offset variable.</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of selection control</td>
</tr>
<tr>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Number of selection pairs</td>
</tr>
<tr>
<td align="left" valign="top">ARRAY(*) of BINARY(4)</td>
<td align="left" valign="top">Displacements to selection pairs</td>
</tr>
<tr>
<td align="left" valign="top" colspan="2" rowspan="3">These fields repeat for
each selection pair specified.</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of selection pair</td>
</tr>
<tr>
<td align="left" valign="top">CHAR(20)</td>
<td align="left" valign="top">Selection name</td>
</tr>
<tr>
<td align="left" valign="top">ARRAY(*) of CHAR</td>
<td align="left" valign="top">Selection value</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRCRTSDES">Field Descriptions</a></h3>
<p><strong>Displacements to selection pairs.</strong> An array of displacements
to selection pairs from the beginning of the selection control.</p>
<p><strong>Format name.</strong> The format of the returned output.</p>
<p><strong>Length of selection control.</strong> The total number of bytes for
the length itself, for the number of selection pairs, and for the array of
displacements. It also includes the sum of the lengths of the selection pairs.
The length of the selection control will vary due to the array of displacements
and the selection pairs. A length of zero is one of the ways to indicate that
no selection control pairs are specified.</p>
<p><strong>Length of selection pair.</strong> The total length of the selection
name and selection value fields and the bytes for the length itself. The length
of the selection pair will vary due to the selection value. Valid values that
are used are 24 or larger. A value of 24 corresponds to a selection value that
is empty and means that certificates should be returned when the corresponding
value in the certificate is also empty or not recognized.</p>
<p><strong>Length of validation list path name.</strong> The length of the path
name of the validation list that is specified in the call to the API.</p>
<p><strong>Number of selection pairs.</strong> The number of separate selection
pairs in the generated list of certificates. All of the selection pairs must be
satisfied for each certificate that is returned. If the number of selection
pairs is 0, then all certificates are returned.</p>
<p><strong>Offset to selection control.</strong> The offset to the selection
control. The first field of the selection control is the length of selection
control.</p>
<p><strong>Offset to validation list path name.</strong> The offset to the full
path name of the validation list that is specified in the call to the API.</p>
<p><strong>Selection name.</strong> The selection that is used to limit which
certificates from the validation list are returned. Selections made here
indicate which field of the certificate is to be examined for a matching
selection value. Selection names cannot be specified more than once. Selection
names are defined with length QSY_SELCTRL_NAME_LEN.</p>
<p>Valid selection names are:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>COMMONNAME</em></td>
<td align="left" valign="top">Client's common name</td>
</tr>
<tr>
<td align="left" valign="top"><em>COUNTRY</em></td>
<td align="left" valign="top">Country or region in which the client
resides</td>
</tr>
<tr>
<td align="left" valign="top"><em>LOCALITY</em></td>
<td align="left" valign="top">Locality in which the client resides</td>
</tr>
<tr>
<td align="left" valign="top"><em>STATEORPROVINCE</em></td>
<td align="left" valign="top">State or province in which the client
resides</td>
</tr>
<tr>
<td align="left" valign="top"><em>ORGANIZATION</em></td>
<td align="left" valign="top">Organization of the client</td>
</tr>
<tr>
<td align="left" valign="top"><em>ORGANIZATIONALUNIT</em></td>
<td align="left" valign="top">Organizational unit of the client</td>
</tr>
<tr>
<td align="left" valign="top"><em>PUBLICKEY</em></td>
<td align="left" valign="top">Public key of the certificate. This value is not
text. It is the entire public key information as found in the certificate in
ASN.1 DER format and it includes the tags and lengths. The actual public key
found in the certificate is compared with the specified selection value that
corresponds with this selection name. It is not returned in the list data
section when the CERT0200 format name is specified.</td>
</tr>
<tr>
<td valign="top"><em>EXPIRATIONDAYS</em></td>
<td valign="top">Certificates that are expired or will expire
in the specified number of days. This value will be the number of days in
character format (zoned decimal).</td>
</tr>
<tr>
<td valign="top"><em>CERTIFICATEHANDLE</em></td>
<td valign="top">Handle for the certificate.</td>
</tr>
</table>
<p><strong>Selection value.</strong> The array of characters that is used for
matching the corresponding field of the certificate. A match in the certificate
indicates that the certificate is of interest. If the certificate does not
contain matching characters in its corresponding field, the certificate will
not be returned as part of the list. The length of the selection value can be
determined by subtracting the fixed lengths of the selection name field and the
length field from the length of selection pair. The comparison of the fields is
done in the CCSID of the job and is case sensitive.</p>
<p><strong>User space library name specified.</strong> The library that
contains the user space, as specified in the call to the API.</p>
<p><strong>User space name specified.</strong> The name of the user space.</p>
<p><strong>Validation list path name.</strong> The path name of the validation
list.</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">CPFA0AA E</td>
<td width="85%" valign="top">Error occurred while attempting to obtain
space.</td>
</tr>
<tr>
<td align="left" valign="top">CPFA09C E</td>
<td align="left" valign="top">Not authorized to object.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1F41 E</td>
<td align="left" valign="top">Severe error occurred while addressing parameter
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF227B E</td>
<td align="left" valign="top">Certificate is not correct for the specified
type.</td>
</tr>
<tr>
<td align="left" valign="top">CPF227E E</td>
<td align="left" valign="top">Selection control is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3BFF E</td>
<td align="left" valign="top">Required option &amp;1 is not available.
</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">CPF3C1D E</td>
<td align="left" valign="top">Length specified in parameter &amp;1 not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C1E E</td>
<td align="left" valign="top">Required parameter &amp;1 omitted.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is 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">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">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9801 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9802 E</td>
<td align="left" valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9803 E</td>
<td align="left" valign="top">Cannot allocate object &amp;2 in library
&amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9804 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 damaged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9810 E</td>
<td align="left" valign="top">Library &amp;1 not found.</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>
</table>
<br>
<hr>
API introduced: V4R2
<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>