Frequently Asked Questions

1 - Algorithms - what algorithms are available in DOL?
2 - Classes in DOL - what classes are available?
3 - Classes in PPF - what classes are available?
4 - Classes in PTL - what classes are available?
5 - Compile errors when using DOL too many errors
6 - Compile errors when using DOL unable to resolve them
7 - Depth-first traversal of trees - is it available in DOL?
8 - Debugger - may I use regular debugger when programming with your libraries
9 - DLL or Shared Object libraries - can they be used?
10 - DOL, PTL, PPF - which library is best for my application?
11 - Installing the free software - how do I do that?
12 - Intrusive data structures - why are they good?
13 - Labelled attributes - are they available in DOL?
14 - Mixing DOL and other class libraries (such as STL, tools.h++, or LEDA)
15 - Mixing DOL and PPF in the same program - can it be done?
16 - Mixing persistent and non-persistent objects in PPF, can it be done?
17 - Multi-threading - is it supported?
18 - Persistence, adding it to a project coded with another class library
19 - PersistPtr<>, PersistString - how to use them
20 - Run-time errors in PPF - what to do?
21 - Saving data in DOL - what method should I use?
22 - Saving data in PPF - what is the algorithm?
23 - Saving data in sections, possibly to different files - Can it be done in DOL?
24 - Sorted Collection - is it available in DOL?
25 - Sorting - is sorting of linked lists in DOL efficient?
26 - SQL - does DOL or PPF support it?
27 - Templates - may I use templates when programming with DOL, PTL, PPF?
28 - Transactions - does DOL and PPF support transactional model?
29 - WinNT - why the free DOL for Windows does not run under WinNT?
30 - ZZ_EXT_.. statement - does every class need it?
31 - zzmaster cannot be accessed - what does this error message mean?

 If you get error messages which you are unable to clear, please check this:

- If you have file environ.h in your working directory, remove it. It is safer to depend on the default, which is orgc/lib/environ.h

- You should have #define ZZmain in one of your *.cpp files, but in one file only.

- You should have #include "zzincl.h" in all your files, and #include "zzfunc.c" in one of your source files, or you must compile zzfunc.c separately. Note that the call zzprep myFile file.h zzmaster file.c creates files file.h and file.c. The default names are zzincl.h, and zzfunc.c, zzmaster is always used. Therefore zzprep myfile has the same effect as zzprep myfile zzincl.h zzmaster zzfunc.c

- Above, file myFile must be a concatenation of all your header files, including the file where you have the definition of all relations (ZZ_HYPER... statements).

- Look at the regression script in the orgc/test directory, and see that you link to the correct library from the orgc/lib directory.

- NEVER attempt to debug and modify DOL. Most likely you are not using the library in the correct way. Send email to info@codefarms.com if you are stuck, we will help you.

DOL trees provide iterators which traverse children of the given node. With 
  these iterators, other traversals are easy to arrange. For example:

class Node {
ZZ_EXT_Node
public:
void depthFirst();
};
ZZ_HYPER_SINGLE_TREE(myTree,Node);

void Node::depthFirst(){
Node *node;
myTree_iterator it(this);
ITERATE(it,node){
// access or print 'node' here
depthFirst(node);
}
}

For PPF and PTL - yes, with no restrictions.

For DOL, yes, but do not attempt to traverse or debug DOL code. This code is solid and tested by regression tests and years of use. It is our responsibility to fix it if you can prove there is an error in it.

Note that, under ZZ_HYPER_UTILITIES(util), DOL provides an unusual, very useful tool. If you place a call to util.debug() anywhere in your code, when your reach that point the program will switch to an interactive mode, in which you can traverse the entire data structure, pointer by pointer, and examine individal objects, their links and attributes.

For more details, see Chapl.14 in the DOL User Guide.

The following algorithm will help you to make the decision. The most critical 
  question is whether you need persistence (storage of data and relations to disk). 
  We often often contacted by customers who thought that they will not need persistent 
  data, but now they deserately need it. 

if(persistence required){
if(moving data among different platforms) use DOL;
if(shema migration or version control needed) use DOL;
if(data fit the virtual memory, storing and restoring the entire data){
use DOL;
}

if(mixed case of primary storage: some data in memory, some on disk){
// use the Pager class for the disk-stored data
use DOL;
}

// primary data storage on disk, paging data to memory on demand
if(simple data structures){
// code the data structure yourself, or use existing library
// but replace all pointers by PersistPtr
use PPF;
}
else {
if(data fits virtual memory without excessive paging){
// forget about PPF, it would be too much work
use DOL;
}
else {
// you have no choice, apply PPF to your complex data structure
use PPF;
}
}
}
else { // no persistence
if(design patterns are used) use PTL;
if(complex data structures) use DOL;
switch(what do you prefer){
case (no code generator): use PTL; break;
case (clarity, ease of coding): use DOL; break;
default: use DOL; break;
}
}

 Just unzip the file - it will create a subdirectory tree with all the files 
  in it. No compilation or installation is required for the binaries of DOL and

  PPF, nor for the source of PTL.

