(From contributions by Claude Pruneau and Ken Wilson)
In this tutorial, you will learn to setup, build, and run a simple STAF package called ``foo.'' You will also learn how to modify and customize the modules in this test package. This section of the tutorials may be skipped by those mainly interested in running existing STAF executables for simulations and analysis. This tutorial has been verified to run successfully on irix (rsgi00), sun4os5 (sol.star.bnl.gov) and sun4os5pc (rpro00). Should you encounter problems with one machine, try another.
FOO Setup
Set the default directory to your preferred work area or for example:
cd ~``user_name''/STAF_Tutorial
Create the top level directory for the test STAF package ``foo,'' change to the foo subdirectory, copy the STAR Library standard SL97b Makefile into this directory and issue a make command to set up all package directories and Makefiles.
mkdir foo
cd foo
cp $SLM_DIR/Makefile .
make setup
Type ``ls -F'' and you should see the following subdirectories and files:
Makefile bin/ lib/ wrk/ Makefile.control doc/ solib/ Makefile.user inc/ src/
Edit the ``Makefile.control'' file and verify that the macros ASPS and PAMS are defined as follows:
ASPS := tbr ami dio dui tdm spx soc
PAMS := foo
The macro ASPS determines which ASPs are included in the link of the ``foo'' package whereas the macro PAMS determine which Physics Analysis Modules libraries are included. Here we will include only modules from the ``foo'' package. Make sure there is no ``#'' sign in front of the macro names ASPS and PAMS. Verify that the user libraries are defined as follows:
USER_LIBS := -ldsu -ldsl -lasu
Note the settings for DEBUG and SHARE. Remove the ``#'' sign in front of the MOTIF macro, such that this line reads:
MOTIF := TRUE
Note, finally that for this exercise the CERN Libraries are not linked, therefore we will not have access to a HIGZ graphics window. After making these changes be sure to save the edited Makefile.control file and quit the editor.
Next you will copy some html document files, a table idl file, two modules and their idl files, and a sample kumac file. Please execute the following sequence of file copies. Be sure to not alter any of the Makefiles in the foo directories and subdirectories.
cd doc
cp /star/u2/ray/WWW/ofl_tut/foo/doc/*.html .
cd ../inc
cp /star/u2/ray/WWW/ofl_tut/foo/inc/foo*.* .
cd ../src
cp /star/u2/ray/WWW/ofl_tut/foo/src/foo*.* .
cd ../wrk
cp /star/u2/ray/WWW/ofl_tut/foo/wrk/foo*.* .
Studying FOO
The package FOO holds two modules. There are defined in the src directory. We have defined a C module (foo_top.c) and a FORTRAN module (foo_bottom.F) to illustrate coding with these two languages. The package as supplied to you includes a single table named ``foo_par'' defined to hold foo parameters. Before going any further please examine the IDL definitions of the modules in the src directories, and compare them to the C and FORTRAN module implementations. Also have a look at the IDL definition file for the foo_par table in the /inc directory. You will be adding variables to the foo_par table later in this tutorial.
Compile the foo Package and Link STAF
First, return to the main directory level for /foo by typing ``cd ..'' . Then call the STAR Library make utility to generate the foo package configuration file by typing:
make config
Examine the file ``foo.config.'' You should see (among other things) the following lines:
make
Make will loop through all subdirectories and execute local Makefiles to create all components. A great number of comments, and streaming error messages are printed out by the make utility. In general, error type 1 are fatal whereas error type 2 are not and can be ignored. The make is completely successful if you see the banner:
##############################################################
### STAF made. ###
##############################################################
You can verify that STAF has been built by checking in the ``bin/ARCH'' subdirectory (where ARCH = irix, etc.) which should now contain the file ``fooStaf.'' Note also the files added in subdirectories /lib/ARCH and in /src.
Running FOO
To run STAF, change directory to the work area
cd wrk
You may create a soft link to the Staf executable by typing:
ln -s ../bin/irix/fooStaf fooStaf
if you are on the SGI machines. There is also a simple kumac script named ``foo.kumac.'' Start a STAF session by typing the STAF executable name:
fooStaf
Verify that the modules are loaded by typing
ami/list
Execute the initialization macro in the foo kumac script:
exec foo#init
This executes the foo_top module which defines the values of the variables in the table foo_par. List the values of the variables by typing:
tdm/table/cell/getvalue 'par[0].one'
tdm/table/cell/getvalue 'par[0].two'
Now invoke the second macro, run, with some parameter values
exec foo#run 5 6 7
This sets the variables one, two, and three to the values 5, 6 and 7, respectively, in the foo_par table. The call to foo_bottom calculates the age of the universe. After you have verified the proper execution of the modules you may end the STAF session by typing quit at the KUIP or STAF prompt.
Modifying FOO
Code modification:
Let's now modify the foo package by first changing the code so that the variable ``three'' is set equal to variables ``one+two.'' Edit the file ``foo_top'' and replace the line which reads,
foo[0].three = 3.
by the new line,
foo[0].three = foo[0].one + foo[0].two
Save the file, change directory to /foo, and rebuild STAF. Since we have made changes in the package we must do some house keeping chores. To do this type ``make clean,'' followed by ``make config'' and then finally type ``make.'' Verify that the executable ``fooStaf'' works properly by repeating the above execution steps. After verifying that the modified module is working properly you may end this STAF session.
Addition of a table:
Create a new table IDL file ``foo_fun.idl'' in the /inc subdirectory as follows:
/*
* foo_fun.idl
* Table: foo_fun
* Description: a table to hold the age of the universe...
*/
struct foo_fun {
float age;
};
Add a call to this table in the argument list of the foo_bottom.idl module as follows:
interface foo_bottom : amiModule {
STAFCV_T call
( in foo_par par
, inout foo_fun fun
);
};
Also add the ``#include ``foo_fun.idl'' '' line to foo_bottom.idl. Modify the function declaration statement in the Fortran file to be as follows:
integer function foo_bottom (par_h, par, fun_h, fun)
Modify the line
age = 15e9*par(1).one*par(1).two*par(1).three/6.
as follows so as to keep the value of the variable `age' in a table for output to other modules.
fun(1).age = 15e9*par(1).one*par(1).two*par(1).three/6.
Modify the write statement accordingly, save the modified file, and rebuild STAF. Since we have changed the data structure interfaces for the package we must again do some house keeping and make a new PKG.config file. To do this change directory to /foo, type ``make clean,'' followed by ``make config'' and then finally type ``make.'' You will have to modify the foo.kumac to define the foo_fun table and include it in calls to the foo_bottom module. To do this add/modify the following lines in the foo.kumac file:
newtable fun foo_fun 1
rowcount fun 1
ami/module/call foo_bottom par fun
Run fooStaf and examine the values computed and put in table ``fun'' by typing:
tdm/table/print fun