Ftcl(n) 1.0 "ftcl"

NAME

Ftcl - Calling Tcl from Fortran and vice versa

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    INITIALISATION
    OVERVIEW OF ROUTINES
    EXTENSIONS AND PACKAGES
    DEPLOYMENT
    COPYRIGHT

SYNOPSIS

use ftcl

call ftcl_get( varname, value )

call ftcl_get_arg( iarg, value )

call ftcl_get_array( varname, values )

call ftcl_main_loop

call ftcl_make_command( procedure, cmdname )

call ftcl_provide_package( pkgname, version, error )

call ftcl_put( varname, value )

call ftcl_put_array( varname, values )

call ftcl_script( script )

call ftcl_set_result( value )

call ftcl_start( filename )

The Ftcl library offers an easy-to-use set of subroutines and functions, callable from Fortran to run Tcl commands within a Fortran program or to create an extension in Fortran useable by Tcl programs.

This manual page describes the use of these routines.

INITIALISATION

The library can be used in two ways:

Interacting with Tcl from within a Fortran program
Creating an extension (package of functions, commands and so on) to Tcl, written in Fortran

In the first case, you will need to call the routine ftcl_start to create a Tcl interpreter and initialise it. During this initialisation phase, the usual start-up sequence is run, which means the Tcl routines will look for a useable file "init.tcl" and a script library.

In the second case, you need to provide a routine called package_init that takes care of registering the commands this package provides and registering the name of the package. Tcl will be already running in this case.

New Tcl commands are registered via the routine ftcl_make_command in each case.

OVERVIEW OF ROUTINES

The Ftcl library contains the following functions and subroutines:

use ftcl

The Ftcl library is to be accessed via the Ftcl module. If you are using FORTRAN 77, then you will have to use the specific routines.

call ftcl_get( varname, value )

Get the value of the Tcl variable whose name is stored in varname.

character(len=*) varname: Name of the Tcl variable to get.
integer/real/double precision/logical/character(len=*) value: Variable that will get the value, cast to whatever type the variable is.

call ftcl_get_arg( iarg, value )

Get the value of the iarg'th argument. Used in Fortran-based command routines (i.e. the ones registered via ftcl_make_command).

integer/real/double precision/logical/character(len=*) value: Variable that will get the value of the argument, cast to whatever type the variable is.

call ftcl_get_array( varname, values )

Get the values of the Tcl array whose name is stored in varname.

character(len=*) varname: Name of the Tcl variable to get.
integer/real/double precision/logical/character(len=*), dimension(:) value: One-dimensional Fortran array that will get the values, cast to whatever type the Fortran array is. Note: The index into the Tcl array is assumed to be an ordinary number. The dimension on the Fortran side determines which elements are filled.

call ftcl_main_loop

Enter the Tcl event loop. Useful when creating GUIs. It will not return.

call ftcl_make_command( procedure, cmdname )

subroutine procedure

The Fortran routine in question. The interface is this:

subroutine procedure( cmdname, noargs, ierror ) character(len=*) :: cmdname integer :: noargs integer :: ierror end subroutine procedure

where:

cmdname is the name of the command that was used to call the routine
noargs is the number of arguments that was given
ierror can be used to indicate success or an error (0 means success)

integer/real/double precision/logical/character(len=*) value

Variable that will get the value, cast to whatever type the variable is.

call ftcl_provide_package( pkgname, version, error )

character(len=*) pkgname: Name of the package
character(len=*) version: A version string like "1.0" or "2.2.1"
integer error: Variable that indicates whether the package was successfully registered (0) or not (1).

call ftcl_put( varname, value )

Transfer the value to the Tcl variable whose name is stored in varname.

character(len=*) varname: Name of the Tcl variable to set.
integer/real/double precision/logical/character(len=*) value: Variable that will get the value, cast to whatever type the variable is. Note: if the Tcl variable is a (Tcl) array, then this may also be a one-dimensional array. The index into the Tcl array is assumed to be an ordinary number. The dimension on the Fortran side determines which elements are filled.

call ftcl_put_array( varname, values )

Transfer the values in the one-dimensional Fortran array to the Tcl variable whose name is stored in varname. Note: The index into the Tcl array will be an ordinary number. The dimension on the Fortran side determines which elements are filled.

character(len=*) varname: Name of the Tcl variable to set.
integer/real/double precision/logical/character(len=*), dimension(:) value: Variable that will get the value, cast to whatever type the variable is. Note: The index into the Tcl array will be an ordinary number. The dimension on the Fortran side determines which elements are filled.

call ftcl_script( script )

Run the script contained in the variable "script".

character(len=*) script: String containing the Tcl script to be run.

call ftcl_set_result( value )

Set the result of the command - used within command routines.

integer/real/double precision/logical/character(len=*) value: The value to be set as the result of the command. This is the value that Tcl returns.

call ftcl_start( filename )

Start-up routine for Ftcl. The filename argument should ideally point to the executable, so that the init.tcl file can be found.

character(len=*) filename: Full name of the executable or another string that enables Tcl to find the file init.tcl and the script library. (See section on deployment)

EXTENSIONS AND PACKAGES

Tcl itself provides a concise mechanism to load shared libraries or DLLs (the terminology depends on the operating system, we will use "DLL" to mean either). This allows you to extend any Tcl shell (tclsh, wish or a custom interpreter) with your own commands. Ftcl makes it possible to create such extensions in Fortran:

You should write a Fortran routine with the fixed name package_init. Since the routine must be callable from C, it can not reside in a module. This routine has the task of initialising the package:

The routine takes one argument, an integer that on return indicates whether everything was okay or whether there was an error. Here is a sketch:

subroutine package_init( error ) use mypkg integer :: error call ftcl_provide_package( "mypkg", "1.0", error ) if ( error .ne. 0 ) return call ftcl_make_command( ... ) ... end sobroutine package_init

Register one or more commands (via ftcl_make_command)
Do whatever is required for the package to become properly initialised
Register the package by name and version (via ftcl_provide_package)

Registering the package properly means that Tcl's package mechanism knows about it. It will not attempt to load the DLL again on the next "package require" command.
You need to write a package index file, called pkgIndex.tcl, that loads the DLL. This takes the following form:
package ifneeded Mypkg version [list load [file join $dir mypkg.dll Ftclpkg]]
For your convenience, this can be done via the script mkpackage.tcl in the tools directory. There are three arguments, in the given order:
- The name of the package (in the example: Mypkg). This name is case-sensitive
- The version, a string like "1.0" or "2.2.1"
- The name of the actual DLL (without the extension). This name is case-sensitive on some operating systems. The proper extension is added by the script.
The reason that the argument "Ftclpkg" appears, is that this argument is used by Tcl to construct the name of the initialisation routine for the package. By keeping that name fixed we can avoid any C programming, however simple.

All that is needed now is to build the DLL with the proper compile and link commands. The section DEPLOYMENT has more to say about possible issues with runtime libraries, so please consult that as well.