Example: Installing DOL for Win98/VC++ after downloading file bindol.zip
pkunzip -d bindol.zip
... creates subdirectory 'orgc'

Example: Installing PPF for Solaris/g++ after downloading file gnuppf.zip
unzip -D -L gnuppf.zip
... creates subdirectory 'ppf'

There is a better solution: DOL includes a special class called PAGER which, for selected classes or strings, provides a similar service as PPF does for all classes. Actually, PPF is just a smart pointer hiding the PAGER class from
DOL.

Typical application where this may be used is an abstract service system, which allows readers to search for books and other publicatins. In edition to an in-memory data structure for fast searches, the system keeps a large volume of text (e.g. abstracts) on disk, using PAGER.

Yes, it can. For example:

class A { // non-persistent object
.... anything here as usual, but PersistClass(A) must not be used.
};

class B {
PersistClass(TreeIndex); // persistent class
A *aPtr; // pointer to non-persistent information
...
};

The use of PersistPtr<B> in your program automatically pages B objects in and out of disk, with aPtr copied as a raw number. This means that, within the same run, the reference remains valid.

We frequently encounter this situation. People code with STL or tools.h++, and then they want to make the data persistent. This is not a simple addition (why didn't they think about it in the first place?). You have three options:

a. Replace your collections, arrays, or other data structures by classes from DOL. This is easy if your data structures and their access are not spread all over the code. The problem is that DOL uses intrusive data, therefore interfaces are different. The replacement must be done carefully, and with a good knowledge of how the two libraries work.

b. From your current data structure library, extract the classes needed for your application, and replace all pointer references by the persistent pointers from PPF. This is practical only if your data structure is not complex.

c. Re-code the project with DOL. This may sound ridiculous, but it is usually the safest and fastest solution. Every redesign improves software, and you will see how DOL will improve the clarity of the code, and the run-time performance.

If you are not used to working with smart pointers, note that most of the time they behave as pointers, but they still are objects even though operator '->' is overloaded. In particular:

class A;

A *aPtr;

PersistPtr<A> ap; // do not use '*'

PersistString ps;

...

aPtr=NULL;

ap=NULL; // is the same



if(aPtr).. // testing whether it is NULL

if(ap).. // compiles, but does not work !!

if(ap!=NULL).. // should be used instead

if(ap==NULL).. // also works fine

delete aPtr; // deletes the object
delete ap; // do NOT use, deletes smart pointer, not the object
ap.delObj(); // use instead
delete as; // do NOT use, deletes smart pointer, not the string
as.delString(); // use for deleting the string itself

It does not matter much which method you start coding. It is easy to switch from one method to another. Also, a program may use different methods during the same run.

The ASCII and binary mode are based on serialization, but you don't have to code serialization functions. They are generated automatically. The ASCII mode is less efficient (slower, needs more disk space) but even if your classes and their relations change, the old data files are still usable. Also, data stored in this mode can move between different platforms.

The binary mode is more efficient, but less flexible. The classes and relations must not change, and the data can be restored only on the same platform. Coding with the binary saving to disk is easier, because it does not need ZZ_FORMAT statements, one for each class, required for the ASCII mode.

Memory blasting allocates objects from memory pages, and then stores entire pages as a fast binary write-operation. It is much faster than the other two modes. Coding with memory blasting requires more experience though, and debugging is more difficult.

When we develop a new program, we usually code as if saving the data in the binary mode, and only later switch to the ASCII mode or memory blasting later, when the program is safely running.

Each class stores all its objects in a separate file, one file is kept for all strings. For example, objects of class myClass are stored in file myClass.ppf, and all strings always in file string.ppf. As you can imagine, this gets a bit more complicated whenmember objects or inheritance are used. Each class manages its file, including a list of free objects and allocation and deallocation of arrays.

You control the paging of the data individually for each class by calling

myClass::startPager(pageSz,numPagesInMemory,totalSpace);

where totalSpace is a rough upper bound (not a critical value) on the possible total space the program may need for myClass.

This allows you, for some classes, to keep only a few objects in memory at any given time, while objects of another class may all reside in memory until the end of the run.

When you call myClass::closePager(), all pages of myClass move to disk, and file myClass.ppf is closed.

This can be done, but it involves the advanced use of the library. If you are starting with DOL, just remember that it is possible. For the details, see the DOL User Guide, Chap.13.3, advanced features around the paragraph with the title "Multiple Files".

The idea is to disconnect pointers in some narrow bottleneck of the data-structure, ask the DOL saving utility to save each section to a different file, and reconnect the two parts together.

Note that in PPF, each class saves its objects to a different file, so this question does not arise.