SYNOPSIS

fn name.type[.c] [range] [.|c|e|k|?]

DESCRIPTION

There are five types of user functions, as listed below.

Type	Kind of Function
1	Simple: calculates y for range of x you specify.
2	Parametric: x = f(t), etc., where you enter range of t.
3	Operate: x = f(x, y, ...), etc.
4	Other: function makes data (current data available).
5	Hook-up to fitting package.

The type number is the last component of the function name.

The f1 command is synonymous with fn. The commands f2 through f8 designate additional independent functions.

If you already have a function running, using a single dot as an argument returns you to the same function. Entering an explicit c in the function name automatically invokes the editor.

The range option applies to function types 1 and 2. If you don't enter the range on the command line, you will be prompted for the starting value, the finishing value and the number of intervals. If you do enter the range on the command line, you need to enter all three values. The number of generated points will be one larger than the number of intervals. If the value for the number of intervals is negative, the points will be logarithmically spaced.

Entering c as an argument will cause the current function to be compiled. Entering e as an argument will invoke the editor for the current function. Entering ? as an argument will show the current function names and their process id numbers. Entering k as an argument will kill the current function.

Standard locations for user functions are the public function directory, $CPLOTHOME/functions, and your private function directory. The latter is set by the environment variable CPLOT_FN_DIR or by using the set fn_dir command with C-PLOT. If not explicitly set, the default private function directory is $HOME/functions, or if HOME is also not set, ./functions. The rules for selecting the function path for the fn commands are:

1. If the function name contains a /,the function path is implied in the name, as in /users/moe/func.1 or ./func.2.
2. If the function exists in your private function directory, that version will be used.
3. If there is an executable by the chosen name in the public function directory, that function will be used.
4. Otherwise a new function will be created in your private function directory.

Public functions

Public functions are located in the directory $CPLOTHOME/functions. The functions in the public directory can't be edited or compiled in the usual way. Either executables can be copied to the public directory or the functions can be invoked according to rule 1 above.

Editors

C-PLOT will automatically invoke an editor when you create or modify a user function. If you have the environment variable EDITOR set, that editor is used. Otherwise, the default editor, vi, is used.

How does it work?

For each type of function, a prototype file is copied from $CPLOTHOME/prototypes, and your private function directory. and given the name you selected. The prototype contains skeleton C subroutines and help information appropriate for the function type you selected. You are then put into your chosen editor.

On exiting the editor, the shell script $CPLOTHOME/bin/makefunc is run from the function directory. That file normally invokes the C compiler to compile your module and link it with the appropriate overhead modules. If your user function contains the string cplot_compile: followed by commands to compile your function, those commands are used instead of the default commands from makefunc. The commands can refer to the make utility or invoke the C compiler directly. Possible ways of including the information in a function source file are::

/*
 *    cplot_compile:  make my_func.5
 */

or:

#if 0
    cplot_compile:  make my_func.5
#endif

If there are errors from the commands executed by makefunc, you are asked if you want to go back to the editor and try again. Otherwise the function is run.

If the function is already compiled and the modification date of the compiled code is more recent than that of the source, the function is executed as a child process of C-PLOT. Synchronization and communication between C-PLOT and the function is by pipe reads and writes.

Entering ^C while a type 1, 2 or 3 function is generating data will cause each successive point to be displayed. Entering ^C again will abort the current run of the function.