573 lines
20 KiB
HTML
573 lines
20 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>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>
|
|
Syntax
|
|
|
|
<pre>
|
|
#include <qsyeimapi.h>
|
|
|
|
#include <eim.h>
|
|
|
|
int QsySetEIMConnectInfo(enum QsyEimConnectSystem <em>connectSystem</em>,
|
|
QsyEimConnectionInfo <em>connectInfo</em>,
|
|
EimRc * <em>eimrc</em>)
|
|
|
|
</pre>
|
|
|
|
Service Program Name: QSYS/QSYEIMAPI<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
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 <eim.h>
|
|
#include <qsyeimapi.h>
|
|
|
|
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->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>
|
|
|