FISH Callback Events

FISH functions may be called from several places in the FLAC3D program while it is executing. The fish callback is used to manage registering FISH functions with specific callback events. There are also various commands that allow FISH callbacks to be registered in order to customize the command operation.

Attaching a FISH function to a callback event causes the FISH function to be executed by FLAC3D, either at a fixed point in the cycle sequence or in response to a specific event. The cycle points can be listed with the program list cycle-sequence command, and a subset of the available events is given here.

One can list the set of FISH functions registered with callback events via the fish list callbacks command.

There are two ways to create a FISH execution. The preferred way is to use the standard in-line FISH square bracket syntax:

[global a = 2.0]
fish operator fred(arg)
    ; Does something to model
	return math.sin(arg*dynamic.time)
end
fish callback add [fred(a)] -100

Or you can directly give the name of the function on the command line, along with any arguments it requires when it is called in parenthesis:

fish callback add fred([a]) -100

Please note that arguments are handled differently in these two cases. In the first case everything between the square brackets is parsed as FISH, a small function is created automatically that executes the content deliminated there. This means that the arguments are evaluated every time the function is called. In the second case the function and the arguments are parsed and stored by the command processor, so the argument is evaluated once and the results stored and used every time the function is called.

Some callback events and locations require that the function take an argument that is provided by the call. An example of this is when the fish-local keyword is used as a FLAC3D apply logic multiplier. In this case to use the square brackets requires that the inline FISH function created take an argument. The syntax for this is [[arg]xxxxx], where ‘arg’ is the argument being provided to the inline fish function. An example of this is below:

In the example above the local value gp is provided as an argument when the callback is executed. The value can be used in the inline FISH contents just like a local argument to a FISH function.

The fish callback command can be given with the remove keyword to un-register FISH functions. For example:

fish callback remove xxx 11.0

removes the association between function xxx and cycle point 11.0. Note that a FISH function may be associated twice (or more) with the same cycle point. In this case, it will be called twice (or more). The remove keyword will remove only one instance of the FISH function.