FindStringInCommonName (LDAP function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(4 intermediate revisions by 2 users not shown)
Line 18: Line 18:
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th><i><b>%st</b></i>
<tr><th>%number</th>
</th><td>A float variable to contain the operational status result of the method.
<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,
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 may or may not be in the client code, and more specific information about
Line 25: Line 25:
and the <var>[[ErrorText (LDAP function)|ErrorText]]</var> methods. An error that produces a
and the <var>[[ErrorText (LDAP function)|ErrorText]]</var> methods. An error that produces a
negative status value also breaks the connection to the server, which necessitates a
negative status value also breaks the connection to the server, which necessitates a
reissue of an <var>Ldap</var> <var>[[Bind (LDAP function)|Bind]]</var> call.
reissue of an <var>LDAP</var> <var>[[Bind (LDAP function)|Bind]]</var> call.


If the client is the source of the error, or no server error information is available, <var>ErrorNumber</var>
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">%st</var>, or it may be set harmlessly to 0, and <var>ErrorText</var> is likely to contain explanatory information for the <var class="term">%st</var> setting.
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 <var class="term">%st</var>, 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 <var class="term">%st</var> values are:
Possible <var class="term">%number</var> values are:
<table>  
<table>  
<tr><th>0 </th><td>Operation succeeded </td></tr>  
<tr><th>0 </th><td>Operation succeeded </td></tr>  
Line 42: Line 42:
</table></td></tr>
</table></td></tr>


<tr><th><i><b>%ld</b></i></th>
<tr><th>ldap</th>
<td>An <var>Ldap</var> object variable.</td></tr>
<td>An <var>LDAP</var> object variable.</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 <code>cn</code> values in the directory that contain the string somewhere (beginning, internal, or end) in the value, ignoring prefixes like &amp;amp;amp;amp;ldquo;Ms,&amp;amp;amp;amp;rdquo; middle initials, and suffixes like &amp;amp;amp;amp;ldquo;Jr.&amp;amp;amp;amp;rdquo;.  
<td>A string, which must be 255 bytes or less, used to locate <code>cn</code> 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 <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.  
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 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 (XmlDoc property)|Namespace]]</var> property must be <code>On</code> (the default); otherwise, for any of these, the request is canceled.
<td>A Janus <var>[[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 (XmlDoc property)|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>FindStringInCommonName</var> still retrieves the entries that satisfy the search condition, but it returns only the names (sometimes called &amp;amp;amp;amp;ldquo;types&amp;amp;amp;amp;rdquo;) of the available entry attributes, not their associated values.
<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>FindStringInCommonName</var> 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 <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 69: Line 69:
<tr><th><var>BaseObject</var></th>
<tr><th><var>BaseObject</var></th>
<td>This optional, [[Notation conventions for methods#Named parameters|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:
<td>This optional, [[Notation conventions for methods#Named parameters|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:
<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;amp;ldquo;distinguished name,&amp;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.


<var>BaseObject</var> is available as of <var class="product">Sirius Mods</var> version 6.8.
<var>BaseObject</var> is available as of <var class="product">Sirius Mods</var> version 6.8.
Line 77: Line 77:


==Usage notes==
==Usage notes==
See [[LDAP Helper#Using the Find methods|"Using the Find methods"]],
See [[LDAP class#Using the Find methods|"Using the Find methods"]],
and see the [[FindEQ (LDAP function)#Usage notes|"Usage notes"]] for the <var>FindEQ</var> method,
and see the [[FindEQ (LDAP function)#Usage notes|"Usage notes"]] for the <var>FindEQ</var> method,
most of which applies to <var>FindStringInCommonName</var>.
most of which applies to <var>FindStringInCommonName</var>.
==Example==
==Example==
<p class="code"> %st = %ld:FindStringInCommonName('baldo', %doc,   -
<p class="code">%st = %ld:FindStringInCommonName('baldo', %doc, ReturnAttributes=%AttList)
                      ReturnAttributes=%AttList)
</p>
</p>


Line 90: Line 89:
the <var>Stringlist</var> variable <code>%Attlist</code>, which
the <var>Stringlist</var> variable <code>%Attlist</code>, which
is formed as follows:
is formed as follows:
<p class="code"> %AttList = new
<p class="code">%AttList = new
%AttList:add ('cn')
%AttList:add ('cn')
%AttList:add ('sn')
%AttList:add ('sn')
%AttList:add ('givenname')
%AttList:add ('givenname')
</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="id=X172, o=Boston University, c=US">
  <entry objectName="id=X172, o=Boston University, c=US">
      <cn>
      <cn>
          <value>Baldona, Ann</value>
        <value>Baldona, Ann</value>
      </cn>
      </cn>
      <sn>
      <sn>
          <value>Baldona</value>
        <value>Baldona</value>
      </sn>
      </sn>
      <givenname>
      <givenname>
          <value>Ann</value>
        <value>Ann</value>
      </givenname>
      </givenname>
    </entry>
  </entry>
    <entry objectName="id=X390, o=Boston University, c=US">
  <entry objectName="id=X390, o=Boston University, c=US">
      <cn>
      <cn>
          <value>Edward, Ubaldonado</value>
        <value>Edward, Ubaldonado</value>
      </cn>
      </cn>
      <sn>
      <sn>
          <value>Edward</value>
        <value>Edward</value>
      </sn>
      </sn>
      <givenname>
      <givenname>
          <value>Ubaldonado</value>
        <value>Ubaldonado</value>
      </givenname>
      </givenname>
    </entry>
  </entry>
</result>
</result>
</p>
</p>
==See also==
==See also==
{{Template:LDAP:FindStringInCommonName footer}}
{{Template:LDAP:FindStringInCommonName footer}}

Latest revision as of 21:47, 26 August 2011

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