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.

Table of Contents