22.5.

22.5.1. Using the logbook API from C++

Here's the C++ implementation of our toy program, kvexample.cpp:

#include <LogBook.h>             
#include <iostream>
#include <stdlib.h>
#include <stdexcept>

int main(int argc, char** argv)
{
  if (argc  != 3 ) {                 
    std::cerr << "kvexmple logbookdatabase key\n";
    exit(EXIT_FAILURE);
  }
  try {                              
    const char* key = argv[2];
    LogBook book(argv[1]);            
    if (book.kvExists(key)) {         
      std::cout << key << " : "
                <<  book.kvGet(key) 
                << std::endl;
    } else {
      std::cerr << key << " does not exist\n";
      exit (EXIT_FAILURE);
    }
  } catch (std::exception& e) {    
    std::cerr << e.what() << std::endl;
    exit(EXIT_FAILURE);
  }
  exit(EXIT_SUCCESS);
}

            

This program accepts two command line parameters. The first is a logbook database file. The concept of a selected logbook is only maintained by the lg_xxxx utilties and Tcl administrative API. As an exercise for the reader, check for the file ~/.nscl-logbook-current and read the logbook database filename from there.

Let's break this down step by step:

To compile this toy program we need to include compiler options to find the LogBook.h header, locate and include the API libraries both at link-time and, since they are shared libraries, at run-time:

g++ -o kvexample -I$DAQINC -L$DAQLIB -lLogbook kvexample.cpp -Wl,-rpath=$DAQLIB
            

This produces an executable named kvexample which can be run directly. The -I$DAQINC adds the NSCLDAQ header directory to the include file search path. The -L$DAQLIB option adds the NSCLDAQ library directory to the link time library search path. -lLogbook specifies that we need the logbook C++ API and the -Wl,-rpath=$DAQLIB part of this command adds the DAQ library directory to the search path for shared libraries at run time.

22.5.2. Using the logbook API from Tcl

There are two levels of Tcl API. This section will demonstate both the low level Tcl bindings and discuss why care is when using them. We'll then write the program to use the so-called administrative level bindings which hide a lot of the complexity of the low-level bindings at the cost of some performance and a more restrictive interface.

#!/bin/sh
# -*- tcl -*-
# The next line is executed by /bin/sh, but not tcl \  
exec tclsh "$0" ${1+"$@"}


##
#  kvexample for low level bindings.
#
lappend auto_path [file join $::env(DAQROOT) TclLibs]    
package require logbook                                  

if {[llength $argv] ne 2} {
    puts stderr "kvexamplelow.tcl filename key"         
    exit -1
}

set book [lindex $argv 0]
set key  [lindex $argv 1]

if {[catch {logbook::logbook open $book} instance]} {    
    puts stderr "Could not open logbook $book : $instance"
    exit -1
}

if {[$instance kvExists $key]} {                        
    puts "$key : [$instance kvGet $key]"                
    set status 0
} else {
    puts stderr "No such key: $key in $book"
    set status -1
}

$instance destroy                                      
exit $status

               

#!/bin/sh
# -*- tcl -*-
# The next line is executed by /bin/sh, but not tcl \
exec tclsh "$0" ${1+"$@"}

lappend auto_path [file join $::env(DAQROOT) TclLibs   
    
package require logbookadmin

if {[llength $argv] != 1} {
    puts stderr "kvexamplehi.tcl  key"                
    exit -1
}

set key [lindex $argv 0]
if {[kvExists $key]} {                               
    puts "$key : [kvGet $key]"                       
} else {
    puts stderr "There is no key named $key"
    exit -1
}
exit 0

               

22.5.3. Using the logbook API from Python

The Python API provides an object oriented Python interface to the Logbook API. Unlike the Tcl low level API, Python's object reference counting and garbage collection can, and are, used to do the storage management the Tcl low level API burdens you with.

Here is the equivalent program in python. Since we can't access the current logbook directly (an excersise for the reader is to pull the logbook filename from ~/.nscl-logbook-current) rather than from the command line.

Note that the API is supported for Python 3 not Python 2. You must use that interpreter when running your scripts.

import sys                              
from  LogBook import LogBook            

if len(sys.argv) != 3 :
    print("kvexample.py logbook key")  
    exit()

bookfile = sys.argv[1]                 
key      = sys.argv[2]                 

book = LogBook.LogBook(bookfile)       
if book.kv_exists(key) :               
    print(key + " : " + book.kv_get(key)) 
else :
    print(key + " does not exist")

exit()

            

Running this script takes a bit of effort. Here's a sample command line that prints the name of the experiment from the KV store:

               
PYTHONPATH=$DAQROOT/pythonLibs/nscldaq python3 kvexample.py junk.log experiment

            

• The definition of PYTHONPATH on the command line tells python to look for importable modules in the DAQ python module directory tree.

• Note the explicit invocation of python3. Our logbook modules for Python are only available for Python version 3. At the time I'm writing this many Linux distributions install both but make Python version 2 the interpreter invoked by the python command.