Windows: C++ Application Development

Printer-friendly version

This topic provides details about developing Objectivity/C++ applications on Windows platforms. You should use this topic in conjunction with the Objectivity/C++ and Objectivity/DDL books.

Note: If you want to learn how to use various Objectivity/C++ features, consider downloading and running some of the sample C++ applications.

Linking Applications to Objectivity/DB

On Windows, you dynamically link your C++ applications to Objectivity/DB. The appropriate Objectivity/DB libraries are normally linked automatically, so you do not need to specify libraries explicitly to the linker; see Automatic Linking of Objectivity/DB Libraries.

The following subsections describe the libraries required for linking to Objectivity/DB, guidelines for combining Objectivity/DB libraries with runtime libraries from other vendors, and what you need to know about automatic linking.

Libraries for Dynamic Linking

The following table lists the import libraries for linking applications dynamically to Objectivity/DB.

Table 1: Objectivity/DB Dynamic Link Import Libraries
Library File Description
oodbi.lib Objectivity/DB import library
oodbid.lib Debug version of the Objectivity/DB import library

The following table lists the dynamic link libraries (DLLs) that must be available at runtime to applications that are linked dynamically to Objectivity/DB.

Table 2: Objectivity/DB Dynamic Link Libraries
DLL Filea Description
oodbxx.dll Release version of the Objectivity/DB DLL (corresponds to the oodbi.lib import library)
oodbxxd.dll Debug version of the Objectivity/DB DLL (corresponds to the oodbid.lib import library)

a. The digits xx in a DLL name correspond to the current Objectivity/DB release.

Release applications link to the Objectivity/DB import library (oodbi.lib) and use the corresponding Objectivity/DB DLL (oodbxx.dll). In contrast, debug applications link to the debug-compatible import library (oodbid.lib) and use the corresponding DLL (oodbxxd.dll). This is necessary because the Visual C++ debug runtime libraries redefine basic memory allocation routines. Failure to link to the correct library may result in a runtime exception, left-over journal files, or data corruption.

Automatic Linking of Objectivity/DB Libraries

When you build your application, the appropriate Objectivity/DB libraries are linked automatically, so you do not need to specify them explicitly to the linker. This is because the oo.h include file contains pragmas that direct the linker to link to the correct Objectivity/DB libraries. The pragmas in the oo.h file are similar to the pragmas defined by Microsoft in the afx.h include file. (oo.h is included in your application automatically when you run the DDL processor.)

The following table shows the runtime libraries that are selected automatically when you link a release or debug version of an application.

Table 3: Compatible Runtime Libraries Selected for Linking 
Application Type Visual C++ Multithreaded Runtime Library Objectivity/DB Library
Release version msvcrt.lib + $(winlibs) oodbi.lib
Debug version msvcrtd.lib + $(winlibs) oodbid.lib

When you develop using the Visual C++ Integrated Development Environment (IDE), your project selects the Visual C++ runtime library, the Objectivity/DB library, and other libraries based on the value you set for either of the link properties listed in the following table.

Table 4: Link Properties Controlling Library Selection 
Property Value
Runtime Library Multi-threaded DLL or
Debug Multi-threaded DLL
Use of MFC Use MFC in a Shared DLL

You should set one of these properties, but you do not need to set both; the MFC link property automatically sets the Visual C++ runtime link property. Regardless of the property you choose, you must set it to select a DLL (either for a release or a debug version).

Linking Explicitly

In general, you should take advantage of automatic linking whenever possible. If you prefer to specify Objectivity/DB libraries to the linker explicitly, you must preserve the following link order:

  1. User-created object files and libraries
  2. Objectivity/DB library
  3. Microsoft Foundation Classes (MFC) libraries
  4. Visual C++ runtime library

To specify libraries explicitly in the Visual C++ IDE:

  1. In the Solution Explorer, right-click your project and click Properties.
  2. In the Property Pages dialog, click the Linker folder and click the Input property page.
  3. Click the Additional Dependencies property and enter the desired libraries, preserving the link order shown above.
  4. Click the Ignore All Default Libraries property and choose Yes.
  5. In the Property Pages dialog, click OK.

Compatibility With Other Runtime Libraries

