Connection Considerations

When you generate classes for your mapping, a class called <class>Datastore is generated; it extends one of the Datastore base classes, depending on which access method you use (IDatastoreDB2 for DB/2; IDatastore for ESQL; or IDatastoreODBC for ODBC). Objects of <class>Datastore represent connections to the datastore from which the class was mapped. A <class>Datastore object can be used by any number of <class> objects at a time, but a <class> object can only use one <class>Datastore object at a time.

This section discusses the three levels of datastore assignment:

Then it addresses different datastore transaction scenarios:

The Application Datastore
Your data access application has a datastore associated with it by default. All <class>, <class>Manager, and <class>DataIdManager objects use this datastore connection for performing add, update, delete, retrieve, select, open, refresh, and user-defined method actions, unless either the default <class> datastore or the object's datastore has been set (see the following sections).

Initially, the application datastore is null, but all IDatastore, IDatastoreDB2, and IDatastoreODBC constructors check to see whether the application datastore is null, and if it is, set the application datastore to the newly constructed datastore object. You can use aDatastore.setAsApplicationDefault to set the application datastore to the current datastore object. You can set the application datastore to null by calling the aDatastore.removeAsApplicationDefault method (where aDatastore is the current application datastore).

Use the applicationDefault method to return the current application datastore.

The Default Class Datastore
If you prefer to determine class-by-class which datastore objects will use, you can associate a datastore with a particular class by using the default class datastore setting (also called the default datastore). All <class>, <class>DataId, <class>Manager, and <class>DataIdManager objects use the default datastore connection for performing add, update, delete, retrieve, and user-defined method actions, unless the object's datastore has been set (see the following section).

Initially, the default datastore is null, but all <class>Datastore constructors change a null default datastore setting to the newly constructed datastore object. You can use the <class>.setDefaultDatastore(aDatastore) method to set the default datastore to any datastore object, or to null by not passing in any parameter. You can also use aDatastore.setAsDefaultDatastore to set the default datastore to the current datastore object.

Use <class>.defaultDatastore to return the current <class>-level default datastore.

The Object's Datastore
Finally, datastore settings can be made at the object's level (that is, for a particular instance of <class>). When a <class> object's datastore setting is set to a particular datastore (that is, not null), then the object will use that datastore connection for performing add, update, delete, retrieve, and user-defined method actions.

<Class> objects created by calling the default constructor have a null object's datastore. If you pass in a datastore object to the constructor, it will set the object's datastore to that datastore. You can use the a<Class>Object.setObjectsDatastore(aDatastore) method to set the object's datastore to any datastore object, or to null, by not passing in any parameter.

Use a<Class>Object.objectsDatastore to return the current <class> object's datastore.

Similar object-level datastore set and get methods exist for Manager objects. If you set the <class>Manager object's datastore, then each transaction done on fetched objects will be done via that datastore. The default datastore for the <class>Manager class is always the <class> default datastore.

Which Datastore Will Your Object Use? The Current Datastore
Because you have three levels of datastore assignment, it is important to know which connection an object will use when it accesses the database. All transactions on an object use the object's current datastore. The a<Class>Object.currentDatastore method returns the current datastore for the object. The currentDatastore method determines which datastore is current as follows:

Note that if the currentDatastore method returns null, then calling connect or attempting a transaction throws an exception; you cannot access a database when all datastore settings for the current object are null.

Single Active Transaction for the Application
The most common and easy to use scenario is when you use one datastore, and therefore have only one active transaction for the entire application. In this situation, you set the application datastore once (implicitly, using a datastore constructor), and all objects access the database through that one transaction. The following example shows how to implement this scenario. Consider two classes, Employee and Department, both mapped from one DB/ 2 database, SAMPLE:

IDatastoreDB2    aDatastore;            // aDatastore is set to be application datastore
Employee         anEmp;
Department       aDept;

aDatastore.setDatastoreName("SAMPLE");

aDatastore.connect();
{                                       // start the transaction with the first retrieve, add, etc.
  // Do some actions on anEmp and aDept
}
aDatastore.commit();                    // complete the transaction

Similarly, you could do the following, which still results in both classes using the same application datastore:

