FindStringInCommonName (LDAP function)
<section begin=dpl_desc/><section end=dpl_desc/>
FindStringInCommonName is a member of the 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
[%st =] %ld:FindStringInCommonName( searchString, %doc, - [, AttributesOnly=bool] - [, ReturnAttributes=%sl] - [, BaseObject=string] )
Syntax terms
| %st | 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 %st, or it may be set harmlessly to 0, and ErrorText is likely to contain explanatory information for the %st setting. If the server reports an error, the ErrorNumber property is set to that number, which is likely to differ from %st, and the ErrorText value will contain whatever information about the server error is available. Possible %st values are:
| ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| %ld | 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>