QsyGetEIMHandle()--Get EIM Handle Connected For System

 #include <qsyeimapi.h>

 #include <eim.h>

 int QsyGetEIMHandle(EimHandle      * eim,,
                          EimRc      * eimrc)
 

The QsyGetEIMHandle() function is used to allocate an EimHandle structure that is connected to EIM. The EIM host information used will be the ldapURL information set by the eimSetConfiguration() API. The connection information used will be the connectInfo set by the QsySetEIMConnectInfo() API. The EimHandle structure should be passed on subsequent calls to other EIM operations. When the handle is no longer needed, it should be destroyed by calling eimDestroyHandle() function.

Authorities and Locks

Authority required

*ALLOBJ and *SECADM special authorities

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.

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 (3028)

eimrc is not valid.

EBUSY (3029)

Unable to allocate internal system object.

EIMERR_NOLOCK (26)

Unable to allocate internal system object.

ECONVERT (3490)

Data conversion error.

EIMERR_DATA_CONVERSION (13)

Error occurred when converting data between code pages.

EINVAL (3021)

Input parameter was not valid.

EIMERR_SSL_REQ (42)	The system is configured to connect to a secure port. EimSSLInfo is required.
EIMERR_NOT_SECURE (32)	The system is not configured to connect to a secure port. Connection type of EIM_CLIENT_AUTHENTICATION is not valid..
EIMERR_URL_NOTLDAP (49)	URL does not begin with ldap.
EIMERR_URL_NOHOST (47)	URL does not have a host.

ENOMEM (3460)

Unable to allocate required space.

EIMERR_NOMEM (27)

No memory available. Unable to allocate required space.

ENOSYS (3470)

System not configured.

EIMERR_OS400_NOTSET_CONFIG (5007)	EIM connection information is not set for this system. Run QsySetEIMConnectInfo() API and try the request again.
EIMERR_OS400_NOTSET_MASTER (5008)	EIM connection information is not set for the master system. Run QsySetEIMConnectInfo() API and try the request again.

EUNKNOWN (3474)

Unexpected exception.

EIMERR_UNKNOWN (44)

Unknown error or unknown system state.

Related Information

• QsyGetEIMConnectInfo()--Get EIM Connect Information
  
• QsySetEIMConnectInfo()--Set EIM Connect Information
  
• eimDestroyHandle()--Destroy an EIM Handle
  

Example

See Code disclaimer information for information pertaining to code examples.

The following example will get connection information used by the operating system.

#include <eim.h>
#include <qsyeimapi.h>
            

int main(int argc, char *argv[])
{
    int rc;
    char       eimerr[100];
    EimRC     *err;
    EimHandle     handle;

    err = (EimRC *)eimerr;
    err->memoryProvidedByCaller = 100;

    if (0 != (rc = QsyGetEIMHandle(&handle,
                                        err)))
    {
        printf("Get connected handle error = %d", rc);
        return -1;
    }

    ...  other eim operations


    if (0 != (rc = eimDestroyHandle(&handle,
                                        err)))
    {
        printf("Destroy eim handle error = %d", rc);
        return -1;
    }
    
              
    return 0;
}