Your First C++ Configuration

The keyval2cc utility is used to translate a <keyval> document (representing a configuration) into the necessary C++ code for loading and using the represented configuration. In addition, it will provide useful parts for building documentation as well. The beauty of this is that you, as the developer, should only have to maintain the single <keyval> file as these other "parts" can automatically be generated as needed.

The following sections will take you through the steps of creating a new ldfilt command. We create this utility in the following steps:

We're going to be lazy and use the newapaapp command to get started. The following commands will stub in a template file, build the initial template code, and run it:

[pkb@salsa pkb]$ newapaapp -m ldfilt -n ldfilt -c true -v true -d \
> "Filters Ld objects based upon user configuration" 
 
*** Generating Template Files ***
 
 
*** Checking Files in /home/pkb/gai/cvs/apa/src/ldfilt ***
 
created: ldfilt.hh
created: ldfilt.cc
created: ldfilt.man.m4
created: makefile
created: ldfilt_config.xml
 
Success! Build with:
 
  (cd /home/pkb/gai/cvs/apa/src/ldfilt; make -f makefile ldfilt)
[pkb@salsa pkb]$ (cd /home/pkb/gai/cvs/apa/src/ldfilt; make -f makefile ldfilt)

... lots of cryptic output as the initial application is built ...

[pkb@salsa pkb]$ ldfilt -h
 
Usage:
 
   ldfilt [-verbosity LEVEL] [-cfg FNAME] [-cfg_loaded] [-cfg_defaults]
      [-tag TAG] [-cdb_host HOST] [-cdb_db DATABASE] [-msg_ipc IPC]
      [-msg_ipc_list] [-tape_ipc IPC] [-tape_ipc_list] [-sdata3d_ipc IPC]
      [-sdata3d_ipc_list] [-fg] [-loglevel LEVEL] [-logmode MODE]
      [-logas FACILITY] [-h] [-help] [-man] [-version] [-debug]
      [-check_locks [FILE]]

[pkb@salsa pkb]$ ldfilt
check setup at line 189 in ldfilt.cc
ldfilt is doing nothing for 5 seconds!
ldfilt is doing nothing for 5 seconds!
ldfilt is doing nothing for 5 seconds!Control-C

[[pkb@salsa pkb]$ 

OK then. We really don't have a clue as to what we've done to deserve this, but somehow or other, we've already got a pretty good start at the new ldfilt utility. Sure, the new ldfilt doesn't do much yet, but we are well on our way.

We are going to replace the ldfilt_config.xml template file which the newapaapp command created for us with the following:

Before we try to make use of the new configuration options, lets make sure things still build with the following:

[pkb@salsa pkb]$ cd $APAHOME/src/ldfilt
[pkb@salsa ldfilt]$ make all

... lots of cryptic output ...

[pkb@salsa ldfilt]$ ldfilt -h
 
Usage:
 
   ldfilt [-verbosity LEVEL] [-cfg FNAME] [-cfg_loaded] [-cfg_defaults]
      [-tag TAG] [-cdb_host HOST] [-cdb_db DATABASE] [-msg_ipc IPC]
      [-msg_ipc_list] [-tape_ipc IPC] [-tape_ipc_list] [-sdata3d_ipc IPC]
      [-sdata3d_ipc_list] [-fg] [-loglevel LEVEL] [-logmode MODE]
      [-logas FACILITY] [-h] [-help] [-man] [-version] [-debug]
      [-check_locks [FILE]]

If we're lucky, everything will build and run the same as it did before. If we look at the man page, we'll notice that the configuration section reflects the changes we made in ldfilt_config.xml.

Also due to the changes in ldfilt_config.xml, there are new member functions available in ldfile_config.hh and ldfilt_config.cc. We will make use of these new member functions as we add the source code for our custom nlib::Filter implementation to the ldfilter.cc source file. The following shows the code added:

Again, we will be paranoid, and make certain things build as they should:

[pkb@salsa ldfilt]$ make all

... lots of cryptic output ...

[pkb@salsa ldfilt]$ ldfilt -h
 
Usage:
 
   ldfilt [-verbosity LEVEL] [-cfg FNAME] [-cfg_loaded] [-cfg_defaults]
      [-tag TAG] [-cdb_host HOST] [-cdb_db DATABASE] [-msg_ipc IPC]
      [-msg_ipc_list] [-tape_ipc IPC] [-tape_ipc_list] [-sdata3d_ipc IPC]
      [-sdata3d_ipc_list] [-fg] [-loglevel LEVEL] [-logmode MODE]
      [-logas FACILITY] [-h] [-help] [-man] [-version] [-debug]
      [-check_locks [FILE]]
[pkb@salsa ldfilt]$ 

Our work on ldfilt has been progressing nicely. We'll now replace (or drastically update) the main() method of the ldfilt class to the following:

Once again, we'll compile and run (feeding in a set of 0 Ld objects) with the following:

[pkb@salsa ldfilt]$ make all

... lots of cryptic output ...

[pkb@salsa ldfilt]$ ldfilt < /dev/null
check setup at line 120 in ldfilt.cc
[pkb@salsa ldfilt]$ 

We don't really want the output shown. So, we'll take a look at line 120 in ldfilt.cc. It turns out, that this diagnostic output was inserted by the newapaapp command when we first created our ldfilt application. It indicates the point in the file where we can do additional sanity checks upon values read from the configuration file. As we like living on the edge, we aren't going to worry about sissy sanity checks and delete the lines of code which produced this warning message.

We're just about done. We'll recompile, locate a test data file (some real Ld objects), make sure negative data comes through the filter, create a configuration that only allows positive Ld objects through, and try it out. This is shown below. NOTE: A sane person would simply edit the configuration file instead of using the sed hack shown below.

[pkb@salsa ldfilt]$ make all

... lots of cryptic output ...

[pkb@salsa ldfilt]$ ldfilt < /tmp/ld.raw | ldcat -printer dff
2004-03-12 21:36:32.999997661  32.9932 -100.0014     0   -75.0  0   0.7  0.3  2.3  20.9    0.2  4 G
[pkb@salsa ldfilt]$ sed -e 's/-1500.0/0.0/g' < $APAHOME/src/package/ldfilt.cfg \
> > $APAHOME/etc/positive.cfg
[pkb@salsa ldfilt]$ ldfilt -cfg positive.cfg < /tmp/ld.raw | ldcat -printer dff
[pkb@salsa ldfilt]$ 

And there you have it. We've got a working start to our new ldfilt application. At this point, we'd want to clean up the man page and start adding other options to the configuration file as we work towards a final product. I'll leave that exercise to the reader as I'm growing weary of documentation.