eimCreateHandle()--Create an EIM Handle
Syntax
#include <eim.h> int eimCreateHandle(EimHandle * eim, char * ldapURL, EimRC * eimrc)Service Program Name: QSYS/QSYEIM
Default Public Authority: *USE
Threadsafe: Yes
The eimCreateHandle() function is used to allocate an EimHandle structure, which is used to identify the EIM connection and to maintain per-connection information. The EimHandle structure should be passed on subsequent calls to other EIM operations.
Authorities and Locks
If a NULL is not passed for the ldapURL parameter, then the caller of the API must have *SECADM special authority.
Parameters
- eim (Output)
-
The pointer to an EIM handle to be returned. This handle is used as input
for other EIM APIs. The handle is temporary; you can use it only in the job
that created it.
- ldapURL (Input)
- A uniform resource locator (URL) that contains the EIM host information.
A NULL parameter indicates that the ldapURL information
set by the eimSetConfiguration() API should be used.
This URL has the following format:
ldap://host:port/dn or ldaps://host:port/dn
where:
- host:port is the name of the host on which the EIM domain controller is running with an optional port number.
- dn is the distinguished name of the domain to work with.
- ldaps indicates that this host/port combination uses SSL and TLS.
Examples:
- ldap://systemx:389/ibm-eimDomainName=myEimDomain,o=myCompany,c=us
- ldaps://systemy:636/ibm-eimDomainName=thisEimDomain
- eimrc (Input/Output)
-
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 EimRC--EIM Return Code
Parameter.
Return Value
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.
- 0
- Request was successful.
- EACCES
- Access denied.
EIMERR_AUTH_ERR (7) Insufficient authority for the operation.
- EBADDATA
- eimrc is not valid.
- EBUSY
- Unable to allocate internal system object.
EIMERR_NOLOCK (26) Unable to allocate internal system object.
- ECONVERT
- Data conversion error.
EIMERR_DATA_CONVERSION (13) Error occurred when converting data between code pages.
- EINVAL
- Input parameter was not valid.
EIMERR_PARM_REQ (34) Missing required parameter. Please check API documentation. EIMERR_PTR_INVAL (35) Pointer parameter is not valid. EIMERR_URL_NODN (45) URL has no dn (required). EIMERR_URL_NODOMAIN (46) URL has no domain (required). EIMERR_URL_NOHOST (47) URL does not have a host. EIMERR_URL_NOTLDAP (49) URL does not begin with ldap. EIMERR_INVALID_DN (66) Distinguished Name (DN) is not valid.
- ENOMEM
- Unable to allocate required space.
EIMERR_NOMEM (27) No memory available. Unable to allocate required space.
- ENOSYS
- EIM is not configured.
EIMERR_NOTCONFIG (30) EIM environment is not configured. Run eimSetConfiguration() API and try the request again.
- EUNKNOWN
- Unexpected exception.
EIMERR_LDAP_ERR (23) Unexpected LDAP error. %s EIMERR_UNKNOWN (44) Unknown error or unknown system state.
Related Information
- eimDestroyHandle()--Destroy an EIM
Handle
- eimGetAttribute()--Get EIM Attributes
- eimSetAttribute()--Set EIM Attributes
- eimConnectToMaster()--Connect to EIM
Master Domain
- eimConnect()--Connect to EIM
Domain
Example
The following example creates an EIM handle.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <eim.h> #include <stdio.h> int main(int argc, char *argv[]) { int rc; char eimerr[100]; EimRC * err; EimHandle handle; EimHandle handle2; char * ldapURL = "ldap://eimsystem:389/ibm-eimDomainName=myEimDomain,o=mycompany,c=us"; /* Set up error structure. */ memset(eimerr,0x00,100); err = (EimRC *)eimerr; err->memoryProvidedByCaller = 100; /* Create a new eim handle. Use the eim configuration URL */ if (0 != (rc = eimCreateHandle(&handle, NULL, err))) printf("Create handle error = %d", rc); /* Create a new eim handle. Use the specified URL */ if (0 != (rc = eimCreateHandle(&handle2, ldapURL, err))) printf("Create handle error = %d", rc); return 0; }
API introduced: V5R2
[ Back to top | Security APIs | APIs by category ]