EmployeeDatastore  anEmpDS;  // Uses database name you specified in the mapping.
Employee           anEmp;
Department         aDept;

anEmpDS.connect();
{                                       // start the transaction with the first retrieve, add, etc.
  // Do some actions on anEmp and aDept
}
anEmpDS.commit();                       // complete the transaction

By creating the datastore object with the EmployeeDatastore constructor, you avoid having to enter the database name because the generated code picks it up from the mapping settings. This datastore, anEmpDS, not only becomes the default datastore for the Employee class, but also sets itself as the application datastore (this assumes that this code runs before any other part of the application has set the application datastore to something other than null). So, anEmpDS is also the current datastore for the Department class, and Department objects use it for all their transactions.

One Active Transaction per <Class>
The next-to-easiest scenario is to use one active transaction for each <class>. In this scenario, you set each <class>'s default datastore, and, while there is still only one active transaction per class, it is independent from the transactions of other classes. To simplify this scenario, you may want to set autoCommit to true for each datastore, so that each method call is committed to the database immediately and automatically. Then you don't have to keep track of which transactions you have completed, and which you have not.

For example, suppose your application has two <class> classes, Employee and Department. If they are mapped from different databases, it is impossible to use the same datastore connection. Even if they are from the same database, you may want to keep their transactions separate. In this case, you would do the following:

EmployeeDatastore      anEmpDS; // uses database name you specified in the mapping.
DepartmentDatastore    aDeptDS;

Employee               anEmp;
Department             aDept;

anEmpDS.connect();
aDeptDS.connect();
{
  // Do some actions on anEmp and aDept
}
anEmpDS.commit();      // Here, only anEmp transaction is committed.  If you now try to disconnect
                       // from aDeptDS, you may get an exception, or you may lose the changes in
                       // the transaction.

In this scenario, you use only the default (class-level) datastores for transactions; the application datastore, although it was set by the first datastore constructor (EmployeeDatastore in the above example), is not used.

Multiple Active Transactions per <Class>
There may be situations when you wish to handle transactions at the object level. In this case, you set the object's datastore for each object. For example, if you have a <class> called Employee, you might want to handle transactions for employees with more than ten years' experience separate from transactions on those with less than ten years' experience. The following code shows what you might do:

Employee              anEmp;

EmployeeDatastore     anEmpDSLessThanTen;
EmployeeDatastore     anEmpDSMoreThanTen;

{
  {
    // Get input into anEmp
  }
  if (anEmp.getYearsExperience() < 10) anEmp.setObjectsDatastore(anEmpDSLessThanTen);
    else anEmp.setObjectsDatastore(anEmpDSMoreThanTen);
} 
// Repeat above for a collection of objects.

anEmpDSLessThanTen.connect();
anEmpDSMoreThanTen.connect();
{
  // Do some actions on these objects
}
anEmpDSLessThanTen.commit();
anEmpDSMoreThanTem.commit();

If you repeat this for a group of objects, one transaction will handle some objects, and the other transaction will handle the rest, depending on the number of years of experience. These transactions commit changes to the database, as specified later in the code. Although the class default datastore or application datastore may have been used to retrieve the objects originally, they are not used for transactions, once the objects' datastores have been set.

Other Typical Transaction Scenarios
Depending on the number of <class>es and objects you use, and depending on how much control you want to have, you can have any combination of the above scenarios. One example could be three classes: Employee, Department, and Vehicle, all mapped from the same database. In this case, it might make sense to have Employee and Department classes use the same datastore, but to have the Vehicle class use its own datastore. Your code might look like this:

VehicleDatastore      aVehDS;   // sets default datastore for Vehicle class
EmployeeDatastore     anEmpDS;  // sets default datastore for Employee class

Department            aDept;

Department.setDefaultDatastore(anEmpDS);  // sets default datastore for Department to anEmpDS

Now, all Employee and Department objects will use the EmployeeDatastore for transactions, while all Vehicle objects will use the VehicleDatastore.

If you are unsure which transaction is handling a particular object, you can always check by calling the currentDatastore method.



Commit and Rollback
Connect and Disconnect


Data Access Class Library and Generated Code Reference