FindEQ (LDAP function) - Revision history

JAL: minor cleanup

2014-12-04T17:14:05Z

minor cleanup

← Older revision		Revision as of 17:14, 4 December 2014
Line 153:		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}}

JAL at 20:01, 31 July 2014

2014-07-31T20:01:25Z

Show changes

JALWiccan: 1 revision

2011-08-26T21:47:59Z

1 revision

← Older revision	Revision as of 21:47, 26 August 2011
(No difference)

JAL2 at 21:47, 26 August 2011

2011-08-26T21:47:58Z

← Older revision		Revision as of 21:47, 26 August 2011
Line 34:		Line 34:
	</table>		</table>

	<tr><th>~~LDAP~~</th><td>An <var>LDAP</var> object variable.</td></tr>		<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.		<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.

JAL2 at 21:54, 15 August 2011

2011-08-15T21:54:42Z

← Older revision		Revision as of 21:54, 15 August 2011
Line 18:		Line 18:
	===Syntax terms===		===Syntax terms===
	<table class="syntaxTable">		<table class="syntaxTable">
	<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>
	<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;ldquo;~~type~~&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> <tr><th>cn </th><td>Common Name </td></tr>
Line 46:		Line 50:
	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 class#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.

Line 57:		Line 61:

	<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;ldquo;~~types~~&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 75:
	<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;ldquo;~~distinguished name,~~&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.</td></tr>		<var>BaseObject</var> is available as of <var class="product">Sirius Mods</var> version 6.8.</td></tr>
Line 79:		Line 82:
	==Usage notes==		==Usage notes==

	In addition to the following notes, see [[LDAP ~~Helper~~#Using the Find methods\|"Using the Find methods"]].		In addition to the following notes, see [[LDAP class#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 112:		Line 115:
	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>If the search result		<li>If the search result
	contains binary data that is not a valid XML string,		contains binary data that is not a valid XML string,
Line 124:		Line 127:
	data (translated to a corresponding EBCDIC value).		data (translated to a corresponding EBCDIC value).
	<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>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

JAL2: /* Syntax terms */

2011-08-15T21:15:11Z

Syntax terms

← Older revision		Revision as of 21:15, 15 August 2011
Line 49:		Line 49:
	<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><i><b>%doc</b></i></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>

JALWiccan: 1 revision

2011-07-14T19:40:31Z

1 revision

← Older revision	Revision as of 19:40, 14 July 2011
(No difference)

Admin: /* Usage notes */

2011-07-14T19:40:29Z

Usage notes

Admin: /* Usage notes */

2011-07-08T23:02:35Z

Usage notes

← Older revision		Revision as of 23:02, 8 July 2011
Line 134:		Line 134:
	Since even a <var class="term">%st</var> value of zero does not guarantee that		Since even a <var class="term">%st</var> value of zero does not guarantee that
	the <var>XmlDoc</var> contents are complete, you need to include		the <var>XmlDoc</var> contents are complete, you need to include
	checks of the <var>[[ErrorNumber (LDAP ~~property~~)\|ErrorNumber]]</var> and		checks of the <var>[[ErrorNumber (LDAP function)\|ErrorNumber]]</var> and
	<var>[[ErrorText (LDAP ~~property~~)\|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.
	</ul>		</ul>

	==Example==		==Example==

JALWiccan: 1 revision

2011-07-08T22:58:23Z

1 revision

← Older revision	Revision as of 22:58, 8 July 2011
(No difference)

← Older revision		Revision as of 19:40, 14 July 2011
Line 1:		Line 1:
	{{Template:LDAP:FindEQ subtitle}}		{{Template:LDAP:FindEQ subtitle}}

	This [[Notation conventions for methods#Callable ~~methods~~\|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
Line 31:		Line 31:
	<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><i><b>%ld</b></i></th><td>An <var>Ldap</var> object variable.</td></tr>
	<tr><th><i><b>attrib</b></i></th><td>The name (sometimes called &amp;ldquo;type&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><i><b>attrib</b></i></th><td>The name (sometimes called &amp;amp;ldquo;type&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.

	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 overview#rfc2256\|"RFC 2256"]].
Line 58:		Line 58:
	<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 &amp;ldquo;types&amp;rdquo;) of the available entry attributes, not their associated values.		but it returns only the names (also called &amp;amp;ldquo;types&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 72:
	<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;ldquo;distinguished name,&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 &amp;amp;ldquo;distinguished name,&amp;amp;rdquo; 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.</td></tr>		<var>BaseObject</var> is available as of <var class="product">Sirius Mods</var> version 6.8.</td></tr>