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 Status and History of all open entries
        # return most recent entries first
        #

        $qs = qq/'Status' = "Open"/;
        ( $lq = ars_LoadQualifier( $ctrl, $schema, $qs ) )
        || die( "LoadQualifier Failed: $ars_errstr" );

        ( @Entries = ars_GetListEntryWithFields(
                                $ctrl, $schema, $lq, 0,
                                [ FieldID("Status"), FieldID("History") ],
                                FieldID("EntryID"), 2
                                           ) )
             || die( "GLEWF Failed: $ars_errstr" );

Returned list, sorted in descending order by EntryID:

        @Entries = ( "0000000139", { 7 => 1,
                                    10 => { decoded_history_hash } },
                     "0000000047", { 7 => 1,
                                    10 => { another_diary } }
                   )

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.

`ars_GetListEntryWithFields` can only be used with API version 4.0 or later.

See Also: ars_GetListEntry, ars_GetMultipleEntries

Table of Contents