Getting information from matching records

The fetch method has four arguments:

• flag
• offset

  Together the flag and offset arguments define the starting position of the block of records to be fetched. The flag argument is a string and must be one of:

  • start
  • current
  • end

  The start and end flags refer to the first record and the last record in the matching set. The current flag refers to the position of the last record fetched by the previous call to the fetch method. If the fetch method has not been called, current refers to the first record in the matching set.

  The offset argument is an integer. It adjusts the starting position relative to the value of the flag argument. A positive value for offset specifies a start after the position specified by flag and a negative value specifies a start before the position specified by flag.

  For example, calling fetch with a flag of start and offset of 3 will return records starting from the fourth record in the matching set. Specifying a flag of end and an offset of -8 will return records starting from the ninth last record in the matching set.

  To retrieve the next record after the last returned by the previous fetch, you would pass a flag of current and an offset of 1.

• count

  The count argument specifies the maximum number of records to be retrieved.

  Passing a count value of 0 is valid. This causes fetch to change the current record without actually retrieving any data.

  Using a negative value for count is also valid. This causes fetch to return all the records in the matching set from the starting position (specified by flag and offset).

• columns

  The optional columns argument is used to specify which columns should be included in the returned records. The argument can be either a string or a reference to an array of strings. In its simplest form each string contains a single column name, or several column names separated by semi-colons or commas.

  The value of the columns argument can be more than simple column names. See the section on Specifying columns for details.

For example:

1. Retrieve the first record from the start of a set of matching records:

   my $parties = IMu::Module->new('eparties', $session);
   my $columns = 'NamFirst,NamLast';
   my $result = $parties->fetch('start', 0, 1, $columns);
   

   The columns argument can also be specified as an array reference:

   my $parties = IMu::Module->new('eparties', $session);
   my $columns =
   [
       'NamFirst',
       'NamLast'
   ];
   my $result = $parties->fetch('start', 0, 1, $columns);
   

2. Return all of the results in a matching set:

   my $parties = IMu::Module->new('eparties', $session);
   my $columns =
   [
       'NamFirst',
       'NamLast'
   ];
   my $result = $parties->fetch('start', 0, -1, $columns);
   

3. Change the current record to the next record in the set of matching records without retrieving any data:

   $parties->fetch('current', 1, 0);
   

4. Retrieve the last record from the end of a set of matching records:

   my $parties = IMu::Module->new('eparties', $session);
   my $columns =
   [
       'NamFirst',
       'NamLast'
   ];my $result = $parties->fetch('end', 0, 1, $columns);
   

The fetch method returns a reference to a hash. It contains three members:

• count

  The number of records returned by the fetch request.

• hits

  The estimated number of matches in the result set. This number is returned for each fetch because the estimate can decrease as records in the result set are processed by the fetch method.

• rows

  A reference to an array containing the set of records requested. Each element of the rows array is itself a reference to a hash. Each hash contains entries for each column requested.

For example, retrieve the count and hits properties and iterate over all of the returned records using the rows property:

my $columns = 
[
    'NamFirst',
    'NamLast',
];my $result = $parties->fetch('start', 0, 2, $columns);my $count = $result->{'count'};my $hits = $result->{'hits'};
print('Count: ', $count, "\n");
print('Hits: ', $hits, "\n");
print('Rows:', "\n");
foreach my $row (@{$result->{'rows'}})
{
    my $rowNum = $row->{'rownum'};
    my $irn = $row->{'irn'};
    my $firstName = $row->{'NamFirst'};
    my $lastName = $row->{'NamLast'};
    printf("  %d. %s, %s (%d)\n", $rowNum, $lastName, $firstName, $irn);
}

This will produce output similar to the following:

Count: 2
Hits: 4
Rows:
  1. ECCLES-SMITH, Kate (100573)
  2. SMITH, Ian (100301)

These are simple column names of the type already mentioned, for example:

NamFirst

The values of atomic columns are returned as strings:

my $columns =
[
    'NamFirst'
];my $result = $parties->fetch('start', 0, 1, $columns);
foreach my $row (@{$result->{'rows'}})
{
    my $first = $row->{'NamFirst'};
    # ⋯
}

Nested tables are columns that contain a list of values. They are specified similarly to atomic columns:

NamRoles_tab

The values of nested tables are returned as an array reference. Each array member is a string that corresponds to a row from the nested table:

my $columns =
[
    'NamRoles_tab'
];my $result = $parties->fetch('start', 0, 1, $columns);
foreach my $row (@{$result->{'rows'}})
{
    my $roles = $row->{'NamRoles_tab'};
    foreach my $role (@$roles)
    {
        # ⋯
    }
}

