ARSperl Manual - ars

`ars_GetListEntry(ctrl, schema, qualifier, maxRetrieve=0, firstRetrieve=0,...)`

This function is used to retrieve the list of entry_ids and description (query list) strings from the specified schema. The entries are returned as an array of (entry_id, query-list) pairs. If you wish to retrieve all entries in the schema (upto the maximum allowed by the server or specified by you as the maxRetrieve parameter) you should load a Qualifier with something like (1 = 1).

ARS3.x

In 3.x, the "..." in the above function can be one of two things:

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.
An optional list of field ids and sorting types to indicate how you want the schema's default query list to be sorted.

ARS2.x

In 2.x, the "..." in the above function indicates an optional list of field ids and sorting type.

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.

Setting maxRetrieve = 0 will return as many matches as the server will allow. This is the default.

firstRetrieve (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.

On success: Returns a list of (entry_id, short-description) pairs.
On failure: Returns undef.

Note: prior to ARSperl 1.50 ars_GetListEntry returned a -1 on a call where the query matched more than the maxRetrieve number of items from the database.

Example:

           %entries = ars_GetListEntry($c, "User", $q, 100);
           foreach $entry_id (sort keys %entries) {
             print "EntryID: $entry_id Short-Descrip: $entries{$entry_id}\n";
           }

Example (2.x or 3.x) of how to set sorting options:

           # 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];

           }

Example (3.x only) of how to specify your own query list and sorting options:

           %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);

Table of Contents

Last changes to this page 15 Apr 2003 by jcmurphy