ARSperl Manual - ars_GetListEntryWithFields

## `ars_GetListEntryWithFields( ctrl, schema, qualifier, maxRetrieve=0, firstRetrieve=0, # standard [ fieldID_list ], # OPTIONAL sortID1,sortdir1,sortID2,sortdir2,...) # OPTIONAL`

This function is used to query a specified schema and return actual field values - not formatted strings as per `ars_GetListEntry` - from all matching entries.

`[ fieldID_list ]` is an optional array reference; the list is a list of FieldIDs. Because only the actual fieldIDs need to be passed, this is a list of scalar values, not a list of hash references a la `ars_GetListEntry`. If not specified, the default result list fields for the schema are returned.

The other arguments are identical in function to `ars_GetListEntry`.

The format of the returned list/hash is (entry_id, {field_value_hash}) pairs. The returned list can be stored in an array or hash. Using an array preserves the sort order, if one was specified. Each referenced field_value_hash looks like the return of a single `ars_GetEntry` call: the hash keys are the fieldIDs and the hash values are the field values.

On success
  Returns a list of (entry_id, {field_value_hash}) pairs.
On failure
  Returns `undef`.

Example:

        # Read all Completed entries from Sample:Enrollments
        # fetch Class Title, Location and Enrollee Login

        my $schema      = "Sample:Enrollments";
        my $querystring = qq/'7' = "Completed"/;
       ( my $lq = ars_LoadQualifier( $ctrl, $schema, $qs ) )
          || die("LoadQualifier Failed: $ars_errstr");

        my %fieldname_to_id = ars_GetFieldTable( $ctrl, $schema );
        my $class_title     = $fieldname_to_id{'Class Title'};
        my $class_location  = $fieldname_to_id{'Class Location'};
        my $enrollee_login  = $fieldname_to_id{'Enrollee Login'};

       (
           my %entries = ars_GetListEntryWithFields(
               $ctrl, $schema, $lq, 0, 0,
               [ $class_title, $class_location, $enrollee_login ],
           )
       ) || die("GLEWF Failed: $ars_errstr");

       foreach my $entry_id (keys %entries) {
           print
       "$entry_id\t $entries{$entry_id}{$class_title}\t $entries{$entry_id}{$class_location}\t $entries{$entry_id}{$enrollee_login}\n";
       }

Notes: This is a high-performance command that returns a lot of data with one API call. Care should be taken to delete the returned data structure (e.g., with "`undef %entries`") when it is no longer needed, to avoid memory problems.

See Also: ars_GetListEntry, ars_GetMultipleEntries

Back to Table of Contents