ARSperl Manual - ars_GetMultipleEntries

## `ars_GetMultipleEntries(ctrl,schema,[ entryID_list ],...)`

This function retrieves multiple entries from a schema, in the form of a hash (or list, if preferred) of entryIDs and references to fieldID/value pairs. The `[ entryID_list ]` argument is a reference to a list of entryIDs. If you specify any fieldIDs after the `[ entryID_list ]` parameter, only the values for those fields will be returned, otherwise all field id value pairs are returned.

The format of the returned list is (entryID, {field_value_hash}) pairs. The list can be stored in an array or hash. Using an array preserves the original order of `[ entryID_list ]`. Each referenced field_value_hash has the same format as the return of a single `ars_GetEntry` call: the hash keys are the fieldIDs and the hash values are the field values. If the entryID was not found, the field_value_hash reference is `undef`.

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

Example:

        @elist = ( "000000001", "0000000046", "0000000138" );
        #
        # Get Status and History for each entry
        #
        ( %Entries = ars_GetMultipleEntries(
                              $ctrl, $schema, \@elist,
                              FieldID("Status"), FieldID("History")
                                            ) )
           || die( "GME Failed: $arr_errstr" );

Example returned hash:

        %Entries = ( "0000000001" => { 7 => 1,
                                      10 => { decoded_history_hash } },
                     "0000000046" => undef,         # entry does not exist
                     "0000000138" => { 7 => 3,
                                      10 => { another_diary } }
                   )

Notes: `ars_GetMultipleEntries` can download a lot of data with one API call. It is advisable to use the fieldID list to specify only the fields you need. Care should be taken to delete the returned data structure (e.g., with "`undef %Entries`") when it is no longer needed.

The underlying `ARGetMultipleEntries` API call has an inherent limit to the number of entries that can be returned in a single call. The ARS 4.5 Programmer's Guide recommends using lists of 100 or fewer entries for each request.

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

See Also: ars_GetEntry, ars_GetListEntryWithFields

Table of Contents