![[Contents]](TOC.GIF){kind=small}
![[Prev. Chapter]](REW.GIF){kind=small}
![[Next Section]](NEXT.GIF){kind=small}
![[Next Chapter]](FF.GIF){kind=small}
![[Index]](INDEX.GIF){kind=small}
![[Help]](HELP.GIF){kind=small}
Use the Tool Integration Language (TIL) to specify the following information about the tool:
Name and key combination for tool startup
Startup specifications so that it can be initialized and started when invoked from FUSE
Message list, the set of messages that a tool sends and receives
States so that it can send and receive FUSE messages during each tool state
Interface to FUSE (executable using C functions or script commands)
Use within FUSE (its availability and its use of the configuration dialog box)
Use the TIL compiler to compile the TIL file to generate information usable by the FUSE Control Panel and the message server.
TIL statements are declarative. You can use one TIL file for each tool or one file for several tools but you cannot split up one tool's information among files.
The TIL language defines a class for each tool. The tool class contains three clauses:
Attributes: Declares information about the tool that the Control Panel uses for identifying, starting, running (executable or script commands), and using configuration dialog boxes for the tool. Many attributes have default values so that you do not have to specify them in the TIL file.
Messages: Declares the list of messages that the tool can send and receive, and the message types.
States: Declares the states and the messages that can be sent and received while the tool is in each state. Although a state can be anything you want, you usually use a state to limit tool activities. For example, you may want to declare a busy state while the tool is working on a task that cannot be interrupted. You can then declare that no messages can be sent or received while the tool is in the busy state.
The format of a tool specification is as follows:
class tool-name ={
Attributes {
label = "tool-label";
accel = "key-combination";
path = "pathname";
multiple = true | false;
multidefault = true | false;
server = true | false;
grouping = local | global;
language = "C" | "script";
active = true | false;
dialog {
normal = show | hide;
auto = show | hide;
recall = show | hide;
request = show | hide;
};
};
Messages {[message-property...] return-value message-name ([param)[,...]];
.
.
.
};
States {
start {
receives {message-name[,message-name ...]
};
sends {message-name[,message-name ...]
};
};
[state-name {
receives {message-name[,message-name ...]
};
sends {message-name[,message-name ...]
};
};
.
.
.
};]
};
};
To comment information in the TIL file, place the comment
within
/* */
pairs, as follows:
/* comment-text */
![[Prev. Section]](PREV.GIF){kind=small}
Specifies the class name for your tool.
Specifies the name of your tool, which must be unique in FUSE. If you specify a non-unique name, the TIL compiler reports an error.
Specifies information about your tool for use by the Control Panel and the message server.
Specifies the label for the tool's entry in the Control Panel and FUSE Tools menus in tool-label). It must be unique in FUSE. If you specify a non-unique name, the TIL compiler reports an error.
Specifies the key combination for starting the tool in key-combination). If you do not specify this keyword in the TIL file, the default is no key combination.
The key combination for FUSE tool startup is a Meta key plus another key (lowercase only). The key combination are listed in FUSE Tools menus next to the name of the tool. For example, to start the Builder, the key combination is Meta+b. You can follow the Meta+key convention, use another Motif-compliant combination, or leave it blank. If you specify a key combination, make sure that it is not currently used by any other FUSE tool. If it is used by another tool, the TIL compiler reports an error. Refer to the for a list of all key combinations used in FUSE.
Specifies the pathname for the Control Panel to start the tool in pathname). You can specify an absolute pathname or a script command. The use of an absolute pathname ensures that the Control Panel can always find the tool from wherever FUSE is started. You should not rely on the user's setting of $PATH to find the correct tool.
You can use an environment variable in the pathname.
For example,
you can use the $FUSE_BIN
environment variable.
$FUSE_BIN
is defined according to where FUSE
is installed on your system and is, by default,
/usr/opt/fuse/bin.
For example, the pathname for the Builder is
$(FUSE_BIN)/builder.
The environment variable can also be any variable required
by your tool.
It must be preceded by a
$
and
closed within parentheses.
For example, the pathname for your tool
can be:
$(HOME)/test/test-tool.
The environment variable is expanded when FUSE starts up. Therefore, any variable that is used in the tool pathname must be defined at the time FUSE starts up.
This is a Boolean value that specifies whether multiple instances of the tool are allowed to run within a tool group. The value true) means multiple instances in a tool group are allowed; the value false) means only one instance in a tool group is allowed. If your tool cannot accurately differentiate among incoming messages, you may want to limit it to one instance in a tool group to avoid possible conflicts.
If you do not specify this keyword in the TIL file, the default value is true.
This is a Boolean value that specifies whether the tool acts as a server. If it acts as a server for other tools in FUSE and does not have a user interface, specify a value of true). If your tool does have a user interface, specify a value of false). A value of true) means that your tool is not listed in the Control Panel and FUSE Tools menus; false) means that your tool is listed and can be started by the user.
If you do not specify this keyword in the TIL file, the default value is false.
Specifies whether the tool will exchange messages with tools only within its tool group or with tools in all tool groups. Specify global) to exchange messages with tools in all tool groups; specify local) to exchange messages with tools within the tool's own tool group.
If you do not specify this keyword in the TIL file, the default value is local.
Specifies the tool's interface. If you use the C interface for your messaging functions, specify C. If you use the script interface, specify script). This value is used by the TIL compiler to generate code appropriate for the C functions or script commands.
If you do not specify this keyword in the TIL file, the default value is C.
A Boolean value that specifies whether the tool
is automatically listed on FUSE Tools menus.
The value
true
means that the tool is listed on FUSE Tools menus;
false
means that the tool is not listed on FUSE Tools menus until you
make it available from the Control Panel.
If you do not specify this keyword in the TIL file, the default value is true.
Specifies when the configuration dialog box for
the tool is displayed.
A value of
show
or
hide
is specified for each of four stages:
normal: The tool has been started for
the first time from the Tools menu on the Control Panel (or by a
keyboard equivalent).
auto: The tool has been started for the
first time by an automatic startup request from another tool (either
through triggering or from the Tools menu of that tool).
recall: The Recall Configuration...
item
from the Control Panel Tools menu has been selected for the tool
for the first time.
request: The tool is being reconfigured
by a request from the user.
The value
show
displays the configuration
dialog box for the user to complete before the tool continues; the
value
hide
does not display the configuration
dialog box and the Control Panel provides the configuration information.
If the Control Panel configuration information is incorrect (based
on the tool's verification of the Control Panel information), the
configuration dialog box is displayed even though
hide
is specified.
If you are not using a configuration dialog box, specify
hide
for each stage.
The values you specify determine the value returned by the
Control Panel's
QuerySystemInfo
message.
Refer
to
Chapter 5
for more information about this message.
If you do not specify this keyword in the TIL file, the default values are as follows:
normal = show auto = show recall = hide request = show
Specifies the list of messages, in a C-style format, that the tool sends and receives in FUSE.
[message-property...] return-value message-name({param[,...]]);
Declares how the tool responds to a message, if other than default behavior is required:
trigger: Specifies that the message must
be received by the tool.
If the message is sent and no tool receives
the message, because the tools currently running are in a state
where they do not listen for or only eavesdrop on the message, the
message server looks for another tool class that receives the message
as a trigger.
If a tool class is found, the message server sends
a request to the Control Panel to start an instance of the tool
(in the same tool group of the tool that sent the message) and the
message as a trigger, then on instance of one of the tools is started,
but it cannot be predicted which tool is started.
If the messag
still cannot be delivered, it is dropped.
eavesdrop: Specifieds that the tool has
an interest in the message received and accepts the message but
does not otherwise process it.
Use this message property when a
tool needs to be aware of a message.
If the eavesdrop message received
has a return value, any attempts to reply (using a reply or message-finish
function or command) are ignored.
override: Specifies that only the message
property previously declared for a message be superseded by the
specified message property.
Use this property when you need to
change messages that are declared with
#include
statements in the TIL file without having to chagne the include
file.
Then, the override instructs the tool to ignore any previous
definition for thtat message and accept the new definition.
The following example applies the eavesdrop property to the
ToolStartNotification message without having to change that message
in the
message_lib.msg
file:
Messages {
#include "message_lib.msg"
override eavesdrop char *ToolStartNotification (char *class, char *host);
}
You can combine the trigger and eavesdrop properties for a message. With this combination, when a trigger message is received, the target tool is started. The next time a trigger message is received by that tool, the tool acts as an eavesdropper. When you use both message properties, define the message as follows:
trigger eavesdrop return-value <message-name>(param,...);
Indicates the response to the message that is sent. It can be one of three types:
sync: Specifies that no data is returned,
but once the message is sent, the tool is notified when all message
receivers have received and processed the message (synchronized
message).
void: Specifies that no data is returned
because the tool does not expect a response.
char*: Specifies that data is returned.
Specifies the name of the message and must be unique in FUSE. Check the message list in to make sure that the tool does not use a name that already exists.
Specifies message parameters that must be one of
the following supported data types:
int, float, char *,
char, or
long.
If any other data type is specified, the TIL compiler reports an error.
The default messages that each tool needs when working in FUSE must also be specified, as follows:
#include "message_lib.msg"
Refer to Section 4.1.2 for an example of specifying the default message library.
Specifies the states and sets of
messages that are allowed to be sent and received by the tool in
each state.
The only required state is
start;
howevever, if your tool receives a trigger message, it must also
declare a
running
state.
You can define any other
state and state name.
Do not use hyphens in state names.
For each
state, list all messages that can be received by the tool in the
receives
clause and list all messages that can
be sent by the tool in the
sends
clause.
A message
in a sends clause causes the TIL compiler to generate a stab routine
to send the message.
If messages are not listed in
receives,
the tool cannot receive any messages in that state.
At a minimum,
the following macros must be listed to enable the sending and receiving
of the required FUSE messages defined in
message_lib.msg:
sends {
MESSAGE_LIB_SEND
}
receives {
MESSAGE_LIB_RECV
}
If no message can be sent or received, omit the
receives
and
sends
clauses.
When you list messages, specify only the message name. If you list a message that has not been declared in the Messages attribute, the TIL compiler reports an error.
After you complete the TIL file for your tool, compile it using the til command. The C preprocessor cpp is also run on all files. The syntax of the TIL command is:
til [option ...] file ...
Depending on the options you specify, the compiler produces some or all of the following:
Error diagnostics about the TIL file
C files (FUSE_class-name.c
and
FUSE_class-name.h
files) for the tool's messaging
functions
A new startup file (a
tools.rc
file) for use by the Control Panel and the message server for identifying
and starting the tool
A new FUSE message schema (a
fuseschema.msl
file)
By default, if you do not specify any options or files, the TIL compiler produces error diagnostics on TIL files in the current directory, generates C files, and produces a new FUSE message schema and startup file in the working directory. These do not replace what is currently being used by FUSE.
After you write the TIL file for your tool, check that the TIL syntax is correct before you attempt a complete build of the file. Use the -syntax option so the compiler will not generate C files, a new startup script, or a message schema.
% til -syntax tool.til
The TIL compiler reports all errors to standard output.
After you have verified that your TIL file is correctly defined, choose which compiler processing actions you need:
-no_ansi option:
If you are using a C compiler that is not ANSI C compliant, use
this option.
When you specify this option, all parameters in the
function prototypes of the generated code are commented out to avoid
compilation errors.
-D
and
-U
options: To override the C preprocessor definitions of directives
in your source file, use the
-D
option to define
a name and the
-U
option to remove the definition
of a name.
These options are useful for conditional source code
compiling.
Refer to the
cpp(1) reference page
for more information.
-I
options: To specify pathnames
for header and TIL files to be used in addition to default files,
use the -I option.
If you do not use this option, only the working
directory and the
$FUSE_TOP/rundata/schema
directory
are searched for header and TIL files.
-d
and
-a
options: To overide the active statement specified in the TIL source
file, use the
-d
option to specify that the tool
will be inactive and use the
-a
option to specify
that the tool will be active.
You can use these options to change
the availability of a tool without modifying its TIL file.
To generate
C files, specify the
-c
option.
You can specify
one or more classes.
The class name you specify must match the
tool-name
you defined for the class attribute in the TIL file.
The
-c
option produces the
.c
and
.h
files for your tool's messaging functions,
using the following default file names:
FUSE_tool-name.h and FUSE_tool-name.c.
The .h file provides the function prototypes that must be included
in the tool's C source file.
If you do not want to generate a new startup script
tools.rc
or message schema
fuseschema.msl, use the
-no_schema
option with the
-c
option.
If you do not specify
-no_schema, a new
tools.rc
file and
fuseschema.msl
are produced for your
tool and the other tools in the working directory.
The
tools.rc
and
fuseschema.msl
files do not replace the
tools.rc
or
fuseschema.msl
files being used by FUSE.
You
should test and debug the schema before replacing the FUSE schema.
Refer to
Section 4.1.4
for an example of debugging
the integration of a tool.
For example, to generate the C files, a new
tools.rc
file, and a new
fuseschema.msl
file for two tools
that are defined in one TIL file, issue this command:
% til -ctool1 -ctool2 tool.til
After executing this command, the TIL compiler produces the following files in your working directory:
The source and include files for the tool's messaging functions:
FUSE_tool1.c
FUSE_tool1.h
FUSE_tool2.c
FUSE_tool1.h
tools.rc, which is the new startup
script
fuseschema.msl, which is the
new message schema
To generate only C files of the message functions, issue this command:
% til -ctool1 -ctool2 -no_schema tool.til
When
you have debugged your tool and are ready to replace the FUSE message
schema and startup script, use the
-install
option.
The
-install
option builds a new startup script
and a new FUSE message schema, including your tool, and replaces
the current startup script and FUSE message schema with the newly
built script and schema.
If you specify the
-no_ansi, -c,
or
-no_schema
option with
-install,
they are ignored.
When you use the
-install
option, make
sure you have copied the TIL file for the tool to the
$FUSE_TOP/rundata/schema
directory.
You will probably have to issue the
til
command from a privileged account because
$FUSE_TOP/rundata/schema
is usually owned by the superuser.
For example, to build and install
a new schema including two new tools, you copy the TIL file to$FUSE_TOP/rundata/schema
and then issue this command:
% til -install
The TIL compiler produces these files in the directory
$FUSE_TOP/rundata/schema
after executing the command with
the
-install
option:
tools.rc
fuseschema.msl