eimCreateHandle()--Create an EIM Handle

 #include <eim.h>

 int eimCreateHandle(EimHandle      * eim,
                     char           * ldapURL,
		     EimRC          * eimrc)

 

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

See Code disclaimer information for information pertaining to code examples.

The following example creates an EIM handle.

#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;
}