Mainframe: A Fortran Interface to Hanna

Mainframe consists of two source files codes that provide an F77 interface to Hanna, so that you can write your usercode in Fortran instead of C. The interface is seamless: instead of writing your user functions as C modules, you write them as Fortran integer functions ... the argument lists and variable types are identical to those of the C version.

Codes

• Download: mainframe.tar.gz and unpack in a separate subdirectory.
• You should see the following files:
  • Just like the dummy_*.c files in the main hanna library, mainframe_dummy.F contains empty verions of all the user functions, in case you choose not to provide your own versions of all of them. Note that mainframe_dummy.F thus provides an empty template for your own user code.
  • An example configure and Makefile.in for you to use when creating your own hanna program. The Makefile assumes that your user functions will be contained in a file called frame.F, but of course you can change this to whatever you like.

Usage

This section describes the few differences between regular hanna, and the F77 implementation provided by mainframe.

• mainframe.c provides the main program for you: it calls ha_main, and so you do not have to do it yourself. All you have to write are integer functions, for each of the user functions you wish to supply. mainframe also initializes HBOOK, so you don't have to do that either.

• Interfaces to all of the hanna user functions are provided:

  	
  	user_init, user_end, user_runinit, user_runend, user_event,
  	user_slow, user_burstinit, user_burstend
  

• Interfaces are not yet provided for the more technical Hannalib functions, such as ha_debuginit. The function ha_addarg is implemented, but via the special routines described in the next section. If you do wish to use some of the other Hannalib functions, it is not difficult: simply add a cfortran declaration for the routine (of the type FCALLSC...) to mainframe.c. There are numerous examples of such declarations in mainframe.c, and you can also have a look at the documentation for the cfortran package.

To repeat from above, mainframe_dummy.F provides an empty template for your user code. In particular, it sets all the return codes to 0 = 'success' ... hanna does pay attention to the return codes from your user functions.

The only major difference between mainframe and hanna is ...

User-defined command line arguments

Hanna provides the very nice ha_addarg routine that allows you to define new command-line arguments (or 'switches') for your usercode. This is a very convenient way of passing information to your program at runtime!

Mainframe allows you to do the same. However the syntax is a bit different from regular hanna. If you wish to declare your own command-line arguments (CLA):

• You must write an additional user function, called user_args. It is just an integer function like all the other user functions, and takes no arguments. user_args is called before any other user function, including user_init.

• Within user_args, decalare your custom switches via calls to the subroutine addarg. Its syntax is very similar to the ha_addarg routine:

  subroutine addarg( name, valname, help, default )

  Add one entry to the list of command line switches.
  Note: all of the arguments to addarg are character string variables. They may be single quoted strings given directly in the argument list, or they may be CHARACTER variables of any length.
  Meaning of the arguments:

  name	Name of this switch, by convention this should begin with a minus sign ('-')
  valname	If the switch requires an additional value, the name of this value (used only by the --help printout) is specified by valname. If the switch is boolean, it does not require an additional value and this argument should be an empty string ('').
  help	Short help string that will be printed if --help (or an invalid CLA) is supplied to your hanna program.
  default	Default value for the switch. If it is a boolean switch, this argument is ignored. Note that no matter what type of value is expected, this default should be supplied in character string format.

• Unlike ha_addarg, the F77 subroutine addarg does not bind any variables to your new command-line switches -- you must explicity retrieve the values with some extra function calls. These retrievals are normally performed in the user function user_init, but you can do it (as often as you like) in any user function except user_args. Here are the declarations you have to supply whenever you want to call these retrieval functions:

  
  	integer       getarg_bool ( name )
  	integer       getarg_int  ( name )
  	real          getarg_real ( name )
  	character*80  getarg_char ( name )
  

  These functions retrieve the value of command-line argument name. The retrieval function you select depends on the expected type of data supplied to each user-defined CLA. As described in the C documentation, boolean switches return an integer value, corresponding to the number of times the switch was specified on the command line.

Archive

For posterity, here is the old page describing F77 interfacing. This older version does not include a Fortran implementation of user-defined command line arguments.