<!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>Open List of User Certificates (QSYOLUC) 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>Open List of User Certificates (QSYOLUC) API</h2> <div class="box" style="width: 80%;"> <br> Required Parameter Group:<br> <!-- iddvc RMBR --> <br> <table width="100%"> <tr> <td align="center" valign="top" width="10%">1</td> <td align="left" valign="top" width="50%">Receiver variable</td> <td align="left" valign="top" width="20%">Output</td> <td align="left" valign="top" width="20%">Char(*)</td> </tr> <tr> <td align="center" valign="top">2</td> <td align="left" valign="top">Length of receiver variable</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Binary(4)</td> </tr> <tr> <td align="center" valign="top">3</td> <td align="left" valign="top">List information</td> <td align="left" valign="top">Output</td> <td align="left" valign="top">Char(80)</td> </tr> <tr> <td align="center" valign="top">4</td> <td align="left" valign="top">Number of records to return</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Binary(4)</td> </tr> <tr> <td align="center" valign="top">5</td> <td align="left" valign="top">Format name</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Char(8)</td> </tr> <tr> <td align="center" valign="top">6</td> <td align="left" valign="top">User name</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Char(10)</td> </tr> <tr> <td align="center" valign="top">7</td> <td align="left" valign="top">Error code</td> <td align="left" valign="top">I/O</td> <td align="left" valign="top">Char(*)</td> </tr> </table> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: Yes<br> <!-- iddvc RMBR --> <br> </div> <p>The Open List of User Certificates (QSYOLUC) API provides a list of user certificates associated with a user.</p> <br> <h3>Authorities and Locks</h3> <dl> <dt><em>User Profile Authority</em></dt> <dd>*USE</dd> </dl> <br> <h3>Required Parameter Group</h3> <dl> <dt><strong>Receiver variable</strong></dt> <dd>OUTPUT; CHAR(*) <p>The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold. For more information about the format of the data returned in the receiver variable, 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> </dd> <dt><strong>Length of receiver variable</strong></dt> <dd>INPUT; BINARY(4) <p>The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. For formats that contain variable length data, the receiver variable length must be large enough to hold the fixed portion of the record.</p> </dd> <dt><strong>List information</strong></dt> <dd>OUTPUT; CHAR(80) <p>The variable that is used to return status information about the list of user certificates that were opened. See <a href="#HDRRATLOL1">Format of List Information</a> for a description of this parameter.</p> </dd> <dt><strong>Number of records to return</strong></dt> <dd>INPUT; BINARY(4) <p>The number of records containing a user certificate to return. The value -1 indicates that all the records containing user certificates should be returned.</p> </dd> <dt><strong>Format name</strong></dt> <dd>INPUT; CHAR(8) <p>The name of the format that is used to list user certificates.</p> <p>The possible format names 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 ASN.1 format in ASCII encoding.</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. Character fields are encoded in the job CCSID.</td> </tr> </table> <br> </dd> <dt><strong>User name</strong></dt> <dd>INPUT; CHAR(10) <p>The name of the user profile.</p> <p>The following is a valid selection:</p> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td align="left" valign="top"><em>*CURRENT</em></td> <td align="left" valign="top">The user profile that is currently running.</td> </tr> </table> <br> </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="HDRRATLOL1">Format of List Information</a></h3> <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%">Total records</td> </tr> <tr> <td align="center" valign="top">4</td> <td align="center" valign="top">4</td> <td align="left" valign="top">BINARY(4)</td> <td align="left" valign="top">Records returned</td> </tr> <tr> <td align="center" valign="top">8</td> <td align="center" valign="top">8</td> <td align="left" valign="top">CHAR(4)</td> <td align="left" valign="top">Request handle</td> </tr> <tr> <td align="center" valign="top">16</td> <td align="center" valign="top">10</td> <td align="left" valign="top">CHAR(1)</td> <td align="left" valign="top">Information complete indicator</td> </tr> <tr> <td align="center" valign="top">17</td> <td align="center" valign="top">11</td> <td align="left" valign="top">CHAR(13)</td> <td align="left" valign="top">Date and time created</td> </tr> <tr> <td align="center" valign="top">30</td> <td align="center" valign="top">1E</td> <td align="left" valign="top">CHAR(1)</td> <td align="left" valign="top">List status indicator</td> </tr> <tr> <td align="center" valign="top">31</td> <td align="center" valign="top">1F</td> <td align="left" valign="top">CHAR(1)</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">BINARY(4)</td> <td align="left" valign="top">Length of information returned</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">First record in buffer</td> </tr> <tr> <td align="center" valign="top">44</td> <td align="center" valign="top">2C</td> <td align="left" valign="top">CHAR(36)</td> <td align="left" valign="top">Reserved</td> </tr> </table> <br> <br> <h3>Field Descriptions</h3> <p><strong>Date and time created.</strong> The date and time when the list was created.</p> <p>The 13 characters are:</p> <table cellpadding="5"> <!-- cols="10 90" --> <tr> <td align="left" valign="top"><em>1</em></td> <td align="left" valign="top">Century, where 0 indicates years 19<em>xx</em> and 1 indicates years 20<em>xx</em>.</td> </tr> <tr> <td align="left" valign="top"><em>2-7</em></td> <td align="left" valign="top">The date, in YYMMDD (year, month, and day) format.</td> </tr> <tr> <td align="left" valign="top"><em>8-13</em></td> <td align="left" valign="top">The time of day, in HHMMSS (hours, minutes, and seconds) format.</td> </tr> </table> <p><strong>First record in buffer.</strong> The number of the first record in the receiver variable.</p> <p><strong>Information complete indicator.</strong> Whether all requested information has been supplied.</p> <p>Possible values follow:</p> <table cellpadding="5"> <!-- cols="5 95" --> <tr> <td align="left" valign="top"><em>I</em></td> <td align="left" valign="top">Incomplete information. An interruption causes the list to contain incomplete information about a buffer or buffers.</td> </tr> <tr> <td align="left" valign="top"><em>P</em></td> <td align="left" valign="top">Partial and accurate information. Partial information is returned when the maximum space was used and not all of the buffers requested were read.</td> </tr> <tr> <td align="left" valign="top"><em>C</em></td> <td align="left" valign="top">Complete and accurate information. All the buffers requested are read and returned.</td> </tr> </table> <p><strong>Length of information returned.</strong> The size, in bytes, of the information that is returned in the receiver variable.</p> <p><strong>List status indicator.</strong> The status of building the list.</p> <p>The possible value follows:</p> <table cellpadding="5"> <!-- cols="5 95" --> <tr> <td align="left" valign="top"><em>2</em></td> <td align="left" valign="top">The list has been completely built.</td> </tr> </table> <p><strong>Records returned.</strong> The number of records returned in the receiver variable. This is the smallest of the following three values:</p> <ul> <li>The number of records that will fit into the receiver variable.</li> <li>The number of records in the list.</li> <li>The number of records that are requested.</li> </ul> <p><strong>Request handle.</strong> The handle of the request that can be used for subsequent requests of information from the list. The handle is valid until the Close List (QGYCLST) API is called to close the list, or until the job ends.</p> <p><strong>Note:</strong> This field should be treated as a hexadecimal field. It should not be converted from one CCSID to another, for example, EBCDIC to ASCII, because doing so could result in an unusable value.</p> <p><strong>Reserved.</strong> An ignored field.</p> <p><strong>Total records.</strong> The total number of records available in the 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">CPF1F41 E</td> <td align="left" valign="top">Severe error occurred while addressing parameter list.</td> </tr> <tr> <td align="left" valign="top">CPF2204 E</td> <td align="left" valign="top">User profile &1 not found.</td> </tr> <tr> <td align="left" valign="top">CPF2213 E</td> <td align="left" valign="top">Not able to allocate user profile &1.</td> </tr> <tr> <td align="left" valign="top">CPF2217 E</td> <td align="left" valign="top">Not authorized to user profile &1.</td> </tr> <tr> <td align="left" valign="top">CPF2222 E</td> <td align="left" valign="top">Storage limit is greater than specified for user profile &1.</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 &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 &1 API.</td> </tr> <tr> <td align="left" valign="top">CPF3C1E E</td> <td align="left" valign="top">Required parameter &1 omitted.</td> </tr> <tr> <td align="left" valign="top">CPF3C21 E</td> <td align="left" valign="top">Format name &1 is not valid.</td> </tr> <tr> <td align="left" valign="top">CPF3C36 E</td> <td align="left" valign="top">Number of parameters, &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">CPF4AB9 E</td> <td align="left" valign="top">User certificate function not successful. </td> </tr> <tr> <td align="left" valign="top">CPF9872 E</td> <td align="left" valign="top">Program or service program &1 in library &2 ended. Reason code &3.</td> </tr> </table> <br> <hr> API introduced: V4R3 <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>