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.