FindEQ (LDAP function)

From m204wiki
Revision as of 21:54, 15 August 2011 by JAL2 (talk | contribs)
Jump to navigation Jump to search

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:

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)
LDAPAn LDAP object variable.
attribThe 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".

cn Common Name
sn Surname
l Location
o Organization
ou Organization Unit
st State
c Country
dc Domain Component
The attrib string limit is 255 bytes, and case does not matter (all characters are sent in uppercase as is the usual Model 204 default, which is adjustable using *LOWER). A dotted-number string, which some servers support as a substitute ID for certain standard attribute names, is a perfectly valid attrib argument.
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.

BaseObject is available as of Sirius Mods version 6.8.

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 result element. 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 to True (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 Allow in 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>

See also

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