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

573 lines
20 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!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>QsySetEIMConnectInfo()--Set EIM Connect 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 Carol Budnik 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>QsySetEIMConnectInfo()--Set EIM
Connect 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;Syntax
<pre>
#include &lt;qsyeimapi.h&gt;
#include &lt;eim.h&gt;
int QsySetEIMConnectInfo(enum QsyEimConnectSystem <em>connectSystem</em>,
QsyEimConnectionInfo <em>connectInfo</em>,
EimRc * <em>eimrc</em>)
</pre>
&nbsp;&nbsp;Service Program Name: QSYS/QSYEIMAPI<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<!-- ============================================================== -->
<!-- -->
<!-- D E S C R I P T I O N -->
<!-- -->
<!-- ============================================================== -->
<p>The <strong>QsySetEIMConnectInfo()</strong> function defines the connection
information that will be used by the operating system when it needs to
connect to the EIM domain that is configured for this system or for the master
system. EIM configuration information is set using eimSetConfiguration().</p>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- A U T H O R I T I E S A N D L O C K S -->
<!-- -->
<!-- ============================================================== -->
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Authority required</em></dt>
<dd>*ALLOBJ and *SECADM special authorities</dd>
</dl>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- P A R A M E T E R S -->
<!-- -->
<!-- ============================================================== -->
<h3>Parameters</h3>
<dl><!-- ============================================================== -->
<!-- connectSystem -->
<!-- ============================================================== -->
<dt><strong>connectSystem</strong></dt>
<dd>(Input)
<p>The system defined by eimSetConfiguration(). If the configured system is a
replica system and EIM updates will be done, then connection information for
the master system must also be defined.</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>QSY_EIM_CONFIG (0)</em></td>
<td align="left" valign="top">The specified connection information will be used
to connect to the EIM domain that is configured for this system.</td>
</tr>
<tr>
<td align="left" valign="top"><em>QSY_EIM_MASTER (1)</em></td>
<td align="left" valign="top">The specified connection information will be used
to connect to the master system.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- connectInfo -->
<!-- ============================================================== -->
<dt><strong>connectInfo</strong></dt>
<dd>(Input)
<p>The connection information. EIM uses ldap. The connection information
indicates the required information to bind to ldap. There are two types of
connections supported, simple bind and Kerberos.</p>
<p>If the system is configured to connect to a secure port then Digital
Certificate Manager (DCM) must be used to assign a certificate to the
Enterprise Identity Mapping Client (QIBM_QSY_EIM_CLIENT) application.</p>
<p>For QSY_EIM_SIMPLE (0) connect type, the <em>connectInfo</em> field must
contain an EimSimpleConnectInfo structure with a binddn and password. The
binddn cannot be longer than 400 bytes. The password cannot be longer than 174
bytes. EimPasswordProtect is used to determine the level of password protection
on the ldap bind.</p>
<table cellpadding="5">
<!-- cols="40 60" -->
<tr>
<td align="left" valign="top"><em>EIM_PROTECT_NO (0)</em></td>
<td align="left" valign="top">The "clear-text" password is sent on the
bind.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIM_PROTECT_CRAM_MD5 (1)</em></td>
<td align="left" valign="top">The protected password is sent on the bind. The
server side must support cram-md5 protocol in order to send the protected
password.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>EIM_PROTECT_CRAM_MD5_OPTIONAL
(2)</em></td>
<td align="left" valign="top">The protected password will be sent on the bind
if the cram-md5 protocol is supported. Otherwise, the "clear-text" password is
sent.</td>
</tr>
</table>
<p>For QSY_EIM_KERBEROS_KEYTAB (1), connect type, the <em>connectInfo</em>
field must contain a QsyEimKerberosKeyTab structure with a keytab file name,
principal, and realm. Each of the keytab file name, principal, and realm cannot
be longer than 400 bytes.</p>
<p>For QSY_EIM_KERBEROS_PWD (2), connect type, the <em>connectInfo</em> field
must contain a QsyEimKerberosPassword structure with a principal, realm, and
password. The principal and realm cannot be longer than 400 bytes. The password
cannot be longer than 174 bytes.</p>
<p>For QSY_EIM_REMOVE_CONNECT_INFO (3), connect type, the <em>connectInfo</em>
field must be zeros. The connection information that is currently defined for
the specified connection system will be removed.</p>
<p>Following are the structure layouts:</p>
<pre>
#pragma enumsize(4)
enum QsyEimConnectType {
QSY_EIM_SIMPLE,
QSY_EIM_KERBEROS_KEYTAB,
QSY_EIM_KERBEROS_PWD,
QSY_EIM_REMOVE_CONNECT_INFO
};
enum EimPasswordProtect {
EIM_PROTECT_NO,
EIM_PROTECT_CRAM_MD5,
EIM_PROTECT_CRAM_MD5_OPTIONAL
};
typedef struct EimSimpleConnectInfo
{
enum EimPasswordProtect protect;
char reserved[12];
char * bindDn;
char * bindPw;
} EimSimpleConnectInfo;
typedef struct QsyEimKerberosKeyTab
{
char * keyTabFile;
char * principal;
char * realm;
}
typedef struct QsyEimKerberosPassword
{
char * principal;
char * realm;
char * password;
}
typedef struct QsyEimConnectionInfo
{
enum QsyEimConnectType type;
union {
EimSimpleConnectInfo simpleCreds;
QsyEimKerberosKeyTab kerberosKeyTab;
QsyEimKerberosPassword kerberosPassword;
} connectInfo;
} QsyEimConnectionInfo;
</pre>
</dd>
<!-- ============================================================== -->
<!-- eimrc -->
<!-- ============================================================== -->
<dt><strong>eimrc</strong></dt>
<dd>(Input/Output)
<p>The structure in which to return error code information. If the return value
is not 0, eimrc is set with additional information. This parameter may be NULL.
For the format of the structure, see <a href="eimrc.htm">EimRC--EIM Return Code
Parameter</a>.</p>
</dd>
</dl>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- R E T U R N V A L U E -->
<!-- -->
<!-- ============================================================== -->
<h3>Return Value</h3>
<p>The return value from the API. Following each return value is the list of
possible values for the messageCatalogMessageID field in the eimrc parameter
for that value.</p>
<dl><!-- ============================================================== -->
<!-- 0 -->
<!-- ============================================================== -->
<dt><strong>0</strong></dt>
<dd>Request was successful.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- EACCESS -->
<!-- ============================================================== -->
<dt><strong>EACCESS (3401)</strong></dt>
<dd>Access denied. Not enough permissions to set connection information.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_AUTH_ERR (7)</em></td>
<td align="left" valign="top">Insufficient authority for the operation.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EBADDATA -->
<!-- ============================================================== -->
<dt><strong>EBADDATA (3028)</strong></dt>
<dd>eimrc is not valid.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- EBUSY -->
<!-- ============================================================== -->
<dt><strong>EBUSY (3029)</strong></dt>
<dd>Unable to allocate internal system object.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_NOLOCK (26)</em></td>
<td align="left" valign="top">Unable to allocate internal system object.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EINVAL -->
<!-- ============================================================== -->
<dt><strong>EINVAL (3021)</strong></dt>
<dd>Input parameter was not valid.<br>
<br>
<table cellpadding="5">
<!-- cols="40 60" -->
<tr>
<td align="left" valign="top"><em>EIMERR_PROTECT_INVAL (22)</em></td>
<td align="left" valign="top">The protect parameter in EimSimpleConnectInfo is
not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_PARM_REQ (34)</em></td>
<td align="left" valign="top">Missing required parameter. Please check API
documentation.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_PTR_INVAL (35)</em></td>
<td align="left" valign="top">Pointer parameter is not valid.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>EIMERR_OS400_CONN_SYS_INVAL
(5002)</em></td>
<td align="left" valign="top">Connection system is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_RESERVE_INVAL (57)</em></td>
<td align="left" valign="top">Reserved field is not valid.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ENAMETOOLONG -->
<!-- ============================================================== -->
<dt><strong>ENAMETOOLONG (3486)</strong></dt>
<dd>Input parameter is too long.<br>
<br>
<table cellpadding="5">
<!-- cols="40 60" -->
<tr>
<td align="left" valign="top"><em>EIMERR_OS400_BINDDN_SIZE (5001)</em></td>
<td align="left" valign="top">Bind DN is too large.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_OS400_KEYTAB_SIZE (5003)</em></td>
<td align="left" valign="top">Kerberos keytab file name is too large.</td>
</tr>
<tr>
<td align="left" valign="top" nowrap><em>EIMERR_OS400_PRINCIPAL_SIZE
(5004)</em></td>
<td align="left" valign="top">Kerberos principal is too large.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_OS400_PWD_SIZE (5005)</em></td>
<td align="left" valign="top">Kerberos password is too large.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_OS400_REALM_SIZE (5006)</em></td>
<td align="left" valign="top">Kerberos realm is too large.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ENOMEM -->
<!-- ============================================================== -->
<dt><strong>ENOMEM (3460)</strong></dt>
<dd>Unable to allocate required space.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_NOMEM (27)</em></td>
<td align="left" valign="top">No memory available. Unable to allocate required
space.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ENOTSUP -->
<!-- ============================================================== -->
<dt><strong>ENOTSUP (3440)</strong></dt>
<dd>Connection type is not supported.<br>
<br>
<table cellpadding="5">
<!-- cols="30 70" -->
<tr>
<td align="left" valign="top"><em>EIMERR_CONN_NOTSUPP (12)</em></td>
<td align="left" valign="top">Connection type is not supported.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EUNKNOWN -->
<!-- ============================================================== -->
<dt><strong>EUNKNOWN (3474)</strong></dt>
<dd>Unexpected exception.<br>
<br>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td align="left" valign="top"><em>EIMERR_UNKNOWN (44)</em></td>
<td align="left" valign="top">Unknown error or unknown system state.</td>
</tr>
</table>
</dd>
</dl>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- U S A G E N O T E S -->
<!-- -->
<!-- ============================================================== -->
<!-- ============================================================== -->
<!-- -->
<!-- R E L A T E D I N F O R M A T I O N -->
<!-- -->
<!-- ============================================================== -->
<h3>Related Information</h3>
<ul>
<li><a href="qsygeteimconnectinfo.htm">QsyGetEIMConnectInfo()</a>--Get EIM
Connect Information<br>
<br>
</li>
</ul>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- E X A M P L E -->
<!-- -->
<!-- ============================================================== -->
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following example will set connection information used by the operating
system.</p>
<pre>
#include &lt;eim.h&gt;
#include &lt;qsyeimapi.h&gt;
int main(int argc, char *argv[])
{
int rc;
enum QsyEimConnectSystem *connectSys;
QsyEimConnectionInfo connectInfo;
char eimerr[100];
EimRC *err;
/* Get the system that the connection information is for. */
connectSys = (enum QsyEimConnectSystem *)argv[1];
/* Get the type of the connection information. */
connectInfo.type = *((enum QsyEimConnectType *)argv[2]);
/* Set the connection information based on the connection type.
switch (connectInfo.type) /* Determine connect type. */
{
case QSY_EIM_SIMPLE:
{
connectInfo.connectInfo.simpleCreds.protect =
*((enum EimPasswordProtect *)argv[3]);
connectInfo.connectInfo.simpleCreds.bindDn = argv[4];
connectInfo.connectInfo.simpleCreds.bindPw = argv[5];
break;
}
case QSY_EIM_KERBEROS_KEYTAB:
{
connectInfo.connectInfo.kerberosKeyTab.keyTabFile = argv[3];
connectInfo.connectInfo.kerberosKeyTab.principal = argv[4];
connectInfo.connectInfo.kerberosKeyTab.realm = argv[5];
break;
}
case QSY_EIM_KERBEROS_PWD:
{
connectInfo.connectInfo.kerberosPassword.principal = argv[3];
connectInfo.connectInfo.kerberosPassword.realm = argv[4];
connectInfo.connectInfo.kerberosPassword.password = argv[5];
break;
}
case QSY_EIM_REMOVE_CONNECT_INFO:
{
connectInfo.connectInfo.kerberosPassword.principal = NULL;
connectInfo.connectInfo.kerberosPassword.realm = NULL;
connectInfo.connectInfo.kerberosPassword.password = NULL;
break;
}
} /* end determine connect type. */
err = (EimRC *)eimerr;
err-&gt;memoryProvidedByCaller = 100;
if (0 != (rc = QsySetEIMConnectInfo(*connectSys,
connectInfo,
err)))
printf("Set connection information error = %d", rc);
return 0;
}
</pre>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- F O O T E R -->
<!-- -->
<!-- ============================================================== -->
<hr>
API introduced: V5R2
<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>