init Function

This function initializes a session with an LDAP server. This actually establishes a connection with the LDAP server.

Syntax

DBMS_LDAP.init (

hostname  IN VARCHAR2,
portnum   IN PLS_INTEGER )

RETURN SESSION;

Parameters

Table 20-4 init Function Parameters

Parameter	Description
hostname (IN)	Contains a space-separated list of host names or dotted strings representing the IP address of hosts running an LDAP server. Each host name in the list may include a port number, which is separated from the host with a colon (:). The hosts are tried in the order listed, stopping with the first one to which a successful connection is made.
portnum (IN)	Contains the TCP port number to connect to. If a host includes a port number, this parameter is ignored. If this parameter is not specified and the host name does not contain the port number, the default port number 389 is assumed.

Return Values

Table 20-5 init Function Return Values

Value	Description
SESSION	A handle to an LDAP session that can be used for further calls into the API.

Exceptions

Table 20-6 init Function Exceptions

Exception	Description
init_failed	Raised when there is a problem contacting the LDAP server.
ts_mode_not_supported	Raised if DBMS_LDAP.init is invoked from a user session that is logged onto the database using an MTS service.
general_error	For all other errors. The error string associated with the exception describes the error in detail.

Usage Notes

DBMS_LDAP.init is the first function that should be called in order to establish a session to the LDAP server. DBMS_LDAP.init returns a session handle, a pointer to an opaque structure that must be passed to subsequent calls pertaining to the session. This routine returns NULL and raises the INIT_FAILED exception if the session cannot be initialized. Subsequent to the call to init, the connection must be authenticated using DBMS_LDAP.bind_s or DBMS_LDAP.simple_bind_s.

See Also: "simple_bind_s Function" "bind_s Function"