<HTML>
<HEAD>
<TITLE>ARSperl Manual - ars_GetListEntry</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H2><CODE>ars_GetListEntry(ctrl, schema, qualifier, maxRetrieve=0, firstRetrieve=0,...)</CODE></H2>
This function is used to retrieve the list of <CODE>entry_id</CODE>s
and description (query list) strings from the specified schema. The entries
are returned as an array of <I>(entry_id, query-list)</I> pairs.
If you wish to retrieve all entries in the schema (upto the maximum
allowed by the server or specified by you as the <CODE>maxRetrieve</CODE>
parameter) you should load a Qualifier with something like
<CODE>(1 = 1)</CODE>.
<P>
<DL>
<DT><B>ARS3.x</B>
<DD>
In 3.x, the "..." in the above function can be one of two things:
<OL>
<LI> A Hash Reference that specifies what you want the
query list to look like, followed by (optionally) a list
of field ids and sorting types to indicate how you want the
query list sorted.
<LI> An optional list of field ids and sorting types to indicate
how you want the schema's default query list to be sorted.
</OL>
<p>
<DT><B>ARS2.x</B>
<DD>
In 2.x, the "..." in the above function indicates
an optional list of field ids and sorting type.
</DL>
The sorting type can be
1 for ascending, or 2 for descending. Also, note that if you want to
retain the order of the entry ids returned, then you must assign the
list to an array, and not a hash. <P>
Setting <CODE>maxRetrieve = 0</CODE> will return as many matches as
the server will allow. This is the default.
<P>
<code>firstRetrieve</code> (only available when compiled against the
5.x API) specifies which entry to start with. The default (zero) is to
start with the first entry that matches the qualifier.
<P>
<DL>
<DT><B>On success</B>
<DD>
Returns a list of <I>(entry_id, short-description)</I> pairs.
<DT><B>On failure</B>
<DD>
Returns <CODE>undef</CODE>.
</DL>
<P>
<i>Note: prior to ARSperl 1.50 <code>ars_GetListEntry</code> returned a
<tt>-1</tt> on a call where the query matched more than the maxRetrieve
number of items from the database.
</i>
<P>Example:
<PRE>
%entries = ars_GetListEntry($c, "User", $q, 100);
foreach $entry_id (sort keys %entries) {
print "EntryID: $entry_id Short-Descrip: $entries{$entry_id}\n";
}
</PRE>
<P>
Example (2.x or 3.x) of how to set sorting options:
<PRE>
# returns entries for User schema sorted by login name
$all = ars_LoadQualifier($c,"User","1=1");
$login_name = ars_GetFieldByName($c,"User","Login Name");
@Entries = ars_GetListEntry($c, "User", $all, 0, 0, $login_name, 1);
for ( $i = 0; $i <= $#Entries; $i +=2 ) {
$entry_num = $Entries[$i];
$description_fields = $Entries[$i+1];
}
</PRE>
<P>Example (3.x only) of how to specify your own query list and sorting options:
<PRE>
%f = ars_GetFieldTable($ctrl, "User");
# retrieve list of matching records. query list should only
# contain the Login name and Full Name fields. In addition,
# query list should be reverse sorted by Login name.
@a = ars_GetListEntry($ctrl, "User", $qual, 0, 0,
# getListFields
[
{columnWidth=>5, separator=>' ', fieldId=>$f{'Login name'} },
{columnWidth=>5, separator=>' ', fieldId=>$f{'Full Name'} }
],
# sort Order
$f{'Login name'}, 1);
</PRE>
<P>
<hr width="30%">
<p>
<A HREF="toc.html"><IMG ALT="<--" SRC="arrow.gif" ALIGN=CENTER> Table of Contents </A>
<p>
<address>
Last changes to this page 15 Apr 2003 by jcmurphy<P>
© J.C.Murphy, J.W.Murphy 1998 arsperl@arsperl.org
</address>
</BODY>
</HTML>