SLAC PEP-II
BABAR
SLAC<->RAL
Babar logo
HEPIC E,S & H Databases PDG HEP preprints
Organization Detector Computing Physics Documentation
Personnel Glossary Sitemap Search Hypernews
Workbook Home Introduction Account Setup QuickTour Packages Modules Unwrap page!
Event Information Tcl Commands Editing Compile and Link Run the Job Debugging
Check this page with the
W3C Validator
(More checks...)
Parameters Tcl Files Find Data Batch Analysis ROOT Tutorial

Run the Job: How to run BaBar applications



In the previous section, you used the gmake all command to compile and link the C++ source code in your test release. Compiling and linking the code in the BetaMiniUser package produced an executable named BetaMiniApp.

In this section, you will learn how to run the BetaMiniApp executable, and BaBar applications in general. There is a brief overview of program flow, and an extensive discussion of the workdir package, from which all BaBar applications are run. And you will run your new BetaMiniApp from Example 2 and view your new momentum histogram.

The basic run command

All Babar applications must be run from the workdir directory. The basic command to run any analysis job is:

workdir> XXXApp YYY.tcl
where XXXApp is a BaBar executable, and YYY.tcl is a Tcl file. It is this Tcl file (along with other Tcl files that it sources) that tell XXXApp what to do.

Program Flow

Here is what happens when you run a BaBar executable:

  1. The application creates the Framework and an AppUserBuild object.
  2. The AppUserBuild object gives the Framework a list of modules.
  3. Tcl files (or you, acting like a Tcl file):

Tcl files and their role in setting up the analysis path are discussed in detail in the Tcl files section.

Example 2, Part 3: Running the job

Quick links:

In the previous section, you made a brand new BetaMiniApp. Now it is time to run the new executable. As in the Quicktour, you go to workdir, and issue the run command:

workdir> BetaMiniApp snippet.tcl

