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

This function is used to retrieve the list of entry_ids and results list strings from the specified schema. The entries are returned as an array of (entry_id, resultslist) 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).

See also the ars_GetListEntryWithFields which is similar to GetListEntry but returns selected fields as separate values and not as formatted strings.

The "..." in the above function can be one of two things:

  1. 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.
  2. An optional list of field ids and sorting types to indicate how you want the schemas default results list to be sorted. If you do not specify the fields you want to have returned, the function returns the fields defined as the results list for this schema, which can be changed on the server side.

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 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, resultslist) pairs.
On failure
Returns undef.

Examples:

Simple usage:

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

Example 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];
               $resultslist_fields = $Entries[$i+1];
                           print "$entry_num\t$resultslist_fields\n";
           }
 

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

Back to Table of Contents

Last changes to this page 14 Apr 2009 by michiel.beijen@gmail.com

© J.C.Murphy, J.W.Murphy 1998 arsperl@arsperl.org