FindStringInCommonName (LDAP function)

Retrieve substring matching records from LDAP directory (LDAP class)

This callable function does substring matching on text attributes of LDAP directory entries. It invokes a search of all entries at a target LDAP server that have the commonName (cn) attribute, and it returns all of those entries whose cn attribute value contains a specified argument string.

The argument string may be located anywhere within a matching value: that is, it may be a leading substring, trailing substring, arbitrary internal substring, or any combination of these.

Syntax

[%number =] ldap:FindStringInCommonName( string, doc, - [AttributesOnly= boolean], - [ReturnAttributes= stringlist], - [BaseObject= string])

Syntax terms

%number	A float variable to contain the operational status result of the method. A zero indicates that the method operation succeeded; a negative value indicates an error, which may or may not be in the client code, and more specific information about which can often be obtained by using the ErrorNumber and the ErrorText methods. An error that produces a negative status value also breaks the connection to the server, which necessitates a reissue of an LDAP Bind call. If the client is the source of the error, or no server error information is available, ErrorNumber may be the same as %number, or it may be set harmlessly to 0, and ErrorText is likely to contain explanatory information for the %number setting. If the server reports an error, the ErrorNumber property is set to that number, which is likely to differ from %number, and the ErrorText value will contain whatever information about the server error is available. Possible %number values are: 0 Operation succeeded -1 Connection lost -3 Other communication failure -4 Response message contains ill-formed (unexpected) data -5 Error obtained from server and available to ErrorNumber and ErrorText methods -6 Invalid search string (see ErrorNumber and ErrorText methods)
ldap	An LDAP object variable.
searchString	A string, which must be 255 bytes or less, used to locate cn values in the directory that contain the string somewhere (beginning, internal, or end) in the value, ignoring prefixes like "Ms", middle initials, and suffixes like "Jr.". The searchString is sent as specified, and Model 204 uppercases the characters by default. For LDAP attribute types and servers employing mixed-case searching, you can use the Model 204 *LOWER command to turn off the default uppercasing. For comments about special character and wildcard handling, see "Using the Find methods".
doc	A Janus XmlDoc object to contain the found directory entries returned from the LDAP server. It must not be Null, but it must be empty, and its Namespace property must be On (the default); otherwise, for any of these, the request is canceled. The contents of a returned XmlDoc are described in "Working with returned values".
AttributesOnly	This Boolean enumeration is an optional but name required parameter. If set to True, FindStringInCommonName still retrieves the entries that satisfy the search condition, but it returns only the names (sometimes called "types") of the available entry attributes, not their associated values. If you omit this parameter, its default setting is False. If you specify a value, you must include the parameter name.
ReturnAttributes	This optional, name required, Stringlist object contains a list of the LDAP attributes for which information is displayed in each entry that FindStringInCommonName returns. If you omit this parameter or provide a Null object, information for all attributes is returned. If you specify a value, you must include the parameter name. Each Stringlist item is limited to 255 characters; null string items are ignored.
BaseObject	This optional, name required, string contains one or more comma-separated attribute=value pairs that direct this search to a particular domain in the target LDAP directory tree. For example: BaseObject='dc=hawaii,dc=edu' Such a string may be required by your target LDAP server to provide an LDAP base "distinguished name," which ensures that the entries your search string locates are unique. BaseObject is available as of Sirius Mods version 6.8.

Usage notes

See "Using the Find methods", and see the "Usage notes" for the FindEQ method, most of which applies to FindStringInCommonName.

Example

%st = %ld:FindStringInCommonName('baldo', %doc, ReturnAttributes=%AttList)

This statement searches a test LDAP server, asking for a return of only the attributes in the Stringlist variable %Attlist, which is formed as follows:

%AttList = new %AttList:add ('cn') %AttList:add ('sn') %AttList:add ('givenname')

The %doc:Print result follows:

<result> <entry objectName="id=X172, o=Boston University, c=US"> <cn> <value>Baldona, Ann</value> </cn> <sn> <value>Baldona</value> </sn> <givenname> <value>Ann</value> </givenname> </entry> <entry objectName="id=X390, o=Boston University, c=US"> <cn> <value>Edward, Ubaldonado</value> </cn> <sn> <value>Edward</value> </sn> <givenname> <value>Ubaldonado</value> </givenname> </entry> </result>

See also

LDAP class	List of LDAP methods	LDAP methods syntax
Notation conventions for methods