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