At this point (although you can't see it), BetaMiniApp creates a Framework and an AppUserBuild object, which loads the Framework with modules. One of these modules is your QExample module. That is why QExample must be included in BetaMiniUser's AppUserBuildBase.cc file.

After BetaMiniApp performs these two initial actions it sources snippet.tcl. snippet.tcl sets some parameters and then sources MyMiniAnalysis.tcl, which in turn sources a number of secondary tcl files that set up the analysis path. The role of Tcl files is discussed extensively in the next section.

After a while, you get a Framework prompt:

>

While the executable is running, a Framework prompt is given whenever user input is allowed or required. Then you get to act like a Tcl file. You can issue any legal Tcl command at the Framework ('>') prompt. This includes ordinary Tcl commands, and the special BaBar Tcl commands.

As before, you input some data and then tell the Framework to process events:

> mod talk KanEventInput
KanEventInput> input add /store/SP/R18/001237/200309/18.6.0b/SP_001237_013238
KanEventInput> exit
> ev beg -nev 40
> exit

When you exit the Framework you terminate the BetaMiniApp executable and are returned to your usual unix shell prompt.

Because you ran your job from workdir, the output ROOT file is placed in your workdir directory. Its name in snippet.tcl is still set to "myHistogram.root", so it will have overwritten your older myHistogram.root from the Quicktour.

You can view your new histogram in ROOT:

workdir> bbrroot
workdir> TFile f("myHistogram.root");
workdir> f.ls();
You should now see the momentum histogram that you added:
TFile**         myHistogram.root        Created for you by RooTupleManager
 TFile*         myHistogram.root        Created for you by RooTupleManager
  KEY: TH1F     h1d1;1  MC reco abs mtm difference
  KEY: TH1F     h1d2;1  Reco track momentum
  KEY: TH1F     h1d3;1  Tracks per Event
  KEY: TH1F     h1d4;1  Momentum
  KEY: TH1F     h1d5;1  TagInspector Status

This confirms that the your compile and link sucessfully incorporated your code changes into the new BetaMiniApp. Go ahead and plot your new momentum histogram:

   root[] h1d4->Draw():
It should look like this:

root histogram

Finally, Example 2 is finished. You have successfully edited BaBar code to add a histogram, recompiled and relinked your code to make a new executable, run the new executable, and viewed your new histogram. Congratulations!

The workdir package

workdir is the package used to run all BaBar applications. So it is a good idea to become very familiar with workdir and how it works, because no matter what other packages you are using, you will always need workdir. The remainder of this section is devoted to workdir.

workdir has links to all of the library and binary files it needs in both the test release and the base release. Input and output remain local to the workdir directory.

Contents of the workdir package

When the workdir package is checked out it comes with the following files:
CVS/
Directory with information about repository the workdir package was checked out from and which version of workdir was checked out
GNUmakefile
makefile for the workdir package
README
general information file
RooAlias.C
Subroutines that are loaded during ROOT initialisation
RooLogon.C
Initialisation code executed at the start of a ROOT session
kumac/
directory of useful kumac macros (for PAW)
pawlogon.kumac
Default kumac that is executed when PAW starts up in the workdir

Setup

Before starting to work from the workdir directory you must set it up by making the setup target.
workdir> gmake setup

(This target is defined in the GNUmakefile of the workdir package. So from workdir, the command is "gmake setup". From the RELEASE directory, as in the Quicktour, the command is "gmake workdir.setup".)

A main result of gmake setup is that several symbolic links are created. These links are:

PARENT
This is a link to the production release directory under BFDIST that corresponds to the base release with which the new release was created.
RELEASE
By default this is a link to the directory one level up in the tree, the release directory: ../
bin
This link points to the bin directory of the RELEASE directory: RELEASE/bin/
shlib
This link points to the shlib directory of the RELEASE directory: RELEASE/shlib/

Currently, if you do a gmake clean from within the workdir package itself, several of the soft links get deleted or reset, including the bin link which will no longer point to your own bin area - meaning that you will not be able to directly access your own executables such as BetaMiniApp which we used in the QuickTour. To remake these links correctly, you simply repeat the

gmake setup
command from your workdir directory.

Using workdir to run applications

workdir is designed to run applications. Since input and output remains local to the workdir directory, the locations of input and output files must be given with respect to the workdir directory.

When you use your test release to generate an executable like BetaMiniApp, it is stored in the bin/$BFARCH directory of your test release. Recall that gmake setup generates a link in workdir: bin->RELEASE/bin. This is the first place that workdir looks for applications. If it does not find the application there, then it will look in PARENT/bin.

In the Quicktour, this meant that when you issued the command "BetaMiniApp snippet.tcl", the system looked in RELEASE/bin/$BFARCH/ for your BetaMiniApp executable.

To run the executable you need a Tcl script as an argument. The Tcl script has the responsibility of defining the analysis path of the user's application.

For example, the BetaMiniUser package used in the Quicktour provides example tcl files for several different possible BetaMiniApp jobs:

Any one of these files can be used as an argument to BetaMiniApp.

The command to run an executable from workdir is:

  workdir> WhateverApp ../<Package>/<filename>.tcl 
The second argument locates filename.tcl with respect to workdir. There are a few other ways to do this (besides "../"). You could make use of the RELEASE pointer
  workdir> WhateverApp RELEASE/<Package>/<filename>.tcl
or you could copy the tcl file into the workdir directory (or place a symbolic link in the workdir directory without moving the existing file - see the Workbook section on Unix) and issue:
  workdir> WhateverApp <filename>.tcl
In the Quicktour, you ran the job with the command:
workdir> BetaMiniApp snippet.tcl
snippet.tcl is actually NOT one of BetaMiniUser's tcl files, but it sources (executes) MyMiniAnalysis.tcl right away after setting a few parameters. You could just as well have changed the parameters in MyMiniAnalysis.tcl itself, and issued:
workdir> BetaMiniApp ../BetaMiniUser/MyMiniAnalysis.tcl
However most people prefer to use their own personal snippet tcl files to set parameters. That way, they avoid modifying standard BaBar tcl files more than they have to. Among other things, this makes it easier to describe your analysis when you ask other BaBar people for help. Snippet tcl files are discussed in detail in the Tcl files section.

As in the Quicktour, applications often write output .root or .hbook files. The output files are put in workdir. If you want to put them in a different directory, you need to specify the name of the directory with respect to workdir. For example,

set histFileName output/myHistogram.root
in your snippet.tcl file puts the ROOT file in the directory workdir/output (which you would then of course have to create before running the job).

Care about using gmake clean in workdir

Often when compiling your work you will want to issue a "gmake clean" command to clear out libraries and binaries from a previous problem with compiling or linking. This should always be done from your release directory. However, if often happens that one accidentally issues a "gmake clean" command from the workdir directory. The main effect of this command in workdir is that is removes the symbolic link that workdir has to your /bin directory - meaning workdir can no longer 'see' any binaries you have built. This is easy to fix... whenever you accidentally do a "gmake clean" command in your workdir, just issue a
gmake setup
command from workdir to rebuild the link. (Or you can do gmake workdir.setup from your release directory.)

A warning about missing binaries

Missing binaries can catch you out in two ways:
  1. If your gmake bin command fails due to some compile-time error, the binary won't be made
  2. If you put your release in your scratch area (as in the Quicktour), and you haven't used your binary for some time (approximately a week), it will be deleted, as the scratch disk cleans out unused files
There are two ways in which a missing binary will manifest itself:
  1. The binary will simply not be found when you try to execute it
  2. A binary in the BaBar compiled code (in workdir/PARENT) will run, and none of your changes will be in it

In the second case, what happens is that the system searches for an executable in your bin/$BFARCH/ directory, and when it doesn't find one, it looks in the original analysis-41 release, finds the central, pre-compiled binary, and uses that one instead.

This problem can be very difficult to spot - the code appears to run just fine, but none of your changes are in the output files!

In either case, the way to check things is to look at output from the compile and link stages and, particularly if it is just the case that you haven't tried to run your binary for some time, check the bin directory:

ls -l ana41/bin/$BFARCH/

If this directory does not contain the binary you wanted to run, then the binary hasn't been built, or has got old and been deleted.

A good way to avoid accidentally using the wrong binary is to always run your executable with its full path name:

ana41/workdir> bin/$BFARCH/BetaMiniApp

(Note that workdir/bin is a link to the bin directory in your test release.)

Of course, running with the full path name will not prevent binaries from going missing. But this way, if there is no BetaMiniApp in bin/$BFARCH, the system will give you an error message, instead of running PARENT/bin/$BFARCH/BetaMiniApp.


Back to Workbook Front Page

Send comments to Workbook Team.