FindEQ (LDAP function)
Retrieve matching records from the LDAP directory (LDAP class)
This callable function
retrieves all records (entries) from the LDAP directory
that satisfy the criterion attributeType=searchString
(for example, cn=Albert Einstein), where:
- attributeType is one of the entry attribute types defined in the target LDAP server.
- searchString is a string, which may include blanks and special characters.
- The attribute type and search string are separate FindEQ arguments you must explicitly specify.
Syntax
[%number =] ldap:FindEQ( attrib, searchString, 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. More specific information about the error can often be obtained by using the ErrorNumber method and the ErrorText method.
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:
| ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ldap | An LDAP object variable. | ||||||||||||||||
| attrib | The name (sometimes called "type") of the entry attribute you want to key the directory search. You use the searchString argument to specify the attribute value, and FindEQ searches the directory for entries that satisfy the attrib=searchString condition.
Some traditionally supported attribute names include the following, but note that servers are not required to support them. For more about the standard attribute names, see RFC 2256.
| ||||||||||||||||
| searchString | A string, which must be 255 bytes or less, used to locate values in the directory for which attrib=searchString. 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, FindEQ still retrieves the entries that satisfy the search condition, but it returns only the names (also 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 FindEQ 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. |
Usage notes
In addition to the following notes, see Using the Find methods.
- Specifying an attribute that does not exist is not an error, but
you receive an XmlDoc that contains only an empty
resultelement. Each LDAP server defines its own schema, including what attributes it has and the semantics of those attributes. Some of those attributes may be standard types and some may be local. Some of the attributes may be searchable and some may not. To obtain the names of the searchable attributes as implemented by the particular LDAP server you are querying, you can send a FindEQ call with the AttributesOnly parameter set toTrue(and omit the ReturnAttributes argument). Such a call, of course, requires knowing at least one attribute: the attrib argument you use in the call. - As stated earlier, how an LDAP server resolves a search is up to
the server.
For example, using a local university's LDAP server, all of the following
strings returned the entry whose common name it
displays as
Sildar, John R.:John Sildar Sildar, John R Sildar John R. Sildar John R Sildar J* Sildar Sildar Joh?
- Since the XmlDoc argument (%doc in the syntax, above) that will contain the response from the LDAP server must be empty when passed in the FindEQ call, your programs must include an extra statement to clear %doc before subsequent Finds can reference it, say, in a loop. For an example, see LDAP class example.
- If the search result contains binary data that is not a valid XML string,
the request is canceled, with a
message that displays a fragment of the value including the invalid character.
However, if you set the InvalidChar property to
Allowin the result XmlDoc before invoking the method, the request is not cancelled, and the result will contain the binary data (translated to a corresponding EBCDIC value). - For information about programmatically locating specific information within a returned XmlDoc, see LDAP class example.
- If communications are lost before the returned XmlDoc document contents are complete, a partial output XmlDoc is returned containing whatever the server was able to send. The document is null if the failure happens before the server sends its response. Whatever the XmlDoc contains is available for use, although the contents are suspect if the %st value is non-zero. Since even a %st value of zero does not guarantee that the XmlDoc contents are complete, you need to include checks of the ErrorNumber and ErrorText properties in your programs when incomplete query results are not tolerable.
Example
Against a test LDAP server,
the following FindEQ statement does a search of cn attribute values
for entries that match the search string sildar john.
The statement asks for a return of only the attribute names in each matching entry,
and all available attributes are returned.
%st = %ld:FindEQ('cn', 'sildar john', %doc, - AttributesOnly=TRUE)
The %doc:Print result follows:
<result> <entry objectName="cn: Sildar, John R, id=X479, o=Boston University, c=US"> <cn/> <sn/> <givenname/> <postaladdress/> <title/> <o/> <telephonenumber/> <objectclass/> <l/> <st/> <c/> </entry> </result>