Updating an EMu module

The insert method is used to add a new record to the module.

Arguments

The method takes two arguments:

• values

  Specifies any data values to be inserted into the newly created record.

  The data values should be an associative array. The indexes of the array must be column names.

• columns

  Used to specify which columns should be returned once the record has been created. The value of the column is specified in exactly the same way as in the fetch method. See the section on Specifying columns for details.

  Note: It is very common to include irn as one of the columns to be returned. This gives a way of getting the key of the newly created record.

Return value

The method returns an associative array. This associative array contains an entry for each column requested. This is identical to the associative array returned for each row as part of the fetch method.

Example

$parties = new IMuModule('eparties', $session);

/* Specify the values to insert.
*/
$values = array
(
    'NamFirst' => 'Chris',
    'NamLast' => 'Froome',
    'NamOtherNames_tab' => array
    (
        'Christopher',
        'Froomey'
    )
);

/* Specify the column values to return after inserting.
*/
$columns = array
(
    'irn',
    'NamFirst',
    'NamLast',
    'NamOtherNames_tab'
);

/* Insert the new record.
*/try
{
    $result = $parties->insert($values, $columns);
}
catch (Exception $e)
{
    print("Error: $e\n");
    exit(1);
}

/* Output the returned values.
*/
$irn = $result['irn'];
$first = $result['NamFirst'];
$last = $result['NamLast'];
$others = $result['NamOtherNames_tab'];

printf("%s, %s (%d)\n", $last, $first, $irn);
print("Other names:\n");foreach ($others as $other)
{
    print("\t$other\n");
}
exit(0);

If inserting of records is permitted, this will produce output similar to the following:

Froome, Chris (435)

Other names:

Christopher

Froomey

If inserting of records is denied by the server, this will produce output similar to the following:

Error: ModuleUpdatesNotAllowed (authenticated,default) [500]

The update method is used to modify one or more existing records. This method operates very similarly to the fetch method. The only difference is a values argument which contains a set of values to be applied to each specified record.

Arguments

The method takes five arguments:

• flag
• offset
• count

  These arguments are identical to those used by the fetch method. They define the starting position and size of the block of records to be updated.

• values

  Specifies the columns to be updated in the specified block of records. The values argument must be a hash reference. The keys of the hash must be column names.

  This is the same as the values argument for the insert method.

• columns

  Used to specify which columns should be returned once the record has been created. The value of the column is specified in exactly the same way as in the fetch method. See the section on Specifying Columns for details.

  This is the same as the columns argument for the insert method.

Return value

The update method returns an IMuModuleFetchResult object (the same as the fetch method). It contains the values for the selected block of records after the updates have been applied.

Example

/* Find all parties records that have a first name of "Chris" and a last name
** of "Froome".
*/
$parties = new IMuModule('eparties', $session);
$terms = new IMuTerms();
$terms->add('NamFirst', 'Chris');
$terms->add('NamLast', 'Froome');
$parties->findTerms($terms);

/* Specify the column to update and the new value.
*/
$values = array
(
    'NamFirst' => 'Christopher',
);

/* Specify the column values to return after updating.
*/
$columns = array
(
    'irn',
    'NamFirst',
    'NamLast'
);

/* Run the update.
*/try
{
    $result = $parties->update('start', 0, -1, $values, $columns);
}catch (Exception $e)
{
    print("Error: $e\n");
    exit(1);
}

/* Output the returned values.
*/print("Count: $result->count\n");
print("Hits: $result->hits\n");
print("Rows:\n");foreach ($result->rows as $row)
{
    $rowNum = $row['rownum'];
    $irn = $row['irn'];
    $first = $row['NamFirst'];
    $last = $row['NamLast'];

    printf("\t%d. %s, %s (%d)\n", $rowNum, $last, $first, $irn);
}
exit(0);

If updating records is allowed, the example will produce output similar to the following:

Count: 1

Hits: 1

Rows:

1. Froome, Christopher (435)

The remove method is used to remove one or more existing records.

Arguments

The method takes three arguments:

• flag

• offset
• count

  These arguments define the starting position and size of the block of records to be removed. They are identical to those used by the fetch and update methods.

Return value

The method returns an integer that specifies the number of records that were removed.

Example

/* Find all parties records that have a first name of "Christopher" and a last
** name of "Froome".
*/
$parties = new IMuModule('eparties', $session);
$terms = new IMuTerms();
$terms->add('NamFirst', 'Christopher');
$terms->add('NamLast', 'Froome');
$parties->findTerms($terms);

/* Remove all of the matching records.
*/try
{
    $result = $parties->remove('start', 0, -1);
}catch (Exception $e)
{
    print("Error: $e\n");
    exit(1);
}
print("Removed $result record(s)\n");
exit(0);

If removing records is allowed, the example will produce output similar to the following:

Removed 1 record(s)