Objectivity/DB libraries link only to the dynamic multithreaded Visual C++ runtime libraries. If you use libraries from other vendors, these libraries must be compatible with the same version of the multithreaded Visual C++ runtime libraries. Using incompatible libraries may result in either a link-time failure or data corruption.

Because you link dynamically to Objectivity/DB, you should also link dynamically to any third-party libraries. Mixing static and dynamic link libraries may result in either a link-time failure or data corruption.

Linking to Additional Objectivity Products and Features

If an application uses Objectivity/C++ persistent collections or the C++ programming interfaces of other Objectivity products, the application must include the header files that are specified in the documentation for the feature or product. When a release or debug application includes such header files, the appropriate release or debug import libraries are linked automatically. In all cases, the corresponding dynamic link libraries (DLLs) must be available at runtime.

Linking to Persistent Collections

For Release 9.3 (or later) Persistent Collections

If the persistent collections used by your application are all implemented with the Release 9.3 (or later) scalable collection structure (for example, ooTreeSetX), you should include the header file ooCollectionBase.h. No special linking is necessary, other than linking to the Objectivity/DB library.

For pre-Release 9.3 Persistent Collections

If any of the collections used by your application are implemented with the pre-Release 9.3 scalable collection structure (for example, ooTreeSet), you must include the header file ooCollections.h. The following table lists the collection-specific import libraries; the release or debug import library is linked automatically when you include the ooCollections.h header file.

Table 5: Dynamic Link Import Libraries For pre-Release 9.3 Persistent Collections
Library File Description
ooco.lib Multithreaded import library for Objectivity/C++ persistent collections
oocod.lib Debug version of the multithreaded import library for Objectivity/C++ persistent collections

The following table lists the DLLs that must be available at runtime to applications that are linked dynamically to libraries in Table 5.

Table 6: Dynamic Link Libraries For pre-Release 9.3 Persistent Collections
DLL Filea Description
oocoxx.dll DLL for Objectivity/C++ persistent collections
oocoxxd.dll Debug version of the DLL for Objectivity/C++ persistent collections

a. The digits xx in a DLL name correspond to the current Objectivity/DB release.

Linking to Objectivity/DB Active Schema for C++

The following table lists the import libraries for Objectivity/DB Active Schema for C++ (Active Schema), which enables applications to dynamically read and modify a federated-database schema. The release or debug import library is linked automatically when you include the Active Schema header file.  

Table 7: Active Schema Dynamic Link Import Libraries 
Library File Description
ooas.lib Active Schema multithreaded import library
ooasd.lib Debug version of the Active Schema multithreaded import library

The following table lists the DLLs that must be available at runtime to applications that are linked dynamically to Active Schema.

Table 8: Active Schema Dynamic Link Libraries 
DLL Filea Description
ooasxx.dll Active Schema DLL
ooasxxd.dll Debug version of the Active Schema DLL

a. The digits xx in a DLL name correspond to the current Objectivity/DB release.

Automatic Loading of Parallel Query Feature

When your application initiates a parallel query, the appropriate dynamic link library is loaded automatically at runtime. The following table lists the DLLs that must be available at runtime to applications that perform parallel queries.  

Table 9: Parallel Query Dynamic Link Library
DLL Filea Description
oopqexx.dll DLL for parallel queries

a. The digits xx in a DLL name correspond to the current Objectivity/DB release.

Automatic Loading of Predicate Query Language Feature

When your application uses the predicate-query language (PQL) to qualify persistent objects through a scan or parallelScan operation, or uses PQL to find qualified destination objects through a linkName method, the appropriate object qualification library is automatically loaded at runtime. The following table lists the DLLs that must be available at runtime to applications that use the predicate query language feature.  

Table 10: Predicate Query Language Dynamic Link Libraries 
DLL File Description
ooObjectQualification.dll
ooObjectModelxx.dll
ooSchemaModelIntxx.dll
oopcre.dll
ooasxx.dll
DLL for the predicate query language and the libraries on which it depends.

Linking to Object Qualification Library When Using ObjectQualifiers

The following table lists the import libraries for using an ObjectQualifier to qualify individual objects. The release or debug import library is linked automatically when you include the ObjectQualifier.h header file.  

Table 11: Predicate Query Language Dynamic Link Import Libraries
Library File Description
ooObjectQualification.lib Predicate query language import library
ooObjectQualificationd.lib Debug version of the predicate query language import library