An attachment is a link between a record in a module and a record in the same or another module. The columns from an attached record can be specified by first specifying the attachment column and then the column to retrieve from the attached record:

SynSynonymyRef_tab.SummaryData

Multiple columns can be specified from the attached record:

SynSynonymyRef_tab.(NamFirst,NamLast)

The return values of columns from attached records depends on the type of the attachment column. If the attachment column is atomic then the column values are returned as a hash reference. If the attachment column is a nested table the values are returned as an array reference. Each array member is a hash reference containing the requested column values for each attached record:

my $columns =
[
    'SynSynonymyRef_tab.(NamFirst,NamLast)'
];my $result = $parties->fetch('start', 0, 1, $columns);
foreach my $row (@{$result->{'rows'}})
{
    my $synonymies = $row->{'SynSynonymyRef_tab'};
    foreach my $synonymy (@$synonymies)
    {
        my $first = $synonymy->{'NamFirst'};
        my $last = $synonymy->{'NamLast'};
        # ⋯
    }
}

A reverse attachment allows you to specify columns from other records in the same module or other modules that have the current record attached to a specified column.

For example:

1. Retrieve the TitMainTitle (Main Title) column for all Catalogue records that have the current Parties record attached to their CreCreatorRef_tab (Creator) column:

   <ecatalogue:CreCreatorRef_tab>.TitMainTitle
   

2. Retrieve the NarTitle (Title) column for all Narratives records that have the current Narrative record attached to their HieChildNarrativesRef_tab (Child Narratives) column:

   <enarratives:HieChildNarrativesRef_tab>.NarTitle
   

Multiple columns can be specified from the reverse attachment record:

<ecatalogue:CreCreatorRef_tab>.(TitMainTitle,TitObjectCategory)

Reverse attachments are returned as an array reference. Each array member is a hash reference containing the requested column values from each record from the specified module (The Catalogue module in the example below) that has the current record attached to the specified column (The CreCreatorRef_tab column in the example below):

my $columns =
[
    '<ecatalogue:CreCreatorRef_tab>.(TitMainTitle,TitObjectCategory)'
];my $result = $parties->fetch('start', 0, 1, $columns);
foreach my $row (@{$result->{'rows'}})
{
    my $objects = $row->{'ecatalogue:CreCreatorRef_tab'};
    foreach my $object (@$objects)
    {
        my $title = $object->{'TitMainTitle'};
        my $category = $object->{'TitObjectCategory'};
        # ⋯
    }
}

A set of nested table columns can be grouped by specifying them between square brackets.

For example, to group the Contributors and their Role from the Narratives module:

[NarContributorRef_tab.SummaryData,NarContributorRole_tab]

Each corresponding rows of the supplied nested tables are returned as a single table row in the returned results. By default, the group is given a name of group1, group2 and so on. This group name can be changed by prefixing the grouped columns with an alternative name:

contributors=[NarContributorRef_tab.SummaryData,NarContributorRole_tab]

The grouped nested tables are returned as an array reference. Each array member is a hash reference containing corresponding rows from the nested tables:

my $columns =
[
    '[NarContributorRef_tab.SummaryData,NarContributorRole_tab]'
];my $result = $narratives->fetch('start', 0, 1, $columns);
foreach my $row (@{$result->{'rows'}})
{
    my $groupedRows = $row->{'group1'};
    foreach my $groupedRow (@$groupedRows)
    {
        # NarContributorRef_tab is an attachment column.my $contributor = $groupedRow->{'NarContributorRef_tab'};
        my $summary = $contributor->{'SummaryData'};
        my $role = $groupedRow->{'NarContributorRole_tab'};
        # ⋯
    }
}

Virtual columns are columns that do not actually exist in the EMu table being accessed. Instead, the IMu server interprets the request for the column and builds an appropriate response. Certain virtual columns can only be used in certain modules as follows:

The following virtual columns can be used in any EMu module:

• insertedTimeStamp

  Returns the insertion date and time of the record using the format YYYY-MM-DDThh:mm:ss, for example 1999-12-31T23:59:59. This is similar to the ISO8601 date format except the time zone designator is not included.

• modifiedTimeStamp

  Returns the modification date and time of the record using the format YYYY-MM-DDThh:mm:ss.

my $columns =
[
   'insertedTimeStamp',
    'modifiedTimeStamp'
];my $result = $parties->fetch('start', 0, 1, $columns);
foreach my $row (@{$result->{'rows'}})
{
    my $inserted = $row->{'insertedTimeStamp'};
    my $modified = $row->{'modifiedTimeStamp'};
    # ⋯
}

