Bind (LDAP function)

From m204wiki
Jump to navigation Jump to search

<section begin=dpl_desc/><section end=dpl_desc/>

Bind is a member of the Ldap class.

This callable function creates an instance of an Ldap object, which includes a connection to a remote LDAP server host using a Janus client socket (CLSOCK) port, and authorization to use the server.

Syntax

%st = %ld:Bind( [JanusPort=name] [, LDAPServer=hostid] - [, PortNumber=num] [, UserID=login] - [, Password=pwd] [, Options=sslvalue] )

Syntax terms

%st A float variable to contain the status result of the Bind.

Zero indicates success, while a non-zero integer indicates an error, more specific information about which can often be obtained by using ErrorNumber and ErrorText.

These status values are possible:

0 Success
-1 Connection lost
-3 Other communication failure
-4 Response message contains ill-formed (unexpected) data
-5 Authorization failure: server rejected bind
-100 or less Error codes match those listed in "Network communication error codes".
%ld An Ldap object variable.
JanusPort The name of a Janus CLSOCK port.

This is an optional and name required parameter. If not provided for (for example, by a MASTER specification) in the CLSOCK port definition under which this Bind method is being used, you must specify a value here. And if you specify a value, you must include the parameter name.

The default is the MASTER port, if any is defined. However, if you omit a port name specification, and no MASTER port is defined, the request is canceled.
LDAPServer The HTTP host name (fully qualified domain name) or IP address of the target LDAP server host machine. This is an optional and name required parameter.

If the LDAP host or IP address is fully specified on the associated Janus port definition REMOTE clause, you may omit a parameter specification here. If an asterisk (*) is specified for the remote host on the port definition, you must identify the LDAP server here.

In any case, if you specify a value for this parameter:

  • You must include the parameter name.
  • The value must match the remote host, if any, specified explicitly or indicated by a pattern on the port definition.
PortNumber The TCP/IP port number of the target LDAP server. This is an optional and name required numeric parameter.

If you specify a port number value, you must:

  • Include the parameter name.
  • Specify a value that does not conflict with the port setting on the REMOTE clause in the CLSOCK port definition that this Bind method references.

If you omit PortNumber and a value, or set it to zero:

The Bind call uses the port number specified in the associated Janus port definition. If that port definition has no port number specified (or if an asterisk (*) is specified), the Bind call uses either:

  • 389 (the “well-known port” default for LDAP), if SSL encryption is not offered in the connection attempt
  • 636, if SSL is offered in the connection attempt
For more information about binding an SSL connection, see the Options parameter description, below.
UserID The string with which you log on to an LDAP server. This is an optional and name required string parameter; its default is a null string. Some LDAP servers accept a null (“anonymous”) login, and some require

a null login.

The login maximum is 255 characters.
Password The password for UserID. This is an optional and name required string parameter; its default is a null string. The pwd maximum is 255 characters.
Options This name required, optional, string argument selects whether SSL encryption is attempted for this connection. However, specifying an Options argument is only meaningful when the JANUS DEFINE command for the associated CLSOCK port specifies both the SSL and SSLOPT parameters. When both these parameters are set in the port definition, SSL encryption is offered on the connection attempt only if the Bind method explicitly requests it by setting Options='SSL'.

Options may be either of the following values, although the value must not conflict with the explicit or implicit SSL setting on the port definition. If you omit an Options argument, SSL usage depends entirely on the CLSOCK port definition. For more information about Janus SSL support, see the Janus Network Security Reference Manual.

SSL Use SSL over the connection. Setting SSL here is redundant if the port definition includes the SSL parameter but not SSLOPT, and it is invalid if the port definition excludes the SSL parameter.
NOSSL Do not use SSL over the connection. This selection is invalid if the port definition includes the SSL parameter but not SSLOPT, and it is redundant if the port definition does not include the SSL parameter.

Usage Notes

  • You can change your target LDAP server by changing the Janus port definition without having to touch your application code. That is, you can omit the port name and server name arguments, and let the port definition MASTER and REMOTE arguments do the work.

Example

The following statement uses the JANUS CLSOCK port named LDAPSOCK1 to establish an encrypted socket connection with the LDAP server whose HTTP domain name is the value assigned in the request to %ldSrv1. The ID set in %ldS1usr and the password set in %ldS1pwd are needed for login to this particular LDAP server.

%status = %ld:Bind(JanusPort='LDAPSOCK1', - LDAPServer=%ldSrv1, - UserID=%ldS1usr, - Password=%ldS1pwd, - Options='SSL')

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Bind_(LDAP_function)&oldid=47301"