The Clear ODB SDK comes with a number of examples of code (actually one at this point). The ConsoleApplication example is very helpful as a first introduction.
In the templates folder in the Clear ODB SDK installation ("C:\Program Files\Clear Objects\ClearODB SDK 0.6.3\templates" in the default install location) you will find project templates. You can use them as tutorials or base for your own projects. Before using them, copy them to a new location such as My Documents or some other work directory.
Copy the whole ConsoleApplication folder to MyDocuments or somewhere you have write access. (Click to expand)
Open the ConsoleApplication.sln (requires Visual Studio 10). (Click to expand)
The solution has 2 projects:
This project is used for creating users and databases. It has one DOS batch file that uses the Clear ODB Admin tool (OSM.exe) in its command line mode (it can be run in interactive mode as well, see the Clear ODB Admin user guide for further details). The batch file assumes that the server's root user has a blank password, so if it has been changed you should change the root password in the batch file.
Also, if the server was installed in a non-default location you might have to update the path to the admin tool, i.e. the line saying 'set OSMPath="C:\Program Files\Clear Objects\ClearODB\bin\OSM.exe"'.
To run the CreateDB.bat, simply rebuild the CreateDB project:
When successfully run, the output should look like this:
The following shows the output if the ClearODB service is not active:
This is a small example that defines two classes (one a sub-class of the other). The program connects to the database, selects all existing instances of the sub-class, creates a new instance of the class and make updates to all objects it found, and eventually commits all the modified objects and the new to the database.
The Clear ODB API uses reflection to help serialize the objects prior to sending to the database. As C++ does not have its built-in reflection functionality, Clear ODB uses a modified version of Clear Object's Object Serialization Library. You will have to add a minimum amount of declarative code for the reflection to work (see below and for further reading on the OSL, see the OSL reference (the version control features of OSL is not fully implemented for Clear ODB).
Classes must adhere to the following rules:
For any source files that uses the reflection API, the <clearodb/rfx.h> header must be included. For any source files that uses the database objects (odb and queue), the <clearodb/odb.h> must be included. In this project, the Main.cpp includes both header files, while the class definitions BaseClass.h, and MyClass.h only includes the <clearodb/rfx.h>.
First part of Main.cpp shows how to initialize the Clear ODB library and how to connect to the database. You must first call the clearodb::init() function as this initializes the reflection library.
You interact with the database through the clearodb::odb class and use its connect() function to establish a connection. If you update the connection details in CreateDB.bat, make sure you update the details in the beginning of the main() function.
The define<>() statements tells the database about your classes. It is required to run this once for each class that will be stored. In the current pre-release version, the define<>() statement is not checked against permissions; however, in the future this will be subject to access control and may fail for a user that does not have the rights to execute this command. There is no ill-effect from running the command multiple times other than performance (i.e. you should only run the define<>() statement once for any new classes for example).
As the main() function uses the clearodb::odb class, we need to include both <clearodb/rfx.h> and <clearodb/odb.h>.
The bottom part of the Main.cpp shows how to select objects and commit them to the database.
The select<>() statement selects objects of the specified class and may be used to select objects based on their member field values (see for more examples of select<>()). The objects are returned as pointers in an STL container (in this example the std::vector is used).
The updated() function is used to indicate that an object has been updated without sending it to the database. If you are making a number of updates to a number of objects, it is better from a performance point of view to make a number of changes first and then commit all updated objects to the database at the same time.
The commit_all() is here used to commit all objects that has previously been set as updated. You can also use commit() on objects instead of the updated()-commit_all() combination to directly commit objects or sequences of objects. See for more examples on updates and commits.
The most noteworthy about this class is that it includes the <clearodb/rfx.h> header and have the two static declarations:
The static function clearodb_class_init() is called by the reflection initialization code (which is run when clearodb::init() is called - see above). See further down for implementation. For MyBase this is an empty function as there are no members or base classes.
The declaration osl_class(), is a static object much like the Class or Type classes in Java or .Net. See MyBase.cpp for definition.
The class name must be specified in the osl_class' definition, as below. This is the name Clear ODB will use to identify the class.
The clearodb_class_init() is for declaring member fields and base classes. In this case, MyBase does not have any members and is not inherited, so the function is empty.
The header file for MyClass is similar to the MyBase header. Don't forget to include <clearodb/rfx.h>.
MyClass.cpp is basically the same as MyBase with the difference that MyClass has a base class and member fields that must be declared as shown below. Base classes are declared with the c.base<>() function and fields with c.member(). Order does not matter. You can still declare members in the class declaration without including them in clear_odb_init() with the only effect that they are not stored in the database but rather act as transient members which gets there values by the class' default constructor.
To build the application, simply right-click on the project and select Build
If the Clear ODB SDK is correctly installed, the build should be successful. Note that the Clear ODB server generally does not have to be installed on the same machine as the SDK (however the CreateDB.bat project in this example assumes it is).
Start a DOS command prompt and change directory to the solution's build directory.
The first run will show "Found 0 objects." as there are no objects yet in the database. The second run and onwards should show an increasing number of objects.