Overview_of_LDAP_API_Use

   An application generally uses the C LDAP API in four simple
   steps.

   o  Initialize an LDAP session with a primary LDAP server. The
      ldap_init() function returns a handle to the session, allowing
      multiple connections to be open at once.

   o  Authenticate to the LDAP server. The ldap_bind() function
      supports a variety of authentication methods.

   o  Perform some LDAP operations and obtain some results. The
      ldap_search() function returns results that can be parsed
      by ldap_parse_result(), ldap_first_entry(),  and ldap_next_
      entry().

   o  Close the session. The ldap_unbind() function closes the
      connection.

   Operations can be performed either synchronously or
   asynchronously. The names of the synchronous functions end
   in _s. For example, a synchronous search can be completed by
   calling ldap_search_s(). An asynchronous search can be initiated
   by calling ldap_search(). All synchronous functions return an
   indication of the outcome of the operation (for example, the
   constant LDAP_SUCCESS or some other error code). The asynchronous
   functions make available to the caller the message id of the
   operation initiated. This id can be used in subsequent calls
   to ldap_result() to obtain the result(s) of the operation. An
   asynchronous operation can be abandoned by calling ldap_abandon()
   or ldap_abandon_ext().

   Results and errors are returned in an opaque structure called
   LDAPMessage. Functions are provided to parse this structure,
   step through entries and attributes returned. Functions are also
   provided to interpret errors.

   LDAPv3 servers may return referrals to other servers. By default,
   implementations of this API will attempt to follow referrals
   automatically for the application. This behavior can be disabled
   globally (using the ldap_set_option() call) or on a per-request
   basis through the use of a server control.

   As in the LDAPv3 protocol, all DNs and string values that are
   passed into or produced by the C LDAP API are represented as
   UTF-8 characters. Conversion functions are described in Encoded
   ASN.1.

   For compatibility with existing applications, implementations of
   this API will, by default, use Version 2 of the LDAP protocol.
   Applications that intend to take advantage of LDAPv3 features
   will need to use the ldap_set_option() call with a LDAP_OPT_
   PROTOCOL_VERSION switch set to Version 3.

   The file LDAP_EXAMPLE.C in SYS$EXAMPLES contains an example
   program that demonstrates how to use the LDAP API on OpenVMS.