FindEQ (LDAP function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (minor cleanup)
 
(5 intermediate revisions by 3 users not shown)
Line 3: Line 3:
This [[Notation conventions for methods#Callable functions|callable]] function
This [[Notation conventions for methods#Callable functions|callable]] function
retrieves all records (entries) from the LDAP directory
retrieves all records (entries) from the LDAP directory
that satisfy the criterion
that satisfy the criterion ''attributeType''=''searchString''
''attributeType''=''searchString''
(for example, <code>cn=Albert Einstein</code>), where:
(for example, <code>cn=Albert Einstein</code>), where:
<ul>
<ul>
<li>''attributeType'' is one of the entry attribute types
<li>''attributeType'' is one of the entry attribute types
Line 14: Line 14:
you must explicitly specify.
you must explicitly specify.
</ul>
</ul>
==Syntax==
==Syntax==
{{Template:LDAP:FindEQ syntax}}
{{Template:LDAP:FindEQ syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table>
<tr><th><i><b>%st</b></i>
<tr><th><i><b>%number</b></i>
</th><td>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
</th><td>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 <var>[[ErrorNumber (LDAP function)|ErrorNumber]]</var> method and the <var>[[ErrorText (LDAP function)|ErrorText]]</var> method.


If the client is the source of the error, or no server error information is available, <var>ErrorNumber</var> may be the same as ''%st'', or it may be set harmlessly to 0, and <var>ErrorText</var> is likely to contain explanatory information for the ''
If the client is the source of the error, or no server error information is available, <var>ErrorNumber</var> may be the same as <var class="term">%number</var>, or it may be set harmlessly to 0, and <var>ErrorText</var> is likely to contain explanatory information for the <var class="term">%number</var> setting.


If the server reports an error, the <var>ErrorNumber</var> property is set to that number, which is likely to differ from ''%st'', and the <var>ErrorText</var> value will contain whatever information about the server error is available.
If the server reports an error, the <var>ErrorNumber</var> property is set to that number, which is likely to differ from <var class="term">%number</var>, and the <var>ErrorText</var> value will contain whatever information about the server error is available.


Possible ''%st'' values are:  
Possible <var class="term">%number</var> values are:  
<table>  
<table class="thJustBold">  
<tr><th>0 </th><td>Operation succeeded </td></tr>  
<tr><th> 0 </th><td>Operation succeeded </td></tr>  
<tr><th>-1 </th><td>Connection lost </td></tr> <tr><th>-3 </th><td>Other communication failure </td></tr>  
<tr><th>-1 </th><td>Connection lost </td></tr> <tr><th>-3 </th><td>Other communication failure </td></tr>  
<tr><th>-4 </th><td>Response message contains ill-formed (unexpected) data</td></tr>
<tr><th>-4 </th><td>Response message contains ill-formed (unexpected) data</td></tr>
<tr><th><i><b>%ld</b></i></th><td>An <var>Ldap</var> object variable.</td></tr>
<tr><th>-5 </th><td>Error obtained from server and available to <var>ErrorNumber</var> and <var>ErrorText</var> methods </td></tr>
<tr><th><i><b>attrib</b></i></th><td>The name (sometimes called &amp;amp;amp;ldquo;type&amp;amp;amp;rdquo;) of the entry attribute you want to key the directory search. You use the ''searchString'' argument to specify the attribute value, and <var>FindEQ</var> searches the directory for entries that satisfy the ''attrib''=''searchString'' condition.
<tr><th>-6 </th><td>Invalid search string (see <var>ErrorNumber</var> and <var>ErrorText</var> methods) </td></tr>  
</table>
 
<tr><th>ldap</th><td>An <var>LDAP</var> object variable.</td></tr>
 
<tr><th>attrib</th><td>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 <var>FindEQ</var> searches the directory for entries that satisfy the <var class="term">attrib</var>=<var class="term">searchString</var> 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 [[LDAP overview#rfc2256|"RFC 2256"]].  
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 [[LDAP class#LDAP overview#rfc2256|RFC 2256]].  


<table> <tr><th>cn </th><td>Common Name </td></tr>  
<table class="thJustBold">  
<tr><th>cn </th><td>Common Name </td></tr>  
<tr><th>sn </th><td>Surname </td></tr>       
<tr><th>sn </th><td>Surname </td></tr>       
<tr><th>l </th><td>Location </td></tr>  
<tr><th>l </th><td>Location </td></tr>  
Line 42: Line 50:
<tr><th>st </th><td>State </td></tr>           
<tr><th>st </th><td>State </td></tr>           
<tr><th>c </th><td>Country </td></tr>  
<tr><th>c </th><td>Country </td></tr>  
<tr><th>dc </th><td>Domain Component </td></tr></table>   
<tr><th>dc </th><td>Domain Component </td></tr>
</table>   


The <var class="term">attrib</var> string limit is 255 bytes, and case does not matter (all characters are sent in uppercase as is the usual <var class="product">Model 204</var> default, which is adjustable using <var>*LOWER</var>). A dotted-number string, which some servers support as a substitute ID for certain standard attribute names, is a perfectly valid <var class="term">attrib</var> argument.</td></tr>
The <var class="term">attrib</var> string limit is 255 bytes, and case does not matter (all characters are sent in uppercase as is the usual <var class="product">Model 204</var> default, which is adjustable using <var>*LOWER</var>). A dotted-number string, which some servers support as a substitute ID for certain standard attribute names, is a perfectly valid <var class="term">attrib</var> argument.</td></tr>


<tr><th><i><b>searchString</b></i></th>
<tr><th>searchString</th>
<td>A string, which must be 255 bytes or less, used to locate values in the directory for which <var class="term">attrib</var>=<var class="term">searchString</var>. The <var class="term">searchString</var> is sent as specified, and <var class="product">Model 204</var> uppercases the characters by default. For LDAP attribute types and servers employing mixed-case searching, you can use the <var class="product">Model 204</var> <var>*LOWER</var> command to turn off the default uppercasing.
<td>A string, which must be 255 bytes or less, used to locate values in the directory for which <var class="term">attrib</var>=<var class="term">searchString</var>. The <var class="term">searchString</var> is sent as specified, and <var class="product">Model 204</var> uppercases the characters by default. For LDAP attribute types and servers employing mixed-case searching, you can use the <var class="product">Model 204</var> <var>*LOWER</var> command to turn off the default uppercasing.


For comments about special character and wildcard handling, see [[LDAP Helper#Using the Find methods|"Using the Find methods"]]. </td></tr>
For comments about special character and wildcard handling, see [[LDAP class#Using the Find methods|Using the Find methods]]. </td></tr>


<tr><th><i><b>%doc</b></i></th>
<tr><th>doc</th>
<td>A Janus <var>[[XmlDoc API#The XmlDoc class|XmlDoc]]</var> object to contain the found directory entries returned from the LDAP server. It must not be <var>Null</var>, but it must be empty, and its <var>Namespace</var> property must be <code>On</code> (the default); otherwise, for any of these, the request is canceled.  
<td>A Janus <var>[[XmlDoc API#The XmlDoc class|XmlDoc]]</var> object to contain the found directory entries returned from the LDAP server. It must not be <var>Null</var>, but it must be empty, and its <var>Namespace</var> property must be <code>On</code> (the default); otherwise, for any of these, the request is canceled.  


The contents of a returned <var>XmlDoc</var> are described in [[LDAP Helper#Working with returned values|"Working with returned values"]]. </td></tr>
The contents of a returned <var>XmlDoc</var> are described in [[LDAP class#Working with returned values|Working with returned values]]. </td></tr>


<tr><th><var>AttributesOnly</var></th>
<tr><th><var>AttributesOnly</var></th>
<td>This <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> enumeration is an optional but [[Notation conventions for methods#Named parameters|name required]] parameter. If set to <code>True</code>, <var>FindEQ</var> still retrieves the entries that satisfy the search condition,
<td>This <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> enumeration is an optional but [[Notation conventions for methods#Named parameters|name required]] parameter. If set to <code>True</code>, <var>FindEQ</var> 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.  
but it returns only the names (also called &amp;amp;amp;ldquo;types&amp;amp;amp;rdquo;) of the available entry attributes, not their associated values.  


If you omit this parameter, its default setting is <code>False</code>. If you specify a value, you must include the parameter name. </td></tr>
If you omit this parameter, its default setting is <code>False</code>. If you specify a value, you must include the parameter name. </td></tr>
Line 72: Line 80:
<p class="code"> BaseObject='dc=hawaii,dc=edu'
<p class="code"> BaseObject='dc=hawaii,dc=edu'
</p>
</p>
Such a string may be required by your target LDAP server to provide an LDAP base &amp;amp;amp;ldquo;distinguished name,&amp;amp;amp;rdquo; which ensures that the entries your search string locates are unique.
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.</td></tr>
 
<var>BaseObject</var> is available as of <var class="product">Sirius Mods</var> version 6.8.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
 
In addition to the following notes, see [[LDAP class#Using the Find methods|Using the Find methods]].
In addition to the following notes, see [[LDAP Helper#Using the Find methods|"Using the Find methods"]].
<ul>
<ul>
<li>Specifying an attribute that does not exist is ''not'' an error, but
<li>Specifying an attribute that does not exist is ''not'' an error, but
Line 93: Line 98:
(and omit the <var>ReturnAttributes</var> argument).
(and omit the <var>ReturnAttributes</var> argument).
Such a call, of course, requires knowing at least one attribute:
Such a call, of course, requires knowing at least one attribute:
the <var class="term">attrib</var> argument you use in the call.
the <var class="term">attrib</var> argument you use in the call. </li>
 
<li>As stated earlier, how an LDAP server resolves a search is up to
<li>As stated earlier, how an LDAP server resolves a search is up to
the server.
the server.
Line 106: Line 112:
  J* Sildar
  J* Sildar
  Sildar Joh?
  Sildar Joh?
</p>
</p></li>
 
<li>Since the <var>XmlDoc</var> argument (<var class="term">%doc</var> in the syntax, above)
<li>Since the <var>XmlDoc</var> argument (<var class="term">%doc</var> in the syntax, above)
that will contain the
that will contain the
Line 112: Line 119:
your programs must include an extra statement to clear <var class="term">%doc</var>
your programs must include an extra statement to clear <var class="term">%doc</var>
before subsequent <var>Finds</var> can reference it, say, in a loop.
before subsequent <var>Finds</var> can reference it, say, in a loop.
For an example, see [[LDAP Helper#LDAP Helper example|"LDAP Helper example"]].
For an example, see [[LDAP class#LDAP class example|LDAP class example]].</li>
<li>If the search result
 
contains binary data that is not a valid XML string,
<li>If the search result contains binary data that is not a valid XML string,
the request is canceled, with a
the request is canceled, with a
message that displays a fragment of the value including the invalid
message that displays a fragment of the value including the invalid character.
character.
However, if you set the <var>InvalidChar</var> property to <code>Allow</code>
However, if you set the <var>InvalidChar</var> property to <code>Allow</code>
in the result <var>XmlDoc</var> before
in the result <var>XmlDoc</var> before
invoking the method, the request is not cancelled, and
invoking the method, the request is not cancelled, and
the result will contain the binary
the result will contain the binary
data (translated to a corresponding EBCDIC value).
data (translated to a corresponding EBCDIC value).</li>
 
<li>For information about programmatically locating specific information
<li>For information about programmatically locating specific information
within a returned <var>XmlDoc</var>, see [[LDAP Helper#LDAP Helper example|"LDAP Helper example"]].
within a returned <var>XmlDoc</var>, see [[LDAP class#LDAP class example|LDAP class example]]. </li>
 
<li>If communications are lost before the returned <var>XmlDoc</var> document contents
<li>If communications are lost before the returned <var>XmlDoc</var> document contents
are complete, a partial output <var>XmlDoc</var> is returned containing
are complete, a partial output <var>XmlDoc</var> is returned containing
Line 136: Line 144:
checks of the <var>[[ErrorNumber (LDAP function)|ErrorNumber]]</var> and
checks of the <var>[[ErrorNumber (LDAP function)|ErrorNumber]]</var> and
<var>[[ErrorText (LDAP function)|ErrorText]]</var>
<var>[[ErrorText (LDAP function)|ErrorText]]</var>
properties in your programs when incomplete query results are not tolerable.
properties in your programs when incomplete query results are not tolerable. </li>
</ul>
</ul>


==Example==
==Example==
Against a test LDAP server,
Against a test LDAP server,
the following <var>FindEQ</var> statement does a search of <code>cn</code> attribute values
the following <var>FindEQ</var> statement does a search of <code>cn</code> attribute values
Line 146: Line 153:
The statement asks for a return of only the attribute names in each matching entry,
The statement asks for a return of only the attribute names in each matching entry,
and all available attributes are returned.
and all available attributes are returned.
<p class="code"> %st = %ld:FindEQ('cn', 'sildar john', %doc,   -
<p class="code"> %st = %ld:FindEQ('cn', 'sildar john', %doc, AttributesOnly=TRUE)
                  AttributesOnly=TRUE)
</p>
</p>


The <code>%doc:Print</code> result follows:
The <code>%doc:Print</code> result follows:
<p class="code"> <result>
<p class="code"><result>
    <entry objectName="cn: Sildar, John R, id=X479, o=Boston University, c=US">
  <entry objectName="cn: Sildar, John R, id=X479, o=Boston University, c=US">
      <cn/>
      <cn/>
      <sn/>
      <sn/>
      <givenname/>
      <givenname/>
      <postaladdress/>
      <postaladdress/>
      <title/>
      <title/>
      <o/>
      <o/>
      <telephonenumber/>
      <telephonenumber/>
      <objectclass/>
      <objectclass/>
      <l/>
      <l/>
      <st/>
      <st/>
      <c/>
      <c/>
    </entry>
  </entry>
</result>
</result>
</p>
</p>
==See also==
==See also==
{{Template:LDAP:FindEQ footer}}
{{Template:LDAP:FindEQ footer}}

Latest revision as of 17:14, 4 December 2014

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.

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