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

493 lines
15 KiB
HTML
Raw Blame History

<!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>QsyRetrieveDigitalIDConfig()--Retrieve Digital ID Configuration Information</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 -->
<!-- Edited by Kersten Jan 02 -->
<!-- Created by Therese Dalton on 17 July 2001 -->
<!-- End header records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!--Java sync-link-->
<script type="text/javascript" language="javascript" src="../rzahg/synch.js">
</script>
<!-- ============================================================== -->
<!-- -->
<!-- -->
<!-- ============================================================== -->
<h2>QsyRetrieveDigitalIDConfig()--Retrieve Digital ID Configuration Information</h2>
<!-- ============================================================== -->
<!-- -->
<!-- S Y N T A X / P A R M T A B L E -->
<!-- -->
<!-- ============================================================== -->
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;<img src="delta.gif" alt="Start of change">Syntax for QsyRetrieveDigitalIDConfig:<br>
<pre>
#include &lt;qsydigid.h&gt;
void QsyRetrieveDigitalIDConfig
(void *<em>Receiver_variable</em>,
int <em>Length_of_receiver_variable</em>,
char *<em>Format_name</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>
<!-- ============================================================== -->
<!-- -->
<!-- D E S C R I P T I O N -->
<!-- -->
<!-- ============================================================== -->
<p>The Retrieve Digital ID Configuration Information (QsyRetrieveDigitalIDConfig)
API will retrieve digital ID configuration information. This is
the information that defines the Lightweight Directory Access Protocol (LDAP) server
for where to store digital certificates, and connection information
for the server.</p>
<!-- ============================================================== -->
<!-- -->
<!-- A U T H O R I T I E S A N D L O C K S -->
<!-- -->
<!-- ============================================================== -->
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>QSYDIGID Validation List Object</em></dt>
<dd>*USE</dd>
<dt><em>QUSRSYS Library</em></dt>
<dd>*EXECUTE</dd>
</dl>
<p><strong>Note:</strong> For the bind password to be returned, the
user must have *USE, *ADD, and *UPD authorities to the validation list.</p>
<!-- ============================================================== -->
<!-- -->
<!-- P A R A M E T E R S -->
<!-- -->
<!-- ============================================================== -->
<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.</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. The minimum length is 8
bytes.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the configuration information to be returned.</p>
<p>The following format name may be used:</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em><a href="#HDRRDCI100">RDCI0100</a></em></td>
<td align="left" valign="top">Digital ID configuration information.</td>
</tr>
</table>
</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="HDRRDCI100">RDCI0100 Format</a></h3>
<p>The following table describes the information that is returned in the
receiver variable for the RDCI0100 format. For detailed descriptions of the
fields, see <a href="#HDRRDCIFD">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%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Bytes returned</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">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">8</td>
<td align="center" valign="top" width="10%">8</td>
<td align="left" valign="top" width="20%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Enabled indicator</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="center" valign="top">9</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Use SSL indicator</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Port number</td>
</tr>
<tr>
<td align="center" valign="top">16</td>
<td align="center" valign="top">10</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to server name</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">Length of server 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">Offset to directory DN</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of directory DN</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">Offset to bind DN</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">Length of bind DN</td>
</tr>
<tr>
<td align="center" valign="top">40</td>
<td align="center" valign="top">28</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to bind password</td>
</tr>
<tr>
<td align="center" valign="top">44</td>
<td align="center" valign="top">2C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of bind password</td>
</tr>
<tr>
<td align="center" valign="top"></td>
<td align="center" valign="top"></td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Server name</td>
</tr>
<tr>
<td align="center" valign="top"></td>
<td align="center" valign="top"></td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Directory DN</td>
</tr>
<tr>
<td align="center" valign="top"></td>
<td align="center" valign="top"></td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Bind DN</td>
</tr>
<tr>
<td align="center" valign="top"></td>
<td align="center" valign="top"></td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Bind password</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRRDCIFD">Field Descriptions</a></h3>
<p><strong>Bytes available.</strong> The number of bytes of data available to
be returned. All available data is returned if enough space is provided.</p>
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
<p><strong>Bind DN.</strong> The Distinguished Name (DN) of the entry used when
binding to the LDAP server.
<p><strong>Bind password.</strong> The password to use in association with
the bind DN.
<p><strong>Directory DN.</strong> The DN for where in the LDAP server the
user certificates are to be stored.
<p><strong>Enabled indicator.</strong> Specifies whether or not the configuration
information is enabled for use.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The configuration information is not enabled.
Digital certificates for users will be stored locally.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">The configuration information is enabled.
If Enterprise Identity Mapping (EIM) is configured and operational, then
digital certificates for users will be stored in LDAP and the mapping from
the certificate to a user profile will be stored in EIM. </td>
</tr>
</table>
<p><strong>Length of bind DN.</strong> The length of the field that
contains the bind distinguished name (DN).</p>
<p><strong>Length of bind password.</strong> The length of the field that
contains the bind password.</p>
<p><strong>Length of directory DN.</strong> The length of the field that
contains the directory distinguished name (DN).</p>
<p><strong>Length of server name.</strong> The length of the field that
contains the server name.</p>
<p><strong>Port number.</strong> The port number to use when connecting to the
LDAP server.</p>
<p><strong>Offset to bind DN.</strong> The offset to the field that
contains the bind distinguished name (DN).</p>
<p><strong>Offset to bind password.</strong> The offset to the field that
contains the bind password.</p>
<p><strong>Offset to directory DN.</strong> The offset to the field that
contains the directory distinguished name (DN).</p>
<p><strong>Offset to server name.</strong> The offset to the field that
contains the server name.</p>
<p><strong>Reserved.</strong> Reserved data.
<p><strong>Server name.</strong> The domain name of the LDAP server on which
to store user certificates.
<p><strong>Use SSL indicator.</strong> Specifies whether or not Secure Sockets
Layer (SSL) is used for secure access when connecting to the LDAP server.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">A secure connection using SSL is not
used when connecting to the LDAP server.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">A secure connection using SSL is
used when connecting to the LDAP server. Digital Certificate Manager (DCM)
must be used to assign a certificate to the
IBM Directory Server client (QIBM_GLD_DIRSRV_CLIENT) application.
</td>
</tr>
</table>
<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">CPF22F0 E</td>
<td align="left" valign="top">Unexpected errors occurred during processing.</td>
</tr>
<tr>
<td valign="top">CPF3BFF E</td>
<td 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">CPF3C1D E</td>
<td align="left" valign="top">Length specified in parameter &amp;1 not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C19 E</td>
<td align="left" valign="top">Error occurred with receiver variable
specified.</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">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is 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">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">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: V5R3
<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>
Reference in New Issue View Git Blame Copy Permalink