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

640 lines
23 KiB
HTML
Raw Permalink 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>eimChangeRegistryUser()--Change EIM Registry User</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 -->
<!-- Created by Carol Budnik on 17 July 2001 -->
<!-- Edited by Kersten Jan 02 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!--Java sync-link-->
<script type="text/javascript" language="javascript" src="../rzahg/synch.js">
</script>
<a name="Top_Of_Page"></a>
<!-- ============================================================== -->
<!-- -->
<!-- -->
<!-- ============================================================== -->
<h2>eimChangeRegistryUser() --Change
EIM Registry User</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;eim.h&gt;
int eimChangeRegistryUser(EimHandle * <em>eim</em>,
char * <em>registryName</em>,
char * <em>registryUserName</em>,
enum EimRegistryUserAttr <em>attrName</em>,
char * <em>attrValue</em>,
enum EimChangeType <em>changeType</em>,
EimRC * <em>eimrc</em>)
</pre>
&nbsp;&nbsp;Service Program Name: QSYS/QSYEIM&nbsp;&nbsp;<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>eimChangeRegistryUser()</strong> function changes the attributes
of a registry user entry. A registry user is implicitly added to a registry
when a target association for an identity in that registry is added. However,
the attribute fields are not set at that time.</p>
<p>There are situations when more than one user can be returned on a mapping
lookup operation. Applications can choose to use information in the additional
information field to distinguish between which returned target identity to use.
For example, assume Joe has two identities in a specific registry X, joeuser
and joeadmin. An application provider can tell the administrator to add
additional information, for example, "appname-admin," to the appropriate
registry user -- in this case, joeadmin. The application can provide this
additional information on the lookup APIs, eimGetTargetFromSource() and
eimGetTargetFromIdentifier().</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>EIM Data</em></dt>
<dd>Access to EIM data is controlled by EIM access groups. LDAP administrators
also have access to EIM data. The access groups whose members have authority to
the EIM data for this API follow:
<ul>
<li>EIM Administrator</li>
<li>EIM Registries Administrator</li>
<li>EIM authority to an individual registry</li>
</ul>
<p>
<img src="delta.gif" alt="Start of change">
Must be a member of EIM Administrator or have EIM authority to an
individual registry to change the
EIM_REGUSER_PASSWORD_CRED (2), EIM_REGUSER_PWD_CRED_STATUS (3), and
EIM_REGUSER_IDCTX_CRED (4) attributes.
<img src="deltaend.gif" alt="End of change">
</p>
<p>
<img src="delta.gif" alt="Start of change">
Note that if the registry existed prior to EIM Version 3, the first time credential
information is added to a user in that registry, it must be added by a member of
EIM Administrator. After the first credential information is added, then EIM
authority to an individual registry is sufficient to change or remove credential
information for any user in the registry.
<img src="deltaend.gif" alt="End of change">
</p>
</dd>
</dl>
<br>
<!-- ============================================================== -->
<!-- -->
<!-- P A R A M E T E R S -->
<!-- -->
<!-- ============================================================== -->
<h3>Parameters</h3>
<dl><!-- ============================================================== -->
<!-- eim -->
<!-- ============================================================== -->
<dt><strong>eim</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The EIM handle returned by a previous call to eimCreateHandle(). A valid
connection is required for this function.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- registryName -->
<!-- ============================================================== -->
<dt><strong>registryName</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The name of the registry that contains this user.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- registryUserName -->
<!-- ============================================================== -->
<dt><strong>registryUserName</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The name of the user in this registry to change.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- attrName -->
<!-- ============================================================== -->
<dt><strong>attrName</strong></dt>
<dd>The attribute to be updated. Valid values are:
<br><br>
<table cellpadding="5">
<tr>
<td align="left" valign="top" nowrap><em>EIM_REGISTRYUSER_DESCRIPTION (0)</em></td>
<td align="left" valign="top">Change the registry description. Valid
<em>changeType</em> is EIM_CHG (0).</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIM_REGISTRYUSER_ADDL_INFO (1)</em></td>
<td align="left" valign="top">Add or remove additional information for this
user. Valid <em>changeType</em> is EIM_ADD (1) and EIM_RMV (2).</td>
</tr>
<tr>
<td align="left" valign="top"><img src="delta.gif" alt="Start of change"><em>EIM_REGUSER_PASSWORD_CRED (2)</em></td>
<td align="left" valign="top">Change the password credential
associated with the registry user.
Valid <em>changeType</em> is EIM_CHG (0) and EIM_RMV (2).
EIM version 3 must be supported by the local EIM APIs to specify this attribute
(see <a href="eimgetversion.htm">eimGetVersion()</a>--Get EIM Version).
<img src="deltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top"><img src="delta.gif" alt="Start of change"><em>EIM_REGUSER_PWD_CRED_STATUS (3)</em></td>
<td align="left" valign="top">Change the status of the password credential
associated with the registry user.
Valid <em>changeType</em> is EIM_ENABLE (3) and EIM_DISABLE (4). This
attribute has no affect if the EIM_REGUSER_PASSWORD_CRED (2) attribute
does not exist for the registry user.
EIM version 3 must be supported by the local EIM APIs to specify this attribute
(see <a href="eimgetversion.htm">eimGetVersion()</a>--Get EIM Version).
<img src="deltaend.gif" alt="End of change"></td>
</tr>
<tr>
<td align="left" valign="top"><img src="delta.gif" alt="Start of change"><em>EIM_REGUSER_IDCTX_CRED (4)</em></td>
<td align="left" valign="top">Change the identity context credential
associated with the registry user.
Valid <em>changeType</em> is EIM_CHG (0) and EIM_RMV (2).
EIM version 3 must be supported by the local EIM APIs to specify this attribute
(see <a href="eimgetversion.htm">eimGetVersion()</a>--Get EIM Version).
<img src="deltaend.gif" alt="End of change"></td>
</tr>
</table><br>
</dd>
<!-- ============================================================== -->
<!-- attrValue -->
<!-- ============================================================== -->
<dt><strong>attrValue</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The new value for the attribute.<br>
<br>
<p>
<img src="delta.gif" alt="Start of change">
If the attribute being changed is EIM_REGUSER_PASSWORD_CRED or
EIM_REGUSER_IDCTX_CRED and the
<em>changeType</em> is EIM_RMV (2), or the attribute being changed is
EIM_REGUSER_PWD_CRED_STATUS, this value must be NULL.
<img src="deltaend.gif" alt="End of change">
<p>
If the attribute being changed is EIM_REGUSER_IDCTX_CRED and the
<em>changeType</em> is EIM_CHG (0), then this value must be a pointer
to an EimBinaryData structure. The layout of the
EimBinaryData structure follows:
<pre>
typedef struct EimBinaryData
{
int length;
unsigned char * data;
} EimBinaryData;
</pre>
<img src="deltaend.gif" alt="End of change">
</dd>
<!-- ============================================================== -->
<!-- changeType -->
<!-- ============================================================== -->
<dt><strong>changeType</strong>&nbsp;&nbsp;(Input)</dt>
<dd>The type of change to make. This could be add, remove,
<img src="delta.gif" alt="Start of change">
change, enable, or disable.
<img src="deltaend.gif" alt="End of change">
&nbsp;<em>attrName</em> parameter indicates which type is allowed for each
attribute.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- eimrc -->
<!-- ============================================================== -->
<dt><strong>eimrc</strong>&nbsp;&nbsp;(Input/Output)</dt>
<dd>The structure in which to return error code information. If the return
value is not 0, eimrc will be set with additional information. This parameter
may be NULL. For the format of the structure, see <a href=
"eimrc.htm">EimRC - EIM return code</a>.
</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 <samp>messageCatalogMessageID</samp> field in the
<em>eimrc</em> parameter for that value.</p>
<dl><!-- ============================================================== -->
<!-- 0 -->
<!-- ============================================================== -->
<dt><strong>0</strong></dt>
<dd>Request was successful.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- EACCES -->
<!-- ============================================================== -->
<dt><strong>EACCES</strong></dt>
<dd>Access denied. Not enough permissions to access data.<br>
<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>EIMERR_ACCESS (1)</em></td>
<td align="left" valign="top">Insufficient access to EIM data.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EBADDATA -->
<!-- ============================================================== -->
<dt><strong>EBADDATA</strong></dt>
<dd>eimrc is not valid.<br>
<br>
</dd>
<!-- ============================================================== -->
<!-- EBADNAME -->
<!-- ============================================================== -->
<dt><strong>EBADNAME</strong></dt>
<dd>Registry or registry user not found or insufficient access to EIM data.<br>
<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>EIMERR_NOREG (28)</em></td>
<td align="left" valign="top">EIM Registry not found or insufficient access to
EIM data.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_NOREGUSER (29)</em></td>
<td align="left" valign="top">Registry user not found or insufficient access to
EIM data.</td>
</tr>
</table>
</dd>
<dd><br>
<!-- ============================================================== -->
<!-- EBUSY -->
<!-- ============================================================== -->
</dd>
<dt><strong>EBUSY</strong></dt>
<dd>Unable to allocate internal system object.<br>
<br>
<table cellpadding="5">
<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>
<!-- ============================================================== -->
<!-- ECONVERT -->
<!-- ============================================================== -->
<dt><strong>ECONVERT</strong></dt>
<dd>Data conversion error.<br>
<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>EIMERR_DATA_CONVERSION (13)</em></td>
<td align="left" valign="top">Error occurred when converting data between code
pages.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EINVAL -->
<!-- ============================================================== -->
<dt><strong>EINVAL</strong></dt>
<dd>Input parameter was not valid.<br>
<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>EIMERR_ATTR_INVAL (5)</em></td>
<td align="left" valign="top">Attribute name is not valid.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_CHGTYPE_INVAL (9)</em></td>
<td align="left" valign="top">This change type is not valid with the requested
attribute. Please check the API documentation.</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_HANDLE_INVAL (17)</em></td>
<td align="left" valign="top">EimHandle 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"><img src="delta.gif" alt="Start of change"><em>EIMERR_FUNCTION_NOT_SUPPORTED (70)</em></td>
<td align="left" valign="top">The specified function is not supported
by the EIM version.<img src="deltaend.gif" alt="End of change"></td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- ENOMEM -->
<!-- ============================================================== -->
<dt><strong>ENOMEM</strong></dt>
<dd>Unable to allocate required space.<br>
<br>
<table cellpadding="5">
<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>
<!-- ============================================================== -->
<!-- ENOTCONN -->
<!-- ============================================================== -->
<dt><strong>ENOTCONN</strong></dt>
<dd>LDAP connection has not been made.<br>
<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>EIMERR_NOT_CONN (31)</em></td>
<td align="left" valign="top">Not connected to LDAP. Use eimConnect() API and
try the request again.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EROFS -->
<!-- ============================================================== -->
<dt><strong>EROFS</strong></dt>
<dd>LDAP connection is for read only. Need to connect to master.<br>
<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>EIMERR_READ_ONLY (36)</em></td>
<td align="left" valign="top">LDAP connection is for read only. Use
eimConnectToMaster() to get a write connection.</td>
</tr>
</table>
<br>
</dd>
<!-- ============================================================== -->
<!-- EUNKNOWN -->
<!-- ============================================================== -->
<dt><strong>EUNKNOWN</strong></dt>
<dd>Unexpected exception.<br>
<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>EIMERR_LDAP_ERR (23)</em></td>
<td align="left" valign="top">Unexpected LDAP error. %s</td>
</tr>
<tr>
<td align="left" valign="top"><em>EIMERR_UNEXP_OBJ_VIOLATION (56)</em></td>
<td align="left" valign="top">Unexpected object violation.</td>
</tr>
<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="eimlistregistryusers.htm">eimListRegistryUsers()</a>--List EIM
Registry Users<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 changes the description and adds additional
information for the target registry user.</p>
<pre>
#include &lt;eim.h&gt;
#include &lt;stdio.h&gt;
int main(int argc, char *argv[])
{
int rc;
char eimerr[100];
EimRC * err;
EimHandle * handle;
<em>/* Get eim handle from input arg. */</em>
<em>/* This handle is already connected to EIM. */</em>
handle = (EimHandle *)argv[1];
<em>/* Set up error structure. */</em>
memset(eimerr,0x00,100);
err = (EimRC *)eimerr;
err-&gt;memoryProvidedByCaller = 100;
<em>/* Change the registry user's description */</em>
if (0 != (rc = eimChangeRegistryUser(handle,
"MyRegistry",
"mjjones",
EIM_REGISTRYUSER_DESCRIPTION,
"cool customer",
EIM_CHG,
err)))
{
printf("Change registry user error = %d", rc);
return -1;
}
<em>/* Add additional information to the registry user*/</em>
if (0 != (rc = eimChangeRegistryUser(handle,
"MyRegistry",
"mjjones",
EIM_REGISTRYUSER_ADDL_INFO,
"security officer",
EIM_ADD,
err)))
{
printf("Change registry user error = %d", rc);
return -1;
}
<em>/* Add additional information to the registry user*/</em>
if (0 != (rc = eimChangeRegistryUser(handle,
"MyRegistry",
"mjjones",
EIM_REGISTRYUSER_ADDL_INFO,
"administrator",
EIM_ADD,
err)))
{
printf("Change registry user error = %d", rc);
return -1;
}
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>
Reference in New Issue View Git Blame Copy Permalink