The following table lists the DLLs that must be available at runtime to applications that use ObjectQualifier instances.  

Table 12: Predicate Query Language Dynamic Link Libraries 
DLL File Description
ooObjectQualification.dll
ooObjectModelxx.dll 
ooSchemaModelIntxx.dll 
oopcre.dll 
ooasxx.dll
DLL for the predicate query language and the libraries on which it depends.

Automatic Loading of the In-Process Lock Server

An Objectivity/C++ application can start an in-process lock server (IPSL) without linking to any special import library. Instead, the appropriate IPLS dynamic link library is loaded automatically at runtime when the in-process lock server is started. The following table lists the DLLs that must be available at runtime to applications that use IPLS.  

Table 13: IPLS Dynamic Link Libraries 
DLL Filea Description
ooiplsxx.dll DLL for IPLS
ooiplsxxd.dll Debug version of the IPLS DLL

a. The digits xx in a DLL name correspond to the current Objectivity/DB release.

Linking a Lock-Server Performance-Monitoring Program

The following table lists the import libraries for linking a custom C++ program that monitors how your database applications interact with a running lock server. The information collected by such a program can help you analyze application performance (for more information, see Monitoring Lock-Server Performance). The release or debug import library is linked automatically when you include the oolspm.h header file.

Table 14: Dynamic Link Import Libraries 
Library File Description
oolspmi.lib Multithreaded import library for custom lock-server performance-monitoring programs
oolspmid.lib Debug version of the multithreaded import library for custom lock-server performance-monitoring programs

The following table lists the dynamic link libraries (DLLs) that must be available at runtime to lock-server performance-monitoring tools.

Table 15: Dynamic Link Libraries 
DLL Filea Description
oolspmxx.dll DLL for custom lock-server performance-monitoring programs
oolspmxxd.dll Debug version of the DLL for custom lock-server performance-monitoring programs.

a. The digits xx in a DLL name correspond to the current Objectivity/DB release.

User-Created DLLs That Export Objectivity/DB Persistent Data

You can create DLLs whose interfaces export Objectivity/DB persistent data. The following subsections show how to export Objectivity/DB persistent data from a user-created DLL, and provide guidelines for linking and loading these DLLs. These subsections assume that you already know how to create a DLL.

Exporting Persistent Data From a User-Created DLL

This section describes how to export persistent data from a DLL. You must be familiar with the use of the Microsoft Extended Attribute Syntax __declspec(dllexport) and __declspec(dllimport).

