eimSetConfigurationExt()--Set EIM Configuration Extended

Syntax

 #include <eim.h>

 int eimSetConfigurationExt(EimConfigInfo  * configInfo,
                            EimRC          * eimrc)

  Service Program Name: QSYS/QSYEIM

  Default Public Authority: *USE

  Threadsafe: Yes

The eimSetConfigurationExt() function sets the configuration information for use by the system.

Authorities and Locks

The caller of the API must have *SECADM special authority.

Parameters

configInfo (Input)

The configuration information to be set.

The EimConfigInfo structure contains the configuration information.

For EIM_CONFIG_FORMAT_0 (0) configuration format, the config field must contain an EimConfigFormat0 structure.

The structure layouts follow:

   enum EimConfigFormat {
       EIM_CONFIG_FORMAT_0            /* Information is in configuration
                                         format 0.                      */
   };

   typedef struct EimConfigFormat0
   {
        char * ldapURL;               /* URL for EIM domain controller. */
        char * localRegistry;         /* Local system registry name.    */
        char * kerberosRegistry;      /* Kerberos registry name.        */
        char * x509Registry;          /* X.509 registry name.           */
   }  EimConfigFormat0;

   typedef struct EimConfigInfo
   {
        enum EimConfigFormat format;  /* Format of the config info.     */
        int                  enable;  /* Indicate if able to establish
                                         new connections in order to
                                         participate in EIM domain
                                         0 = not enabled
                                         1 = enabled                    */
        int                  ccsid;   /* CCSID of input data. If 0 or
                                         65535, default job CCSID will
                                         be used.                       */
        union {
            EimConfigFormat0   format0;
        } config;                     /* Configuration information      */
   }  EimConfigInfo;

Detail description for the configuration information:

ldapURL

A uniform resource locator (URL) that contains the EIM configuration information for the EIM domain controller. This information will be used for all EIM operations. The maximum size for this URL is 1000 bytes.

Possible values are:

NULL	A value of NULL indicates that it should not change.
EIM_CONFIG_NONE	(*NONE) This value indicates that this system is not configured for EIM.
ldapURL	A URL that contains EIM domain controller information.

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 for the domain entry.
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

localRegistry
The local EIM system registry name. The maximum size for this registry name is 256 bytes.

Possible values are:

NULL A value of NULL indicates that it should not change.

EIM_CONFIG_NONE (*NONE) This value indicates that there is no local system registry.

registry The local EIM system registry name.

kerberosRegistry

The EIM Kerberos registry name. The maximum size for this registry name is 256 bytes.

Possible values are:

NULL	A value of NULL indicates that it should not change.
EIM_CONFIG_NONE	(*NONE) This value indicates that there is no kerberos registry for EIM.
registry	The EIM Kerberos registry name. This is the Kerberos realm name.

x509Registry

The EIM X.509 registry name. The maximum size for this registry name is 256 bytes.

Possible values are:

NULL	A value of NULL indicates that it should not change.
EIM_CONFIG_NONE	(*NONE) This value indicates that there is no X.509 registry for EIM.
registry	The EIM X.509 registry name. This is the registry that will be used when adding source associations for user certificates to the EIM identifier.

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_CCSID_INVAL (8)	CCSID is outside of valid range or CCSID is not supported.
EIMERR_CHAR_INVAL (21)	A restricted character was used in the object name. Check the API for a list of restricted characters.
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.
EIMERR_CONFIG_FORMAT_INVAL (68)	Configuration format is not valid.

ENAMETOOLONG

ldapURL or registry name is too long.

EIMERR_REGNAME_SIZE (39)	Registry name is too large.
EIMERR_URL_SIZE (51)	Configuration URL is too large.

ENOMEM

Unable to allocate required space.

EIMERR_NOMEM (27)

No memory available. Unable to allocate required space.

EUNKNOWN

Unexpected exception.

EIMERR_LDAP_ERR (23)	Unexpected LDAP error. %s
EIMERR_UNKNOWN (44)	Unknown error or unknown system state.

Related Information

eimRetrieveConfiguration() --Retrieve EIM Configuration

Example

The following example sets the configuration information but it is not enabled.

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;
    EimConfigInfo configInfo;

    /* Set up error structure.                  */
    memset(eimerr,0x00,100);
    err = (EimRC *)eimerr;
    err->memoryProvidedByCaller = 100;

    /* Set up config information.               */
    configInfo.format = EIM_CONFIG_FORMAT_0;
    configInfo.enable = 0;
    configInfo.ccsid = 0;
    configInfo.config.format0.ldapURL = 
      "ldap://mysystem:389/ibm-eimDomainName=myEIMDomain,o=mycompany,c=us";
    configInfo.config.format0.localRegistry = "mysystem";
    configInfo.config.format0.kerberosRegistry = "krbprin";
    configInfo.config.format0.x509Registry = "x509reg";

    /* Set config info, but it is disabled.     */
    if (0 != (rc = eimSetConfigurationExt(&.configInfo,
                                          err)))
        printf("Set configuration error = %d", rc);

    return 0;
}

In this example, the configuration information is not changed but it is now enabled for use.

#include <eim.h>
#include <stdio.h>

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

    /* Set up error structure.                  */
    memset(eimerr,0x00,100);
    err = (EimRC *)eimerr;
    err->memoryProvidedByCaller = 100;

    /* Set up config information.               */
    configInfo.format = EIM_CONFIG_FORMAT_0;
    configInfo.enable = 1;
    configInfo.ccsid = 0;
    configInfo.config.format0.ldapURL = NULL;
    configInfo.config.format0.localRegistry = NULL;
    configInfo.config.format0.kerberosRegistry = NULL;
    configInfo.config.format0.x509Registry = NULL;

    /* Enable configuration info.               */
    if (0 != (rc = eimSetConfigurationExt(&configInfo,
                                          err)))
        printf("Set configuration error = %d", rc);

    return 0;
}

API introduced: V5R3

[ Back to top | Security APIs | APIs by category ]