If you are creating the tree as part of a DST production program, you will want to output the tree to disk when it is complete. This is done using an F_Node member function, outputSubtree(). outputSubtree() When you call outputSubtree() for a node, it outputs the node to disk, then all of its children and all of its children's children, etc. (not exactly in that order - it uses recursion to output each subtree). Usually you will call outputSubtree() for the top node in a tree so the entire tree is output; but if for some perverse reason you want to write to disk just part of a tree, you may call it for some node other than the top. outputSubtree() takes one argument, which is the file to which the tree will be written. We use the type iostream for the file; iostream is a class defined in the GNU libg++ class library and most other C++ class libraries. The file must have been previously opened.
outputSubtree() will write a binary output file; i.e. a 32-bit integer will be written to disk as just 32 bits, not as a series of ASCII characters which give the decimal value of the integer. The data format is an extension of the XDR standard, and the binary files are instantly transportable between hardware using different numeric formats (such as DEC and IBM) without translation.
There is an internal implementation detail which most users will not need to understand, but is an interesting highlight of FARFALLA. Part of the philosophy of Object-Oriented Programming is to let class objects take care of themselves (with member functions manipulating data members) as much as possible. Following this philosophy, outputSubtree() actually asks each node to write itself to disk. Later, when the data is to be read in, the FARFALLA input routine first reads the F_NodeType of the node. Then it creates a node of that type, and asks it to read its own data in from disk. This is the reason FARFALLA data files can contain complex data structures without a lot of overhead words. (In fact, other than the four-character node type variable, FARFALLA writes to disk just 4 to 6 bytes of overhead data for every node it outputs.)
Finally, after you are finished with a tree you should delete it so that the memory it uses will be available to FARFALLA to create future trees. If you do not delete the tree, when you call F_createTree() for the next event, it will create the new tree in a new part of memory. If you continue this throughout an entire MACRO run, you will at best waste a lot of memory and at worst crash your program. You delete a tree by calling the deleteSubtree() deleteSubtree() member function of the top node. deleteSubtree() deletes its node, and all children, grandchildren, etc. of the node. Note that it is possible to call the deleteSubtree() member of a node that is not the top node of a tree; this removes that node and all its children, etc., from the tree but the rest of the tree remains intact. This is known as pruning the tree.
The following code fragment illustrates the use of outputSubtree() and deleteSubtree(). It writes a simple 2-node tree to disk and deletes the tree from memory. Here we are using the more specialized fstream class as the argument to outputSubtree(). This is legal because an fstream is just a specialized instance of an iostream; in C++ we say fstream inherits from iostream.
fstream locfile; // declare an fstream variable called locfile
locfile.open("locfile.far",ios::out); // open file for output; the name of
// the output file is "locfile.far".
eventNode *evPtr;
erpNode *erpPtr;
F_createTree(evPtr);
evPtr->run = 2122;
F_addChild(evPtr,erpPtr);
erpPtr->boxnum = 1;
evPtr->outputSubtree(locfile); // output the tree to disk
evPtr->deleteSubtree(); // delete the tree from memory