Accessing Objects in Your External Database

The ExternalIterator class, the ExternalCollection class, and its subclasses provide methods with behavior similar to that of the methods provided by the corresponding JADE classes. For details, see Chapter 1 of the JADE Encyclopaedia of Classes.

You can access objects (or records) in your external database by using the getAtKey method of the ExternalDictionary class, as shown in the following example.

getEmployee;
vars
    ed  : EmployeesByLastNameDict;  // an external dictionary
    emp : Employee;                 // an external object
begin
    create ed;
    emp := ed.getAtKey("D");
    write emp;
epilog
    delete ed;
end;

In this example, EmployeesByLastNameDict is an index in the relational database that has been described to JADE by the External Schema Wizard. You can also use the ExternalDictionary and ExternalIterator class dictionary and iterator methods and the foreach instruction to access entries in an external collection sequentially.

The following example shows the use of the foreach instruction.

vars
    ed  : EmployeesByLastNameDict;  // an external dictionary
    emp : Employee;                 // an external object
begin
    create ed;
    foreach emp in ed do
        listBoxEmployees.addItem(emp.employeeName);
    endforeach;
end;

The following example shows the use of an iterator.

vars
    ed   : EmployeesByLastNameDict; // an external dictionary
    emp  : Employee;                // an external object
    iter : ExternalIterator;
begin
    create ed;
    iter := ed.createIterator;
    while iter.next(emp) do
        listBoxEmployees.addItem(emp.employeeName);
    endwhile;
epilog
    delete ed;
    delete iter;
end;

To add objects (or rows) to your external database, use the ExternalCollection class createObject method and the ExternalObject class update method, as shown in the following example.

createEmployee;
vars
    ed  : EmployeesByLastNameDict; // an external dictionary
    emp : Employee;                // an external object
begin
    create ed;
    emp := ed.createObject;        // creates a reference to the object
    emp.employeeName := "Sid";
    emp.update;                    // updates collection with the new object
epilog
    delete ed;
end;

To update an object, use the ExternalObject class update method, as shown in the following example.

updateEmployee;
vars
    ed  : EmployeesByLastNameDict; // an external dictionary
    emp : Employee;                // an external object
begin
    create ed;
    emp := ed.last;
    if emp.isUpdatable then
        emp.region := "ZZ";
        emp.update;
    else
        write "not updateable";
    endif;
epilog
    delete ed;
end;

The beginExternalTransaction and commitExternalTransaction methods provided by the ExternalDatabase class enable you to start an external database transaction if your external database supports transactions.

You can use this method at the start of a series of updating operations (that is, creates, deletes, or updates) that must be applied atomically to the target database to ensure consistency and the ability to recover. (Updates are committed immediately, by default, if they are not within a beginExternalTransaction and commitExternalTransaction pair of instructions which delays the commitment of updates until the commitExternalTransaction method is called.)