To export Objectivity/DB persistent data:

  1. Choose a placeholder symbol name to represent the extended storage attribute—for example, MY_STORAGE_SPECIFIER.
  2. Specify the extended storage attribute in the class definition of each class to be exported from the DLL. You can use either the placeholder symbol or the __declspec(dllexport) syntax. For example, assume you choose MY_STORAGE_SPECIFIER as the placeholder symbol and you want to export MyClass from your DLL. You specify the extended storage attribute in the definition of MyClass using either of the following alternatives:
    class MY_STORAGE_SPECIFIER MyClass : public ooObj {
    or
    class __declspec(dllexport) MyClass : public ooObj {
  3. Run ooddlx.exe, using the -storage_specifier option to pass the placeholder symbol to it. For example:
    ooddlx -storage_specifier MY_STORAGE_SPECIFIER
    When run with this option, ooddlx.exe:
    • Directly passes any instance of the specified placeholder symbol to the output.
    • Converts all instances of __declspec(dllexport) to the specified placeholder symbol on output.

    Note: If you run ooddlx.exe without the -storage_specifier option, all instances of __declspec(dllexport) are passed directly through to the output without being translated.

  4. Compile your DLL using the -D compiler option to replace the placeholder symbol with __declspec(dllexport). For example:
    -DMY_STORAGE_SPECIFIER=__declspec(dllexport)

    An import library will be generated automatically when you link the DLL, so you may not need a .def file.

  5. Compile the applications that use the DLL with the -D compiler option to replace the placeholder symbol with __declspec(dllimport). For example:
    -DMY_STORAGE_SPECIFIER=__declspec(dllimport)

Linking User-Created DLLs to Objectivity/DB

Linking a user-created DLL to Objectivity/DB is similar to linking an application to Objectivity/DB. That is, the same considerations apply for combining Objectivity/DB libraries with other third-party libraries, and for automatic linking.

Incorporating a User-Created DLL

Linking an Application to an Import Library

You can incorporate a user-created DLL into an application by linking the application to an import library for the DLL.

Loading a User-Created DLL

You can incorporate a user-created DLL into an application by using the Win32 LoadLibrary function. This is an alternative to linking the application to an import library for the DLL. When you load a user-created DLL using the LoadLibrary function, you must also link the DLL and your application as stated in Linking User-Created DLLs to Objectivity/DB.

If you intend to use the FreeLibrary function, you should build DLLs with the following option: OO_SKIP_AUTO_CLEANUP_AT_EXIT. Using this option enables you to use the FreeLibrary function without the function invalidating your sessions during auto-cleanup. You can specify the option in your Visual C++ project definition. You must call ooObjy::shutdown before exiting your application.

If you intend to use the Win32 LoadLibrary function to load a user-created DLL, you should not use the __declspec(thread) Visual C++ language extension on any data in that DLL. Using __declspec(thread) in this way will result in a runtime exception. This is a known Microsoft Visual C++ restriction.

Application Programming Issues

Using the Microsoft Foundation Classes

Objectivity/DB is compatible with the Microsoft Foundation Classes (MFC) as long as the two class hierarchies are kept separate. Mixing the class hierarchies (either by inheritance or by object inclusion) is not supported. The reason for this restriction is that the class library implementation may rely on in-memory pointers, which become invalid once the object is written to disk.

The majority of MFC classes deal with GUI objects for which persistence makes little sense. You may be tempted to use the MFC collection classes in your persistent classes, but for the reason stated above the collections classes will not work as expected and you should avoid using them in your persistent classes (consider using Objectivity/C++ collection classes instead). Furthermore, you should not include MFC header files in your DDL schema files.

Signal Handling

The Objectivity/DB predefined signal handler catches the following signals:

  • SIGABRT; SIGFPE; SIGILL; SIGINT; SIGSEGV; SIGTERM

    but does not catch the following signals and Windows events:

  • SIGBREAK;

    the ExitProcess function; any unhandled exceptions that do not map directly to the caught signals; stack overflow

In general, if your application encounters one of the events that Objectivity/DB does not catch, you should recover your transactions using the oocleanup.exe tool described in Objectivity/DB Administration.

Handling Microsoft Visual C++ Name Decoration

The Microsoft Visual C++ compiler uses its own algorithm to decorate (mangle) the names of functions and variables. The algorithm is different from that of cfront or other C++ compilers. If you encounter linking problems in your code because an external declaration is not found, the compiler may have decorated the function or variable name.

Also note that the Microsoft C++ compiler decorates the names of global variables, whereas most UNIX C++ compilers do not. If you have global variables that are shared between C++ and C modules, make sure that you declare and define these variables as extern "C" in your C++ code.

Visual C++ Development

This section describes the following tasks for creating new Objectivity/C++ projects using Visual C++ 9.0 or Visual C++ 10.0.

Preparing to Create an Objectivity/C++ Project

Before you create your new project, perform the following steps:

  1. List any existing DDL files that define the persistence-capable classes for your application. Similarly, make a preliminary list of planned DDL files that are not yet created. (You can create these files later with Objectivity/Assist or with a text editor.) For information about DDL files and the files that you will generate from them, see Objectivity/C++ Data Definition Language.
  2. Choose the system name (fdSysName) to be used. The system name will be specified as the base filename for the federated database’s boot file and system-database file. For complete information about federated databases, see "Federated Database Tasks" in Objectivity/DB Administration.
  3. If you have not done so already, set up the Visual C++ IDE to work with Objectivity/C++.

Creating a New Objectivity/C++ Project

The steps in this section organize your project files similar to the Objectivity/C++ sample applications available for download.

Note: If you change this recommended organization, you may have to adjust some of the steps in Adding a Pre-Build Event to Create a Federation.

  1. In the Visual C++ IDE, click File > New > Project.
  2. In the New Project dialog:
    • Click Visual C++ in the left pane.
    • In the center pane, click the desired project template—for example, Win32 Console Application.
    • Specify the name and location for the project. This step creates a storage folder with the project’s name in the specified location.
    • Uncheck Create directory for solution.
    • Follow any additional prompts, and click OK.
  3. In the Solution Explorer, right-click your project and click Add > New Filter to add the following filter:
    • Persistent Classes— Project subfilter for files associated with your project’s persistence-capable classes.
  4. In the Solution Explorer, right-click your project’s Persistent Classes filter and click Add > New Filter to add each of the following subfilters:
    • DDL Files—Subfilter for DDL files (.ddl).
    • DDL Generated Files— Subfilter for files generated from DDL files (.h, _ref.h, and _ddl.cpp).
    • Source—Subfilter for any C++ source files (.cpp) implementing persistence-capable classes.
  5. In Windows Explorer, create subfolders for organizing project files in storage:
    • Find your new project’s storage folder.
    • Within the project’s storage folder, create the storage folders listed below:
      • data— Storage folder for files associated with your project’s federated database.
      • ddlFiles— Storage folder for your project’s DDL files (.ddl) and all accompanying generated files (.h, _ref.h, and _ddl.cpp).
      • src—  Storage folder for the C++ source files (.cpp) that implement your project’s persistence-capable classes. Other source files (.h and .cpp) can optionally be stored here, as well.
    • Move any existing DDL files into the ddlFiles storage folder.
  6. Add each planned DDL file to your project:
    • In the Solution Explorer, right-click the DDL Files subfilter of the Persistent Classes filter and click Add > New Item.
    • In the Add New Item dialog, click Browse and select the ddlFiles storage folder.
    • In the left pane, click Visual C++. In the center pane, click the C++ File (.cpp) template.
    • In the Name box, enter the name of the planned DDL file, including the .ddl filename extension, and click Add.
  7. Add any existing DDL files to your project:
    • In the Solution Explorer, right-click the DDL Files subfilter of the Persistent Classes filter and click Add > Existing Item.
    • In the Add Existing Item dialog, browse to the ddlFiles storage folder.
    • Display all file types in the dialog. Select the DDL files in the ddlFiles storage folder and click Add.
    • If a dialog asks if you want to create a new rule file, click No.

Adding a Pre-Build Event to Create a Federation

The steps in this section set up your Visual C++ project to a create a federated database when you build the project. These steps assume you have created a project and organized its storage folders as recommended in the preceding section.

Note: If you changed the recommended organization, you may have to adjust some of the steps for adding a pre-build event.

  1. In the Solutions Explorer, right-click the project, and click Properties.
  2. In the left pane, click Configuration Properties, then in the Configuration box, click All Configurations.
  3. If necessary, click to expand Configuration Properties; then, expand Build Events and select its Pre-Build Event property page.
  4. Click the Command Line property and enter:
    if exist "$(ProjectDir)data\fdSysName.boot"
    	oocleanup -local "$(ProjectDir)data\fdSysName.boot" 
    if exist "$(ProjectDir)data\fdSysName.boot"
    	objy DeleteFd -bootfile "$(ProjectDir)data\fdSysName.boot"
    del "$(ProjectDir)data\"*.DB
    objy CreateFd -fdDirPath "$(ProjectDir)data" -fdName fdSysName            

    Note: fdSysName is the chosen system name of the federated database. Put each command and its options on a single line. Arguments to Objectivity/DB tools must be enclosed in double-quotation marks if they specify paths that contain spaces.

    For more information about the oocleanup or objy CreateFd tools, see Objectivity/DB Administration.

  5. Click the Description property and enter:
    Creating Objectivity/DB Federated Database
  6. In the Property Pages dialog, click OK.

Defining a Custom Build Rule to Process DDL Files

The steps in the following subsections set up your Visual C++ project to run the DDL processor as necessary when you build your project. These steps assume you have created a project and organized its filters as recommended in the preceding section.

Note: If you changed the recommended organization, you may have to adjust some of the steps for defining custom build rules.

Visual C++ 9.0

  1. In the Solutions Explorer, select all of the DDL files in the DDL Files subfilter of the project’s Persistent Classes filter. (Hint: Hold the Control key while selecting each file.)
  2. Right-click the selection and click Properties.
  3. In the Configuration box of the Property Pages dialog, click All Configurations.
  4. If necessary, click to expand Configuration Properties; then click Custom Build Step and select its General property page.
  5. Click the Command Line property and enter:
    cd $(InputDir)
    ooddlx "$(InputName)".ddl ..\data\fdSysName.boot
    cd $(ProjectDir)

    Note: fdSysName.boot is the name of the federated-database boot file. For more information about the ooddlx command, see Objectivity/C++ Data Definition Language. Arguments to the DDL processor must be enclosed in double-quotation marks if they specify paths that contain spaces.

  6. Click the Description property and enter:
    Building DDL File $(InputPath)
  7. Click the Outputs property and enter:
    $(InputDir)$(InputName)_ref.h
    $(InputDir)$(InputName)_ddl.cpp
    $(InputDir)$(InputName).h
  8. Click Additional Dependencies and enter the boot-file name:
    data\fdSysName.boot
  9. In the Property Pages dialog, click OK.

Visual C++ 10.0

  1. In the Solutions Explorer, select all of the DDL files in the DDL Files subfilter of the project’s Persistent Classes filter. (Hint: Hold the Control key while selecting each file.)
  2. Right-click the selection and click Properties.
  3. Click Item Type, click Custom Build Tool, then click Apply.
  4. In the Configuration box of the Property Pages dialog, click All Configurations.
  5. If necessary, click to expand Configuration Properties; then click Custom Build Tool and select its General property page.
  6. Click the Command Line property and enter:
    cd $(ProjectDir)ddlFiles\
    ooddlx %(FullPath) ..\data\fdSysName.boot
    cd $(ProjectDir)

    Note: fdSysName.boot is the name of the federated-database boot file. For more information about the ooddlx command, see Objectivity/C++ Data Definition Language. Arguments to the DDL processor must be enclosed in double-quotation marks if they specify paths that contain spaces.

  7. Click the Description property and enter:
    Building DDL File %(Filename)
        
  8. Click the Outputs property and enter:
    %(Filename)_ref.h
    %(Filename)_ddl.cpp
    %(Filename).h
  9. Click Additional Dependencies and enter the boot-file name:
    ..\data\fdSysName.boot
        
  10. In the Property Pages dialog, click OK.

Adding Generated Files

The steps in this section use your project to create a federated database and generate a set of C++ source files from your DDL files. You then add the generated files to your project.

Note: Before performing the steps in this section, you must add persistence-capable class definitions to the DDL files referenced by your project; for details about defining persistence-capable classes, see Objectivity/C++ Data Definition Language.

  1. In the Solution Explorer, right-click the project and click Build.
  2. Add the generated header and implementation files to your project:
    • In the Solution Explorer, right-click the DDL Generated Files subfilter of the project’s Persistent Classes filter and click Add > Existing Item.
    • In the Add Existing Item dialog, browse to the ddlFiles storage folder if necessary.
    • Select all of the .h and .cpp files in the ddlFiles storage folder and click Add.
  3. Add any planned source (.cpp) files for implementing the member functions of your persistence-capable classes:
    • In the Solution Explorer, right-click the Source subfilter of the Persistent Classes filter and click Add > New Item.
    • In the Add New Item dialog, select the C++ File (.cpp) template in order to add the planned source (.cpp) files.
    • In the Add New Item dialog, click Browse and select the src storage folder.
    • In the Name box, enter the name of the planned implementation file, and click Add.
  4. Add any existing source (.cpp) files for implementing the member functions of your persistence-capable classes:
    • In the Solution Explorer, right-click the Source subfilter of the Persistent Classes filter and click Add > Existing Item.
    • In the Add Existing Item dialog, browse to the src storage folder.
    • Select the implementation files in the src storage folder and click Add.
  5. Add any remaining C++ source files (or references to them) to your project as you normally would.

Setting the Includes Search Path

The steps in this section ensure that generated header files can be found during compilation.

  1. In the Solution Explorer, right-click your project and click Properties.
  2. Click Configuration Properties in the left pane, then click All Configurations in the Configuration box.
  3. If necessary, click to expand Configuration Properties, expand C/C++, and select its Precompiled Headers property page.
  4. Specify that precompiled headers are not used:
    • Visual C++ 9.0. Select Not Using Precompiled Headers in Create/Use Precompiled Headers.
    • Visual C++ 10.0. Select Not Using Precompiled Headers in Precompiled Header.
  5. Under C/C++, select the General property page.
  6. In the Additional Include Directories text box, enter the pathname to your project’s ddlFiles storage folder.
  7. In the Property Pages dialog, click OK.

Setting Link Properties

You can set Visual C++ IDE properties as shown in the following steps to trigger automatic linking of Objectivity/DB libraries; see also Automatic Linking of Objectivity/DB Libraries.

► To link dynamic using the MFC:

  • In the Solution Explorer, right-click your project and click Properties.
  • In the Configuration box of the Property Pages dialog, click All Configurations.
  • If necessary, click to expand Configuration Properties; then, select the General property page.
  • In the Project Defaults section, click the Use of MFC property and choose the following value:
    Use MFC in a Shared DLL
  • In the Property Pages dialog, click OK.

► To link dynamic without using the MFC:

  • In the Solution Explorer, right-click your project and click Properties.
  • In the Property Pages dialog, click All Configurations in the Configurations list.
  • If necessary, click to expand Configuration Properties, then expand C/C++ and select the Code Generation property page.
  • Click the Runtime Library property and choose the following value:
    Multi-threaded DLL (/MD)
  • In the Property Pages dialog, click OK.

Building and Executing the Application

The steps in this section automatically create a federated database, run the DDL processor, and build the application.

  1. Right-click your project and click Rebuild.
  2. Click Debug > Start Without Debugging.

Debugging an Application

While debugging an Objectivity/C++ application, you can:

In either case, you must first prepare your application for debugging, as described in the following subsection. The remaining subsections describe how to view persistent objects from the Visual C++ debugger.

Preparing to Debug an Application

  1. In the Solution Explorer, right-click your project and click Properties.
  2. If necessary, click Configuration Properties in the left pane.
  3. Click Debug in the Configuration box and select the appropriate Windows Platform in the Platform box.
  4. Expand C/C++ in the left pane and click the General property page.
  5. Click the Debug Information Format property and choose the following value:
    Program Database (/Zi)
  6. Expand Linker in the left pane and click Debugging.
  7. Click the Generate Debug Info property and choose the following value:
    Yes (/DEBUG)
  8. In the Property Pages dialog, click OK.
  9. Link your application to the debug-compatible Objectivity/DB import library; see Automatic Linking of Objectivity/DB Libraries.

Viewing Object Reference Variables

While using the Visual C++ IDE debugger, you can view the value of an object from an object-reference variable. To do this, you use the debugger to get the object’s database address, represented by its object identifier (OID), and then, after the transaction is complete, use oodump or oodebug to view the object’s contents.

Example

Assume your application declares an object-reference variable oopvar to a persistent object. To view this variable:

  1. Select oopvar and then use the Visual C++ QuickWatch dialog to display the following:
    -oopvar = {…}
        -ooObj_ooRef = {…}
    	-ooIdBase = {…}
    		_DB = 3
     		_OC = 2
    		_page = 2
    		_slot = 61

    This represents the OID 3-2-2-61, the federated database address of the persistent object pointed to by oopvar.

  2. When the transaction has completed, view the object contents using oodump:
    C:\> oodump -id 3-2-2-61 -r one infoNet

Viewing Handle Variables

While using the Visual C++ debugger, you can view the contents of a persistent object from a handle that references it. To do this, you use the ooprint convenience function. See "Debugging a Federated Database" in Objectivity/DB Administration.

Using Memory-Checking Software

Several third-party tools and libraries track an application’s use of memory and report memory leaks. Unfortunately, the algorithm used by the majority of these tools and libraries, including the Visual C++ debug runtime library, considers any memory not deallocated at process exit to be a leak, which is incorrect. Many programs rely on process exit to free allocated memory and return it to the operating system. A true leak is a block of allocated memory that no longer has a program reference to it (the block has been lost).

Objectivity/DB allocates and keeps track of memory during the lifetime of the process, and uses the process exit to free this memory. Objectivity/DB has been fully tested with sophisticated memory diagnostic tools and found to be leak free. However, some tools will report the memory allocated by Objectivity/DB as a leak.

 

Date: 
Monday, August 20, 2012
Product: 
Objectivity/DB
Version: 
11.0