This chapter will guide you through the steps needed to create a simple IOPC 2-based application. We will start with library initialization and termination and then we will continue with metamodel definition and metamodel description browsing. Further we will describe how the database drivers and their extensions are used and finally, we will discuss usage of the persistence and caching layers to create a code that can persists or load database objects from the database.

Examples from this guide can be found on the enclosed DVD. To run the examples right away, you can use the included VMWare image which contains Eclipse CDT workspaces of both the library and the examples. For more information on the DVD see Appendix D, DVD content.

The IOPC 2 library can be used in several configurations (the section called “Library architecture”). Depending on the selected configuration, corresponding initialization and termination routines must be called. These routines are listed in the Table A.1, “Library configurations and their initialization/termination routines”. Configurations are ordered by ascending complexity and so by amount of features they provide. First row of the table contains the most basic configuration - the iopccommon library. Libraries/configurations in following rows depend on libraries from previous rows and also implicitly call their initialization/termination routines. So calling the initialization/termination routine only for the selected configuration is sufficient. There exist also header files with the "Headers" suffix in their names (like iopcMetaHeaders.h or iopcDbHeaders.h), which include most commonly used header files for the selected configuration.

Basic library setup for a configuration that uses IOPC 2 as a database access library can then look like this:

// Include all commonly used headers for the
// iopcdb configuration
#include "iopcdb/iopcDbHeaders.h"

// IOPC 2 structures are defined within the iopc napespace
using namespace iopc;

int main(int argc, char *argv[])
  try {
    // Initializes the library and also sets the LogWriter masks
    // Throws an exception if not successful
  	IopcDb::init(LogWriter::ERROR, LogWriter::ERROR | 
  	// ... 
    // Library cleanup. Releases allocated resources, 
    // closes open connections.
  } catch (IopcException& e) {
    // Error handling

First parameter of the IopcDb::init specifies mask for messages written to standard output, second parameter specifies mask for the log file which is created by the library at its initialisation. Its name is iopc_log.txt by default, but it can be overridden in the third (not shown) parameter of the IopcDb::init method.

The logger masks filter the log messages by their category. Supported categories are:

  • ERROR - messages generated usually as a result of an exception that prevented required operation to be finished. They can be generated by the user application.
  • WARNING, INFO - warning or informational messages. They can be generated by the user application.
  • INFO_SQL - SQL trace messages representing SQL statements that have been sent to the underlying database. Messages in this category are exclusively generated by the iopcdb library.
  • DEBUG - messages useful for debugging purposes. It can be also disabled by commenting out the IOPC_DEBUG macro in the iopccommon/trace.h file. This macro should be undefined in release versions of IOPC 2.
  • TRACE - more detailed messages which trace the library execution. Turning this filter on may result in large amount of logged messages. May be also disabled by commenting out the IOPC_TRACE macro in the iopccommon/trace.h file. Release versions of IOPC 2 should have this macro undefined.

If an error occurs during any of library activities an exception is thrown. All exceptions thrown by the IOPC 2 library are descendants of the IopcException class. For a detailed list of all exception types please refer to the library documentation.