The following virtual columns can be used in any EMu module except Multimedia:

• application

  Returns information about the preferred application multimedia attached to a record.

  Note: Currently the preferred multimedia is the same as the first entry in the list returned by the applications virtual column. However, future versions of EMu may allow other multimedia to be flagged as preferred, in which case the application column will return information for the preferred multimedia, rather than the first one.

• applications

  Returns information about all of the application multimedia attached to a record.

• audio

  Returns information about the preferred audio multimedia attached to a record.

• audios

  Returns information about all of the audio multimedia attached to a record.

• image

  Returns information about the preferred image multimedia attached to a record.

• images

  Returns information about all of the image multimedia attached to a record.

• multimedia

  Returns information about all of the multimedia attached to a record.

• video

  Returns information about the preferred video multimedia attached to a record.

• videos

  Returns information about all of the video multimedia attached to a record.

See Multimedia for more information.

The following virtual columns can only be used in the Multimedia module:

• master

  Returns information about the master multimedia file.

• resolutions

  Returns information about all multimedia resolutions.

• resource

  Returns minimal information about the master multimedia file including an open file handle to a temporary copy of the multimedia file.

• resources

  The same as the resource virtual column except that information and file handles are supplied for all multimedia files.

• supplementary

  Returns information about all supplementary multimedia files.

• thumbnail

  Returns information about the multimedia thumbnail.

See Multimedia for more information.

The following virtual column can only be used in the Narratives module:

• trails

  Returns information about the position of the current Narratives record in the Narratives hierarchy.

The following virtual column can only be used in the Collection Descriptions module:

• extUrlFull_tab

A fetch set allows you to pre-register a group of columns by a single name. That name can then be passed to the fetch method to retrieve the specified columns.

Fetch sets are useful if the fetch method will be called several times with the same set of columns because:

• The required columns do no have to be specified every time the fetch method is called. This is useful when maintaining state.
• Every time the fetch method is called the IMu server must parse the supplied columns and check them against the EMu schema. For complex column sets, particularly those involving several references or reverse references, this can take time.

The IMu::Module class addFetchSet method is used to register a set of columns. This method takes two arguments:

• name

  The name to use for the column set. The value of this argument can be passed to any call to the fetch method and the set of columns specified by the columns argument will be returned.

• columns

  The set of columns to be associated with the name argument.

The IMu::Module class addFetchSets method is similar except that multiple sets can be registered at one time.

The results are returned as if you had supplied the columns directly to the fetch method.

For example:

1. Add a single fetch set using the addFetchSet method:

   my $columns =
   [
       'NamFirst',
       'NamLast',
       'NamRoles_tab'
   ];
   $parties->addFetchSet('person_details', $columns);
   

2. Add multiple fetch sets using the addFetchSets method:

   my $sets =
   {
       'person_details' => ['NamFirst', 'NamLast', 'NamRoles_tab'],
       'organisation_details' => ['NamOrganisation', 'NamOrganisationAcronym']
   };
   $module->addFetchSets($sets);
   

3. Retrieve a fetch set using the fetch method:

   my $result = $parties->fetch('start', 0, 1, 'person_details');
   foreach my $row (@{$result->{'rows'}})
   {
       my $first = $row->{'NamFirst'};
       my $last = $row->{'NamLast'};
   
       my $roles = $row->{'NamRoles_tab'};
       foreach my $role (@$roles)
       {
           # ⋯
       }
   }
   

Warning

The fetch set name must be the only value passed as the Fetch method columns argument. This may be revised in a future version of the IMu API.

Columns can be renamed in the returned results by prefixing them with an alternative name:

first_name=NamFirst

The value of the specified column is now returned using the alternative name:

my $columns =
[
    'first_name=NamFirst'
];my $result = $parties->fetch('start', 0, 1, $columns);
foreach my $row (@{$result->{'rows'}})
{
    my $first = $row->{'first_name'};
    # ⋯
}

Alternative names can be supplied to other column specifications as well:

roles=NamRoles_tab

synonyms=SynSynonymyRef_tab.(NamFirst,NamLast)

objects=<ecatalogue:CreCreatorRef_tab>.(TitMainTitle,TitObjectCategory)

Alternative names can also be used for any columns specified between round brackets or square brackets:

SynSynonymyRef_tab.(first_name=NamFirst,last_name=NamLast)

contributors=[contributor=NarContributorRef_tab.SummaryData,role=NarContributorRole_tab]

Alternative names can also be supplied in fetch sets:

my $columns =
[
    'first_name=NamFirst',
    'last_name=NamLast',
    'roles=NamRoles_tab'
];
$parties->addFetchSet('person_details', $columns);