Professional Documents
Culture Documents
Reference
Copyright
This is the twelfth edition of the TSL Guide & Reference. It refers to version 3.2 of
Metrica/NPR.
Printing History
November 1991
February 1992
August 1992
September 1993
March 1995
June 1995
February 1996
April 1997
September 1998
August 2000
August 2000
December 2001
First edition
Second edition with minor revisions
Third edition with minor revisions
Fourth edition updated for Metrica/DMS 4.0
Fifth edition updated for Metrica/DMS 4.1
Sixth edition with minor revisions
Seventh edition updated for Metrica/DMS 4.2
Eighth edition updated for Metrica/DMS 4.3
Ninth edition updated for Metrica/DMS 5.0
Tenth edition, updated with revisions
Eleventh edition, revised for Metrica/NPR Release 3.1
Twelfth edition, updated for Metrica/NPR Release 3.2
Contents
Preface
vii
Introduction
What is TSL? . . . . . . . . . . . . . . . . .
Running the examples in this guide
Encrypted and normal TSL . . . . . .
Checking the syntax of TSL scripts
The Look and FeelMotif . . . . . .
Chapter 2
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
TSL Basics
Principles of TSL . . . . . . . . . .
Embedded TQL . . . . . . . . . . .
Variables . . . . . . . . . . . . . . . .
Procedures . . . . . . . . . . . . . .
Text lines . . . . . . . . . . . . . . .
Text items . . . . . . . . . . . . . . .
TSL and TQLwho does what?
The main window . . . . . . . . .
The Help menu . . . . . . . . . . .
TSL and Window managers . .
Attributes . . . . . . . . . . . . . . .
Icons . . . . . . . . . . . . . . . . . .
Dimension Units . . . . . . . . . .
Chapter 3
..
.
..
..
..
7
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2
2
4
5
5
..........
..........
..........
..........
.
.
.
.
8
8
9
9
12
12
15
15
17
18
19
20
20
23
.....
.....
.....
.....
....
....
....
....
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
24
27
28
30
Contents
Chapter 4
Dialogs
A dialog window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Convenience dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The error dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The information dialog . . . . . . . . . . . . . . . . . . . . . . . . .
The progress dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The confirmation dialog . . . . . . . . . . . . . . . . . . . . . . . . .
The list selection dialog . . . . . . . . . . . . . . . . . . . . . . . . .
The file selection dialog . . . . . . . . . . . . . . . . . . . . . . . . .
Text substitution in convenience dialogs . . . . . . . . . . . . .
Creating a dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dialog item types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Text fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiline Text fields . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sliders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Toggle buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Option, List and Panel . . . . . . . . . . . . . . . . . . . . . . . . . .
Calendars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Time range bars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application defined buttons . . . . . . . . . . . . . . . . . . . . . .
Presetting dialog items from a database . . . . . . . . . . . . . . . .
Dialog layout and default positioning of dialog items . . . . . .
Defining the position of dialog items . . . . . . . . . . . . . . . . . .
Changing the control buttons . . . . . . . . . . . . . . . . . . . . . . . .
Managing multiple dialogs . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the contents of a list . . . . . . . . . . . . . . . . . . . . . . .
The INSERT list editing command . . . . . . . . . . . . . . . . .
The DELETE list editing command . . . . . . . . . . . . . . . . .
The REPLACE list editing command . . . . . . . . . . . . . . . .
The APPEND list editing command . . . . . . . . . . . . . . . . .
The CLEAR list editing command . . . . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the SENSITIVE attribute in a dialog . . . . . . . . . . . . . . .
37
38
39
40
40
41
42
43
45
46
46
49
51
55
56
56
57
61
61
62
63
64
68
70
74
79
81
82
82
83
83
84
84
86
Chapter 5
89
Chapter 6
Reports
Formatted reports . . . . . . . . . . . . . . . . . . . . . . . . .
Text expansion in reports . . . . . . . . . . . . . . . . . .
The PRINT and PRINTLN commands . . . . . . . . . .
Format string syntax . . . . . . . . . . . . . . . . . . .
Simple page control . . . . . . . . . . . . . . . . . . . . . .
Free format reports . . . . . . . . . . . . . . . . . . . . . . .
Defining reports . . . . . . . . . . . . . . . . . . . . . . . . .
Pagestyles . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Printing reports to a file or a printer . . . . . . . . . . .
Printing reports: example . . . . . . . . . . . . . . . . . . .
Chapter 7
95
....
....
....
....
....
....
....
....
....
....
....
...
...
...
...
...
...
...
...
...
...
...
Graphics
Kingfisher graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Canvas types . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Kingfisher Procedures . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing procedures . . . . . . . . . . . . . . . . . . . . . .
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Printing a canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling hardcopy details . . . . . . . . . . . . . . . . . .
Loading hardcopy configuration . . . . . . . . . . . . . . .
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Other canvas commands . . . . . . . . . . . . . . . . . . . . . . .
Raising and hiding the canvas window . . . . . . . . . .
Creating a graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Graph formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Positioning and sizing a graph . . . . . . . . . . . . . . . .
Implicit creation and destruction . . . . . . . . . . . . . .
Changing the format of an existing graph . . . . . . . .
Accessing graph formats . . . . . . . . . . . . . . . . . . . .
. 96
. 96
101
102
106
106
108
108
109
110
117
121
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
122
122
124
125
126
126
126
127
129
129
130
130
130
131
132
132
133
133
134
134
iii
Contents
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Query Errors in GRAPH DRAW . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
More graphics features . . . . . . . . . . . . . . . . . . . . . . . .
Plotting overlays . . . . . . . . . . . . . . . . . . . . . . . . . .
Graph properties . . . . . . . . . . . . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The graph cursor . . . . . . . . . . . . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Loading a colourmap . . . . . . . . . . . . . . . . . . . . . . .
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating multiple graphs . . . . . . . . . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating and managing multiple canvasses . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Approaches to developing graphics in TSL . . . . . . . . . .
Using Kingfisher procedures . . . . . . . . . . . . . . . . .
Using GRAPH commands . . . . . . . . . . . . . . . . . . . .
Chapter 8
Miscellaneous Topics
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
135
135
135
136
137
137
139
140
141
142
143
143
144
146
147
149
149
150
153
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
154
155
155
156
158
159
160
161
161
162
163
163
164
165
166
166
167
Chapter 9
General principles . . . .
Consistency . . . . . .
Robustness . . . . . .
Style guide . . . . . . . . .
Icons . . . . . . . . . . .
Menus . . . . . . . . . .
Toolboxes and tools
Confirmation dialogs
Error dialogs . . . . .
Progress dialogs . . .
Information dialogs
File selection dialog
Selection dialog . . .
Main window . . . .
Dialogs . . . . . . . . .
Dialog items . . . . .
Dialog layout . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
173
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
174
174
175
175
175
175
176
176
177
177
178
178
178
178
179
180
182
Index
185
Error Messages
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
357
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
358
358
359
359
377
381
Preface
Preface
vii
PART 1
TSL Guide
Chapter
Introduction
1
Introduction
Chapter
Introduction
What is TSL?
TSL is a Technical Scripting Language which allows non-programmers
to create sophisticated applications based on TQL databases. TSL
provides a very simple mechanism for specifying both the user interface
and controlling the logic of an application. It allows TQL queries to be
embedded in the script enabling you to retrieve and manipulate data in
the database. This data can be presented in user interface elements,
printed on the screen or printer, plotted on a graph or used to control
the application further.
TSL lets you create a modern user interface for your application based
on the X Window system. All TSL applications have a similar look and
feel making them more familiar and easier to learn for yourself and
your users. TSL lets you create a pull-down menu system to instigate
operations in your application, such as plotting a graph, and lets you
define pop-up dialogs for viewing and changing the properties or
attributes of an operationfor example, the range of data on a graph.
The end result is an easy-to-use, windows-based application that
enables your users to concentrate on the analysis and functionality of
the application rather than its interface.
TSL was designed to be used by the wide range of people who need to
build data analysis and reporting applications, not just for programmers.
Its simple command language is genuinely easy to use, flexible and is
free of the complex concepts found in programming languages. The
high level nature of the language and its ease of use makes
programming with TSL highly productive and effective. The simplicity
of the language makes applications very easy to maintain and modify
and this can often be done by the end user.
This guide assumes that you are familiar with TQL and Kingfisher.
TQL_CLIENT_DIR=/users/tqlclients
export TQL_CLIENT_DIR
To run TSL with one of the example scripts you can simply enter the
command:
tsl <script-path>
where <script-path> is the full path name of the script file you wish
to run, for example:
tsl $TQL_CLIENT_DIR/demos/tsl/example1.tsl
However, you may find it easier if you set up the environment variable
TB_TSL_SPEC_PATH to tell TSL where to search for script filesyou can
then run a script by passing the name of the script file, for example:
tsl example1.tsl
Note, TSL scripts should use the suffix .tsl as the TSL
encryption utility only recognises files that have this suffix as
unencrypted TSL files. For information on the encryption utility,
see the Utilities manual.
If you are using the Bourne or Korn shell, use the syntax:
TB_TSL_SPEC_PATH=$TQL_CLIENT_DIR/demos/tsl
export TB_TSL_SPEC_PATH
Chapter
Introduction
TSL first looks for the file example1.tsl. If this is not found, it looks
for the file example1.tse.
If TSL is invoked with a file which has neither a .tsl or a .tse suffix, TSL
first looks for this file in the directories specified by
TB_TSL_SPEC_PATH.
If it does not find this file, it looks for the file with the .tsl suffix added
to the end of the file. If this file is not found, TSL looks for the file with
the .tse suffix appended to it. Finally, if neither of these files are found,
TSL looks for the given file.
If TSL was invoked with the command:
tsl example1
TSL first looks for the file example1, then the file example1.tsl and
finally the file example1.tse.
Chapter
TSL Basics
2
TSL Basics
Chapter
TSL Basics
Principles of TSL
A TSL application consists of one or more script files. A script file is an
ASCII text file created with an editor such as vi which is executed by
the TSL interpreter. The interpreter reads the script one line at a time
and decides whether the line is a command, text, or a comment.
Commands are executed, text is printed and comments are ignored.
Comment lines begin with the symbol #, text lines begin with a single
quote , all other lines are commands. Blank lines are ignored and
spaces at the beginning of the line are skipped. For example:
# This is a comment
# The next line is a command
query display volts from results ;
This line is simple text
Commands are used to execute queries, set up the user interface and
control the flow of the application. Text is used to print simple
messages or reports in the window.
All commands, except the QUERY and GRAPH DRAW commands, consist
of only one line. If you need to continue the command onto another
line, put a backslash at the end of the line, like this:
dialog list(3) longlist "A list" "Item 1" "Item 2" \
"Item 3" "Item 4"
All TSL commands are case insensitive, thus the command DIALOG
LABEL is equivalent to the command dialog label.
Embedded TQL
Perhaps the most important TSL command is QUERY. This command
allows TQL queries to be embedded in an application. The QUERY
command is followed by any TQL command. Unlike other TSL
commands the QUERY command can run onto more than one line and
consequently it must be terminated by a semicolon. Here are some
examples:
query open db ;
query display test#, volts, resist from results ;
query select test#, volts, resist, current
from results where test#>20 to temp ;
You can embed any TQL command in a script using this command.
Notice also that a DISPLAY command that would normally print data to
the screen does not do so in TSL. Instead the data is retrieved into an
Variables
internal buffer which your TSL application can use as required. (The
Query buffer is explained later in this guide.)
Variables
Almost all applications need to make use of variables. A variable is
simply a named bin into which any piece of data can be placed. TSL
creates and uses variables to return the results of dialogs back to your
application and also to set status codes for graphic and data transfer
operations. Your application will need to use variables to control the
flow of the script and to construct queries.
Variables only exist in the TQL Server. TSL itself does not have any
variables but creates them on the server by issuing TQL commands.
Variables are created using the TSL DECLARE command and their values
are changed using the SET command.
declare a, b
set a "Hello", b 24
Procedures
When writing a TSL program, you may find yourself frequently
repeating sequences of commands which differ only in the names of
variables. To save you typing such sequences more than once, TSL
allows you to define them as procedures. A procedure is essentially a
named list of commands which can be called from within a TSL
program with different values, or arguments.
The syntax of a TSL procedure is:
defproc procname ( paramlist )
tsl_commands
endproc
Chapter
TSL Basics
Procedures
For example:
defproc factorial( var x )
if x = 1
return
else
declare y (x - 1)
call factorial( y )
declare x (x * y)
endif
endproc
The first argument (12) is stored in the first parameter (x), the second
argument is stored in the second parameter and so on. You should note
how the third parameter, which is passed-by-reference, was passed a
variable. You should also note that a procedure must be defined prior
to it being called.
A procedure can use global variables (variables not declared inside any
procedure) as well as its parameters and any variables declared within
the current call of the procedure (known as local variables). It may not
use variables which are local to another procedure call.
11
Chapter
TSL Basics
For example:
declare a 0
defproc proc1( p1 )
set x p1
endproc
defproc proc2( p2 )
declare x p2
call proc1( z )
endproc
declare z 12
call proc2( 10 )
In this example the procedure proc2 can use the parameter p2, the
global variables a and z and the local variable x.
The procedure proc1 can use only the parameter p1 and the global
variables. Therefore an error will occur when TSL attempts to assign the
value of p1 to the variable x, as the variable x (local to proc2) does not
exist to proc1.
TSL ignores multiple occurrences of definitions of a procedure and it
only notes the location of the first occurrence of a procedure which has
a given name.
Text lines
A text line is a line in the script that begins with a single quote. Text
lines are simply printed on the output, either the screen or a printer,
and so are used for simple printing and reporting purposes. For more
flexible and controllable printing, use the PRINT and PRINTLN
command.
Text items
Text lines and some commands can contain text items. A text item is a
column name or expression enclosed in square brackets. When a text
item is encountered its value is determined and the value replaces the
text item in the line. Consider the following:
The value of A is [A]
Text items
2.
3.
13
Chapter
TSL Basics
where procname is the name of the procedure and arguments are the
arguments to be passed to the procedure. Text substitution is performed
only on arguments and not on procname. So while its possible to
pass different arguments to the procedure depending on, for example,
the values the user selects in a dialog, it is not possible to alter the
procedure that is called.
Placing an EXPAND command before a TSL command means that text
substitution may be performed on any argument or field in the TSL
command. Therefore, you can replace any part of a command or even
an entire command with a text item. Using text substitution to assign
values to variables within a command provides a powerful
programming tool which, if used correctly, enables you to create more
flexible programs that are easier to maintain.
For example, using EXPAND with the CALL command means that both
the name of the procedure and the arguments that are passed to the
procedure may be supplied as variables. So it is possible to write the
following:
EXPAND CALL [procvar] [argvar]
the TSL interpreter sends the query to the database server. The server
executes it and returns the data to TSL.
TSL is completely ignorant of all arithmetic and data manipulation. For
example when you execute an IF command the condition part is sent
by TSL to the database server for execution. The implication of this is
that you have access to all the mathematical and data manipulation
functions of TQL throughout your application. However, since all
expressions are evaluated on the server, TSL would not be a good
language in which to write compute-intensive applications.
When writing scripts that will be run in a client/server configuration it is
important to bear in mind that the interactive performance of your
application can be improved by attempting to reduce the number of
queries that are executed on the server. In particular, you should always
create and set multiple variables in a single SET command if possible,
also make use of the SWITCH command (described later) in preference
to the IF command as this is normally executed without help from the
server.
15
Chapter
TSL Basics
and maximise buttons, but this depends on the window manager you
are using and how it is configured.
appropriate scroll bar. This allows you to scroll through any part of a
report that has gone off screen.
This user interface model of a menu bar, toolbox, scrolled window and
dialogs is used for all TSL applications. Indeed the same model is used
for very many software packages and is likely to be familiar to yourself
and your end users.
17
Chapter
TSL Basics
The HELPFILE command can occur at any time in a script. This allows
you to build a set of files for different contexts in your application. The
user sees different help depending on the action they are engaged in at
the time. This context-sensitive help is much more likely to be read by
your users as it helps them with their immediate task.
Helpfiles can contain comments. These are lines where the first
significant character is a hash (#) character. Commented lines are not
displayed. Thus, if you use a revision control system such as RCS, you
can put an RCS comment in the helpfile.
The environment variables TB_TSL_SPEC_PATH and TB_SPEC_PATH are
used to search for these files.
The environment variable TSL_HELP_EDITOR specifies the path and
name of any external editor used to display the help files, for example
/usr/netscape/netscape.
The environment variable TSL_HELP_DEFAULTPAGE specifies the name
of the default file that is displayed if the current help file is not located,
for example $NPR_DIR/default_help.html.
You should keep the title fairly short as the window manager does not
guarantee to display it all.
Normally, if you are in a Motif environment you use the Motif window
manager mwm. A Motif application relies on the window manager for the
window decorations: the borders, function buttons and window menu.
If a Motif application is run with a non-Motif window manager, such as
twm or uwm, your application will have a different style of decoration.
Just as the visual appearance is determined by the window manager so
are some details of behaviour. In particular, the initial placing of the
window and whether it can resize.
The initial size of the TSL main window is configured in the X defaults
file. TSL also asks the window manager to stop the user resizing the
window horizontally. If you are using an incompatible window
manager, this may not work.
Attributes
Attributes
Many TSL commands such as DIALOG and PAGESTYLE use attributes to
modify the behaviour of the command. For example, the MINWIDTH
attribute to a DIALOG LIST command sets the minimum width of the
list.
Attributes are written in the form:
attribute_name = attribute_value
For example:
action = "Exit"
Spaces are ignored between the attribute name and the equals and
between the equals and the value being assigned to the attribute. A list
of attribute-value pairs may be given by separating the pairs with
spaces or commas.
The ACTION and SENSITIVE attributes are used by most of the user
interface commands DIALOG, MENU and TOOL.
The ACTION attribute is used to define the string that is put in %MENUVAL
when a tool or menu action is pressed or %BUTTONVAL when a dialog
button is pressed or the value of a dialog item is changed.
The SENSITIVE attribute is used to define whether the menu, tool or
dialog item can be selected. The SENSITITVE attribute is a member of a
special family of attributes which includes the READONLY, ALLOWNULL,
RANGEMIN and RANGEMAX attributes, which are evaluated each time an
ASKDIALOG or ASKMENU command is called.
These attributes can be set to a TQL expression, a TQL variable or a
constant value (like TRUE). If they are set to a TQL expression or
variable, the value of the attribute can change each time the ASKDIALOG
or ASKMENU command is executed. Thus a sensitive menu item could be
made insensitive and vice versa.
For example:
menu 1-1 "Load ..." action = "Load", \
sensitive = "sysuser() = 'DBA'"
defines a menu item Load... which can only be selected by the user
DBA and puts Load into %MENUVAL if the menu action is selected.
19
Chapter
TSL Basics
Icons
An icon is a picture that can be displayed either on a tool in the toolbox
or on a label or a button in a dialog. An icon is created by TSL by
reading the contents of a bitmap file which defines the picture to use.
Bitmaps can be created using the application bitmap.
To specify a bitmap you need either to give the full path that your
operating system must use to find the file, for example:
$TQL_CLIENT_DIR/bitmaps/Kingfisher/kingfisher
where dir1, dir2 and dirN are the paths to the directory where the
bitmaps can be found. For example:
setenv XBMLANGPATH \
"$TQL_CLIENT_DIR/bitmaps/Kingfisher/%B"
Dimension Units
A dimension unit is used by TSL to define distances in centimetres,
millimetres, inches, pixels or characters. In addition, in dialogs the
position of a dialog item can be defined in grid units. Grid units and
grids are defined in full later in this guide.
A dimension unit consists of a number followed immediately by one of
the following letters:
Letter
Unit
centimetres
millimetres
inches
pixels
grids
Dimension Units
Letter
Unit
characters
is 10 centimetres.
2.3i
is 2.3 inches.
5
is 5 grid units.
Note that a number must be given before the decimal point, therefore
you must use 0.2 instead of .2 when defining a dimension unit that is
less than 1.
21
Chapter
23
Chapter
This command defines the first entry in the pull-down pane of the first
top-level item to be Open Database.
A toolbox consists of a number of tool groupings, also called tool
groups, where each group consists of a number of tools and a label.
A tool looks like a button with a picture on it representing the action
that occurs if the button is pressed. The picture is an icon and is read in
from a bitmap file as described in the previous chapter.
25
Chapter
A tool is selected by pressing and releasing the mouse button while the
mouse pointer is positioned over the tool.
The top-leftmost tool group is tool group 1 and subsequent toolboxes
are positioned below or to the right of the previous tool group.
You use the TOOL command to define the bitmap to use for a particular
tool in a tool group and to define a tool groups label. For example:
tool 1 "Kingfisher"
tool 1-1 "kingfisher" action = "Kingfisher"
Here the label for the first tool group is defined to be the string
Kingfisher. In addition the first tool of the first tool group is defined
to use the bitmap file kingfisher.
When a menu or tool is selected the identifier for the selected item, also
called the items action string, is returned in the special variable
%MENUVAL.
For a menu item the action string can simply be a string indicating the
items position in the menu hierarchy. For example:
menu 1-1 "Exit"
The action string for this menu item is the string 1-1.
You may want the menu items action string to be independent of its
position in the menu hierarchy. If this is the case the ACTION attribute
can be used to define the menu items action string. For example:
menu 1-1 "Exit" action = "Exit"
This sets the menus action string to be the string Exit. The remaining
examples in this guide use this method of defining a menu items action
string.
Tools, unlike menus, have no default action strings and so they must
have their action string defined using the ACTION attribute.
The menu system and toolbox are defined near the beginning of the
application. Items can be specified in any order but for clarity it is best
to define them from top to bottom, left to right.
Once the menu system and the toolbox are defined, you activate the
menu and toolbox using the ASKMENU command. This command causes
your application to stop and wait for the user to select either a menu
item or a tool.
A simple menu
Menu and tool items are, by default, sensitive and can be selected.
However, there may be situations where you want a menu or a tool
item to be unavailable for selection. The SENSITIVE attribute can be
used to define the items sensitivity. An insensitive menu item appears
greyed-out. Insensitive tools look the same as sensitive tools. As
described in the previous chapter, the SENSITIVE attribute is evaluated
each time an ASKMENU command is executed.
Once the ASKMENU command is executed the menu system and toolbox
cannot be changed or added to. Any attempt to execute a MENU, TOOL or
TOOLBOX (described later) command causes an error to occur.
A simple menu
The following example shows a simple TSL script which defines a menu
system with one pull-down pane.
# Simple Menu (example1.tsl)
#
title "Simple Menu"
menu 1 "Database"
menu 1-1 "Exit" action = "Exit"
repeat
askmenu
until %menuval="Exit"
This example sets the window title using the TITLE command and
defines the menu system. Notice how we have indented the second
MENU command to reflect its lower level in the menu hierarchy. Once
the menu system is defined we enter a loop and repeatedly ask for
input from the menu. When the user selects the Exit action we exit the
loop and the script finishes.
The loop is defined using the REPEAT and UNTIL commands. When TSL
encounters a REPEAT command, it executes all the lines till it finds the
matching UNTIL command. The condition after the UNTIL keyword is
evaluated. If the condition evaluates to TRUE, the loop is ended and
processing continues after the UNTIL command. If the condition
evaluates to FALSE or NULL, processing starts again at the matching
REPEAT command. The condition after the UNTIL keyword can be any
TQL expression that evaluates to a boolean result. This condition is
evaluated on the server and may use any functions or variables that are
defined.
27
Chapter
Notice how the Exit menu item has a position of 1-5 in the hierarchy
even though it is in position 4 in the first menu pane. Skipping a
position in the pane causes a separator, which looks like an etched line,
If the condition evaluates to TRUE, the lines between the IF and ELSE
commands are executed, otherwise the lines between the ELSE and
ENDIF commands are executed.
A further form of the IF construct is the ELIF command. This provides
a shorthand for the common sequence ELSE IF. For example:
if %menuval="Open"
query open db ;
elif %menuval="Close"
query close ;
29
Chapter
elif %menuval="Drop"
query drop database db ;
endif
This defines a menu where the main entry has a mnemonic of D and the
menu entries have mnemonics of P and E respectively. The character in
the menu label will be underlined on the screen and the menu entry
will be activated by pressing that key once the menu is displayed.
Note that, if the menu label contains multiple instances of the
mnemonic character, the first instance in the string will always be
underlined regardless of where the @ was placed.
It is good practise to provide mnemonics for all menu entries wherever
possible.
An accelerator is defined by following the menu label with the keysym
definition of the accelerator key sequence and optionally by the
accelerator label to place to the right of the menu label.
The keysym definition uses the standard Xt syntax. In its simplest form,
the keysym consists of:
modifier <Key> key :
When the accelerator key sequence is entered in the TSL main window,
the ASKMENU command will return as if the menu entry associated with
that accelerator has been activated. The menu will not, however, be
displayed.
In the following example a mnemonic is placed on the Exit menu
entry:
menu 1 "@Database"
menu 1-1 "Set @Password..." action = "Password"
:menu 1-3 "@Exit" "Ctrl<Key>E:" "Ctrl-E" \
action = "Exit"
1-1
1-2
1-3
1-5
This however would result in a gap between menu item 1-1 (Open) and
1-3 (Close). Thus a separator would be positioned between these two
menu items. To avoid this you would be required to renumber the
menu items in such a way as to ensure that the extra separator is
created between the Open and Close menu items.
If your application has a large and complicated menu hierarchy, this
would be time consuming and mistakes could easily occur.
31
Chapter
Alternatively, you could skip the menu item that you no longer want
using the MENU SKIP command. For example:
menu
menu
menu
menu
menu
1-1
1-2
1-3
1-5
1-2
This instructs TSL to ignore menu item 1-2. Note that a menu item can
be defined or skipped any number of times before executing an
ASKMENU but only the last command that is performed on that menu
item is renumbered.
The Toolbox
You are able to define many of the toolboxes attributes using the
TOOLBOX command.
The location of the toolbox with respect to the central work window is
defined using the GRAVITY attribute and it can be set to one of NORTH,
SOUTH, EAST or WEST.
The maximum number of rows or columns that tool groups may have is
defined using the ROWCOLS attribute. If the toolboxs gravity is NORTH or
SOUTH, the ROWCOLS attribute refers to the maximum number of rows in
the toolboxs tool groups otherwise this attribute refers to the maximum
number of columns in the toolboxs tool groups. For example:
toolbox gravity = south, rowcols = 2
This command positions the toolbox below the central work area, and
each tool group has two rows.
You can define whether tool groups within the toolbox have a frame
around them. A frame is drawn as an etched box surrounding the tools.
This is set using the FRAME attribute.
Finally, the distance between the tools of a tool group is set using the
TOOLGAP attribute and the distance between the tool groups is set using
the GROUPGAP attribute.
The default values of these attributes are:
GRAVITY = WEST
ROWCOLS = 2 if GRAVITY is EAST or WEST, otherwise 1
FRAME = true
The filename is the name of a TSL script file. If the filename contains a
slash, it is taken as the direct path to the file in the file system. If it does
not contain a slash, the file is searched for according to the
environment variable TB_TSL_SPEC_PATH, or if that does not exist the
variable TB_SPEC_PATH. These environment variables contain colon
separated lists of directories in which to search for scripts.
The difference between executing a script and calling a TSL procedure
is that a script is a continuation of the current script or procedure. This
means that variables created in a script exist when the script returns
33
Chapter
case "File"
To File
case "Kingfisher"
Kingfisher
endswitch
until %menuval="Exit"
35
Chapter
Dialogs
4
Dialogs
37
Chapter
Dialogs
A dialog window
Dialogs are separate windows which are displayed by the application
and dismissed when the user has finished with them. They are intended
to be used primarily as a data entry mechanism, but can be used to
specify an action through the use of user-defined buttons and dialog
items.
The user interacts with the dialog, perhaps entering data or reading
values, and presses a button to dismiss the dialog. Typically, the
application uses those values to control an operation that is to be
performed.
Convenience dialogs
situated between the main area and the control button area. The
different areas are separated by etched lines.
The dialog items represent the data of the dialog, for example, numbers
and strings. The user can interact with the dialog to change this data.
The application only continues when the user initiates a dialog action.
A dialog action occurs if a button is pressed or if the value of an active
dialog item changes. An active dialog item is one that was defined to
produce an action when the user changes its value.
If the OK, Apply or an application defined button is pressed, or the
value of an active dialog item is changed, the values entered in the
dialog are applied, and the application continues, making use of these
values. If the Cancel, Reset or Close button is pressed, the dialog is
reset with the values current when the dialog was last applied (or first
displayed).
The dialog is dismissed if the OK, Cancel or Close buttons are pressed;
otherwise it stays on the display for further interactions.
If the Help button is pressed, the current help file is displayed in the
help dialog. It may be useful to create context sensitive help for the
main dialogs in your application.
You can set the TSL_HELP_EDITOR environment variable to replace the
default help dialogs with an external editor.
Convenience dialogs
Some types of dialog are so common that TSL provides a number of
built in commands which create and use these dialogs. These are:
39
Chapter
Dialogs
41
Chapter
Dialogs
Notice how we have used a variable QUIT to finish the loop. If the user
presses the Yes, Exit button, the variable QUIT is set TRUE and the loop
terminates.
43
Chapter
Dialogs
either click on an option in the list or enter a value in the text field. The
application only continues when the dialog is dismissed.
45
Chapter
Dialogs
Creating a dialog
Dialogs are created in TSL by specifying dialog items. A dialog item is a
single user interface element such as a slider or toggle button.
All dialog items, except the label, button and skip dialog items, are
associated with a variable to return the value chosen by the user. Thus
a dialog, which is a collection of dialog items, is associated with a set of
variables. When the dialog is activated, each dialog item is preset with
the value of its associated variable. If the variable does not exist, TSL
issues the appropriate TQL command to create it or, if the value is not
valid for the dialog item type, a null value is used.
When the OK, Apply or an application defined button is pressed, or the
value of an active dialog item is changed, the variables are set with the
values of the dialog items. These values can be used by the application,
to search for specified data and so on.
A dialog item is created using the DIALOG command:
dialog text(12) testname "Test Name"
This example creates a text field with a 12 character width and a label
of Test Name. Associated with the dialog item is the variable TESTNAME
(which is created if it does not already exist). A text field is simply a
user interface element that allows characters to be typed in from the
keyboard.
The other dialog items are introduced in the next sections.
As with menus, you build up a dialog by specifying the individual
items, and activate the dialog by using the command ASKDIALOG. This
command causes the current dialog to be displayed if it is not already
active, and blocks input from the rest of the application.
Creating a dialog
If the dialog uses only the standard control buttons, OK and Cancel,
either %BUTTONVAL or %DIALOGVAL can be used to control processing
after an ASKDIALOG. If you use application defined buttons or active
dialog items, or set the dialog modes to use different control buttons,
you will probably want to use the %BUTTONVAL variable.
The ASKDIALOG keyword can be followed by a string. This is used as
the window title for the dialog.
The following example shows a simple dialog with one text field.
# Simple Dialog (example5.tsl)
#
title "Simple Dialog"
menu 1 "Dialog"
menu 1-1 "Popup..." action = "Popup"
menu 1-3 "Exit" action = "Exit"
47
Chapter
Dialogs
repeat
askmenu
if %menuval="Popup"
dialog text(12) s "Enter a string"
askdialog "Dialog"
if %dialogval
Cancel Pressed.
endif
endif
until %menuval="Exit"
In this example, the DIALOG command occurs inside the loop and is
executed each time the Popup menu action is selected. When the
DIALOG command is first encountered a new dialog box is created and a
text item is added to it. When the ASKDIALOG command is executed the
dialog is completed, the variable associated with the text item is created
and the dialog is displayed. Subsequently when the DIALOG command is
executed the entire dialog is destroyed and recreated. This destruction
and creation of dialogs can be quite expensive and in this example is
unnecessary. The DIALOG command should be moved outside the loop
(for example, to just after the MENU command). However, there are
some circumstances with more complex dialogs when it is necessary to
create dialogs in the main part of the script.
You can create a dialog with multiple dialog items by executing more
DIALOG commands before the ASKDIALOG command. By default these
items are arranged in the dialog box in two columns, left to right and
top to bottom. The labels are right-aligned and the items are leftaligned. TSL allows you control over the dialog layout but it is normally
easiest to let it choose a layout for you.
In the next example we create a dialog with four dialog items and
introduce three new dialog item types.
# Multiple Item Dialogs (example6.tsl)
#
title "Multiple Item Dialogs"
menu 1 "Dialog"
menu 1-1 "Popup..." action = "Popup"
menu 1-3 "Exit" action = "Exit"
dialog
dialog
dialog
dialog
text(8)
slider
toggle
option
s
h
t
o
"Text field"
"Slider" 1 10
"Toggle"
"Option" "Choice 1" "Choice 2" \
"Choice 3"
repeat
askmenu
if %menuval="Popup"
askdialog
if %dialogval
endif
endif
until %menuval="Exit"
Comments
TEXT
All
data
types
Multiline
Text field
MULTITEXT
string
Slider
SLIDER
short/
long/
byte
Dialog Item
Keyword
Text field
49
Chapter
Dialogs
Dialog Item
Keyword
Data
Types
Comments
Toggle
button
TOGGLE
bool
Option
menu
OPTION
string
Scrolled list
LIST
string
Exclusive
panel
PANEL
string
Calendar
CALENDAR
date
Time range
bar
TIMERANGE
time
Label
LABEL
none
Button
BUTTON
none
Skip
SKIP
none
Text fields
The name of the variable associated with the data item (except for
buttons and labels)
2.
3.
4.
Any attributes
Text fields
Text fields are perhaps the most complicated dialog item since they
allow for the input of any data type, and provide some type conversion
and checking.
51
Chapter
Dialogs
specifies a text field that returns a real number into the variable VOLTS.
While the dialog is displayed, TSL is unable to perform any validation of
data entered into a text field. However, when the dialog is applied, TSL
checks that the value is appropriate for the specified type. If it is not,
the associated variable is set to NULL.
You may sometimes desire to restrict the range of acceptable values for
a text field. You can assign a minimum and maximum acceptable value
by setting the RANGEMIN attribute to the minimum acceptable value and
the RANGEMAX attribute to the maximum acceptable value. For example:
dialog date
rangemin
dialog time
rangemin
dialog real
rangemax
text(8) t1 "aDate" \
= \[1/1/70], rangemax = \[12/31/99]
text(8) t2 "aTime" \
= \[12:00:00]
text(10,14) t3 "aReal" \
= 1490.5
The first text field only accepts a date greater than or equal to January
1st, 1970 and less than or equal to December 31st, 1999. The second
text field sets the minimum acceptable value to be 12:00 but accepts
any time later than that. The final text field accepts any real number up
to and including 1490.5.
Text fields
When the user attempts to apply the dialog, TSL performs range
checking on any text fields that have had RANGEMIN or RANGEMAX
attributes defined. It does this by evaluating the values of these
attributes on the server and comparing them with the value of the text
field. If a value is found to be out of range, TSL displays an error dialog.
You can either define the message in the error dialog by assigning a
value to the RANGE_ERR_MSG attribute, or let TSL generate its own error
message.
53
Chapter
Dialogs
0XOWLOLQH7H[WILHOGV
until %menuval="Exit"
0XOWLOLQH7H[WILHOGV
Multiline text fields are a special case of text fields that can be used to
enter long strings into variables. However, a multiline text field can only
return string data. You can define the number of columns and rows in
the text field by specifying the size, after the keyword MULTITEXT and
in brackets. For example:
dialog multitext(40,4) notes "Notes"
specifies a multiline text field with 40 columns and 4 lines. The user can
enter more than 4 lines, or lines with more than 40 columns, in which
case scroll bars are added.
The maximum size of a string that can be entered in a multiline text
field can be set using the MAXLEN attribute. If this is not defined, the
maximum size of the string entered in the multiline text field is set to be
the maximum size supported by TQL variables (which is currently 4096
characters).
This attribute could be used to ensure that the strings entered in
multiline text items will fit into a column in a table, thus taking away
the need to check the length of the string before attempting to insert it
into a table.
dialog multitext(5,30) notes "Notes" maxlen = 200
55
Chapter
Dialogs
6OLGHUV
A useful alternative to a text field for certain types of numeric input is
the SLIDER. A slider allows the user to select a number in a range by
dragging the slider bar to a value. This input mechanism is usually only
suitable where the range of numeric input is not too large, since it can
be difficult to get sufficiently fine control of the slider with the mouse.
By default, sliders are oriented horizontally but they can be arranged
vertically by using the keyword VSLIDER instead of SLIDER (or
HSLIDER). In addition, the size of the slider in pixels can be specified in
brackets after the keyword. Here are some examples:
dialog slider(100) h "Horizontal Slider" 0 100
dialog vslider v "Vertical Slider" -10 10
The item label is followed by two integer numbers. These are the
minimum and maximum values of the slider respectively. The slider is
guaranteed to return an integer value in that range.
Sliders can use the SENSITIVE attribute to determine whether a user is
able to change the value of the slider.
Sliders can be defined such that a dialog action occurs if you change
the value of the sliderthat is, the slider can be an active dialog item.
This is done using the ACTION attribute. For example:
dialog slider(100) h "Horizontal Slider" 0 100 \
action = "Slider", sensitive = true
7RJJOHEXWWRQV
A very restrictive but very useful dialog item is the toggle button. A
toggle button is a user interface element that only has two valueson
and off. A TOGGLE item always returns a boolean valuethat is, TRUE or
FALSE. Toggle buttons are used to enable or disable specific features of
a report or graph, for example:
dialog toggle plotmean "Plot mean"
2SWLRQ/LVWDQG3DQHO
2SWLRQ/LVWDQG3DQHO
The class of dialog items comprising OPTION, LIST and PANEL, is
particularly useful when the user is constrained to input of one of a set
of values. These items should be used whenever you can enumerate the
allowable set of input values.
Each of these three dialog items returns a string value which is
guaranteed to be one of the specified set, or NULL.
The main difference between these three items is their appearance and
the way the user makes a selection. Another important difference is that
the contents of the list dialog item can be changed while the user is
interacting with the dialog.
The syntax is very similar for all three. After the item label comes a list
of strings. These strings are the set of valid values for this dialog item.
For a list item, the scrolled list is preset with these values; for an option
menu, the pop-up pane is set with these values; for a panel, the
exclusive toggle buttons are labelled with these values. The example
below demonstrates these three items:
# Choice Items (example8.tsl)
#
title "Choice Items"
menu 1 "Dialog"
menu 1-1 "Popup..." action = "Popup"
menu 1-3 "Exit" action = "Exit"
dialog list(3) t "List" "Choice 1" "Choice 2" \
"Choice 3""Choice 4" "Choice 5" "Choice 6"
dialog option o "Option" "Option a" "Option b" \
"Option c"
dialog panel p "Panel" "Either this" "that" \
"or the other"
57
Chapter
Dialogs
repeat
askmenu
if %menuval="Popup"
askdialog
if %dialogval
List value is [t]
Option value is [o]
Panel value is [p]
endif
endif
until %menuval="Exit"
sets the variable o to be the string Option a if a variable did not exist
when the ASKDIALOG command was executed.
It is important to understand the implication of this with choice dialog
items. If the variable is NULL in a list, for example, none of the items in
the list are initially marked as selected. Subsequently, if the user does
not select a value in the list but dismisses the dialog by pressing the 2.
button, the associated variable remains NULLthat is, it will not be set
to one of the items in the choice set. There are ways to deal with this:
first, consider if you can make any useful interpretation of a NULL value
in the variable; if not, you must create the variable and set it to a
suitable value. An example with a list is shown below:
2SWLRQ/LVWDQG3DQHO
In many applications you may want to preset a scrolled list with values
from the database. This is explained in the next section.
The option menu, list and panel dialog items can all have SENSITIVE
and ACTION attributes.
As explained before, the SENSITIVE attribute controls whether the
dialog item can be selected and hence its value modified.
The ACTION attribute causes a dialog action to occur should the value of
the dialog item change. A dialog action also occurs in a list if you
deselect the lists current value.
A list can also use the SCROLLMODE, MINWIDTH and MAXWIDTH attributes.
A list can set its scrollmode to be one of the following values:
Value
Meaning
59
Chapter
Dialogs
Meaning
SINGLE
BROWSE
MULTIPLE
RANGE
DISCONTIGUOUS
For lists that allow multi-selection, the maximum number of items that
may be chosen can be specified using the SELECTION_MAXITEMS
attribute. By default, this is set to the number of items in the list.
The TQL variable associated with the list holds the selected values as a
comma separated list. An alternative list delimiter can be set using the
SELECTION_DELIM attribute. In addition, three system variables hold
information on the items chosen from a multi-select list. These are:
&DOHQGDUV
Note that TQL has an internal limit of 4096 characters as the maximum
length of a string literal. If a user tries to select items that will cause this
limit to be exceeded, a warning message is displayed and the items are
not selected from the list.
The panel, option and list dialog items allow a NULL value to be
returned if the user does not select any item from the dialog item.
However, the ALLOWNULL attribute cannot be set for these itemsthis
attributes primary purpose is to disallow NULL values in text fields.
&DOHQGDUV
The calendar provides an alternative to the text field as a way of
entering a date. It consists of a calendar and two option menus from
which the user can select a month and year. As the user selects a new
month and year, the calendars dates change to reflect the new
selection. The calendar therefore provides the user with useful
reference information when selecting a date. The following example
defines a simple calendar labelled Start Date:
DIALOG CALENDAR start_date "Start Date"
displays a calendar item with the date 1 May 1998 already selected.
A calendar may be an active dialog itemthat is, a dialog action may
occur if you select a new date. This is done using the ACTION attribute.
Calendars may also use the SENSITIVE attribute to determine whether a
user can select a date.
7LPHUDQJHEDUV
The time range bar allows the user to define a number of time ranges
over the course of one day. The item is displayed as a horizontal bar
with 24 points denoting hours in the day. The user defines time ranges
by clicking and dragging the mouse to create one or more blocks on
the bar which represent the ranges. Multiple time ranges can be defined
on one bar but one time range may not overlap another. The following
example defines a simple time range bar labelled Working Hours:
61
Chapter
Dialogs
The item can be displayed with preselected time ranges by setting the
items variable with an array of TQL times.
By default, the lowest time unit the user can use to select a time is 15
minutes. This can be changed with the GRANULARITY attribute which
defines the time unit to be used in minutes. For example:
DIALOG TIMERANGE work_hours "Working Hours" \
GRANULARITY = 5
/DEHOV
The label dialog item does not have any associated data but is used
simply to insert titles or subtitles in columns of the dialog. Note that
you do not use this item to label other dialog items since all dialog
items already have an associated label: use it solely for titles. However,
if the title is likely to change during execution, you should use a readonly text item.
Labels can be either text or iconised. For example:
dialog label "a title"
dialog label icon "printer.bm"
The first command defines a label which uses the string a title and the
second uses the icon which is created from the bitmap file printer.bm.
Labels do not have actions, but non-iconic labels can be greyed out by
setting the SENSITIVE attribute to FALSE. Insensitive iconic labels look
the same as sensitive iconic labels.
$SSOLFDWLRQGHILQHGEXWWRQV
$SSOLFDWLRQGHILQHGEXWWRQV
In a dialog a button is the primary method that is used to initiate a
dialog action. If several actions can be initiated from a dialog, having
one 2. or $SSO\ button may not be sufficient.
You can use application defined buttons to specify application specific
actions or to display other dialogs to further control the application.
Using these buttons and non-dismissing dialogs you can build
sophisticated dialogs with multiple windows and options.
Application defined buttons are placed by default in the application
defined button area. This is situated between the main dialog items and
the control buttons. A separator is drawn after the dialog items.
However, you can use the AREA attribute to instruct TSL to place the
button in the main area with the other dialog items.
Value
Meaning
Buttons must have action strings defined using the ACTION attribute. For
example:
dialog button "Next Row" action = "Next"
If this button is pressed, ASKDIALOG returns and sets the values for
%BUTTONVAL to the string Next and %DIALOGVAL to TRUE. The dialog is
not dismissed but the dialogs variables are updated to take into
account any changes that were made. This is also what happens if the
$SSO\ button is pressed.
If you want the dialog to close when an application-defined button is
pressed, you must explicitly close the dialog using the CLOSEDIALOG
command.
Some actions might require that certain values have been defined or
you might decide that a user does not have the right permission to
perform an action. In this case you could define a SENSITIVE attribute
for the button which evaluates to FALSE when the action cannot be
done.
In the application defined button area, buttons can either have a label
or an icon. Buttons that have icons on them are frequently called iconic
buttons.
63
Chapter
Dialogs
This creates an iconic button using the bitmap print.bm and places a
label Define Printer... to the left of the button. If you try to create a
labelled-iconic button in the application defined button area, the label
is ignored and an iconic button is created.
Application defined buttons may be set to be the dialogs default
button. The default button is the button that is considered to be pressed
when the user presses the return on the keyboard or clicks twice
rapidly on a list. The default button on a dialog is identified by a box
surrounding it. Initially it is set to either 2. or $SSO\ in the control
button area but an application defined button can be made the default
button by putting the keyword DEFAULT after BUTTON, for example:
dialog button default "Next Customer" action = "Next"
3UHVHWWLQJGLDORJLWHPVIURPDGDWDEDVH
In real applications it is very rare that you can create a dialog without
having to retrieve data from a database to preset it. This section
demonstrates some of the techniques you can use to interface the
dialog to the database.
First, consider how to preset a text field in a dialog with a value from
the database. This is straightforward since the text field is associated
with a TQL variable as you have already seen. To preset the text field
all we need to do is assign the correct value from the database to its
associated variable before displaying the dialog.
As an example, suppose we have a table in the database that associates
a parameter number, such as 1221, with a parameter name, such as
3UHVHWWLQJGLDORJLWHPVIURPDGDWDEDVH
The DISPLAY command retrieves the data into the query buffer as the
column PNAME. If the variable PNAME exists, the value of the column is
also assigned to this variable.
Notice that executing the DISPLAY command destroys any data that we
had already retrieved into the query buffer. As we do not really need
the data but just want the variable assignment we can tell the TQL
Server not to return any data, as follows:
declare pname
query set %display false ;
query display paramname as pname from parameters
where param#=pno ;
query set %display true ;
In this example, we actually retrieve the name into the query buffer as
the column PARAMNAME and use text substitution in the DECLARE
command to assign the value.
As another example, suppose you wish to create a slider dialog item
whose minimum and maximum values are the minimum and maximum
values of a column in the database.
query display minimum volts as minvolts,
maximum volts as maxvolts
from results ;
dialog slider volts "Voltage" [minvolts] [maxvolts]
65
Chapter
Dialogs
In this example the minimum value of the column VOLTS is put in the
query buffer as MINVOLTS and the maximum value of the column VOLTS
is put in the query buffer as MAXVOLTS. As in the first example, the
value will also be put in the variables MINVOLTS and MAXVOLTS if they
exist.
The same technique can of course be used to set the choice items in
lists, option menus and panels. However this is normally quite
inconvenient, particularly for lists where a large number of items may
be required. Consequently these items support a special syntax which
allows a choice list to be specified from data in the query buffer.
Instead of a list of strings a single column name can be specified. The
choice set is then taken from data of that name in the current buffer.
For example, suppose table PARAMS contains a list of test parameter
names in the column PARAMNAME that we wish to preset in a scrolled
list.
query display paramname from params ;
dialog list(4) pname "Parameter" paramname
Here we read in the column PARAMNAME into the query buffer and use
these values for the list. Notice how the column name appears as is
and not in square brackets. This tells TSL to get all the values for this
column and to use them for the list values. You may wish to limit how
many items are used in the choice set. This can be achieved by
qualifying the column name with a slash and item limit. For example:
query display paramname from params ;
dialog list(4) pname "Parameter" paramname/12
You can use the same technique to preset the list selection convenience
dialog instead of having to enumerate all the list items. For example:
query display paramname from params ;
select "Parameter" paramname
3UHVHWWLQJGLDORJLWHPVIURPDGDWDEDVH
As usual we have created the dialog outside of the main loop. This is
OK in this example because we dont expect the list of kings in the
database to change as we run the script! However in many other
applications the list may need to be reset. To do this, you can either use
the list editing commands (described later in this chapter) or recreate
the dialog each time it opens.
67
Chapter
Dialogs
'LDORJOD\RXWDQGGHIDXOWSRVLWLRQLQJRIGLDORJLWHPV
So far, all the dialogs have been laid out in two columns with the dialog
items positioned left to right, top to bottom. The labels and labelled or
iconic buttons are aligned on their right-hand edge and the items
themselves are aligned on the left-hand edge. This is the default layout
strategy and is configured in the application default file.
It is possible to change the layout of dialogs and define where to
position each dialog item in the dialogs main area. If you do not define
a position for a dialog item, TSL determines the items default position
based on the following dialog layout attributes.
The default values for these attributes can be found in the TSL
application defaults file, $TSL_CLIENT_DIR/appdefs/Tsl. See X
Resources and the Applications defaults file on page 161 for a complete
description of how these values can be changed. If the resources
corresponding to these attributes are not defined, the following internal
defaults are used:
COLUMNS = 2
ALIGNITEMS = TRUE
ALIGNCOLUMNS = TRUE
ALIGNROWS = TRUE
BUTTONCOLUMNS = 1
BUTTONLAYOUT = COLUMNCENTRE
'LDORJOD\RXWDQGGHIDXOWSRVLWLRQLQJRIGLDORJLWHPV
The values of these attributes can be changed using the DIALOG LAYOUT
command. For example:
dialog layout columns=3 alignrows=false
This command would set the number of columns to 3 and disable row
alignment.
In most situations the only useful one to change is the number of
columns. The example script below allows you to see the effect in
dialog layout of changing these parameters.
# Dialog Layout (example10.tsl)
#
title "Dialog Layout"
menu 1 "Dialog"
menu 1-1 "Set Layout..." action = "Layout"
menu 1-2 "Popup..." action = "Popup"
menu 1-4 "Exit" action = "Exit"
declare
declare
declare
declare
ncols 2
aitems true
acols true
arows true
repeat
askmenu
switch %menuval
case "Layout"
# Construct a dialog to set the layout
#
dialog layout columns=2 alignrows=true \
alignitems=true aligncolumns=true
dialog slider ncols "No. of Columns" 1 4
dialog skip(1)
dialog toggle aitems "Align Items"
dialog toggle arows "Align Rows"
dialog toggle acols "Align Columns"
askdialog "Layout"
if %dialogval
dialog layout
dialog layout
dialog layout
dialog layout
columns = [ncols]
alignitems = [aitems
alignrows = [arows]
aligncols = [acols]
69
Chapter
Dialogs
endif
case "Popup"
dialog text(12) s "Text field"
dialog list(2) aList "List" \
"Item 1" "Item 2" "Item 3"
dialog panel p "Panel" "Choice 1" "Choice 2"
dialog toggle t "Toggle"
askdialog "Example"
endswitch
until %menuval="Exit"
Quite often the layout of a dialog is spoilt because of the way that items
are always inserted left to right, top to bottom. You can cause TSL to
skip a number of positions in its allocation of items using the DIALOG
SKIP command. For example:
dialog skip(2)
'HILQLQJWKHSRVLWLRQRIGLDORJLWHPV
You might decide to position dialog items located in the dialogs main
area yourself rather than use the default position described in the
previous section.
The size of a dialogs main area defaults to the minimum size that
would accommodate all the dialogs items assuming that they use their
default position. However, if you decide to define the position of each
item, you might find that the default size of the dialog is either too
small or too big. The dialog layout attributes WIDTH and HEIGHT define
the size of a dialogs main area. The value assigned to these attributes
must be a dimension unit as defined in Chapter 2, but grid units are not
allowed. The WIDTH and HEIGHT attributes are defined using the DIALOG
LAYOUT command, for example:
dialog layout width = 15c, height = 9c
'HILQLQJWKHSRVLWLRQRIGLDORJLWHPV
the dialogs main area. You can change this using the GRID attribute, for
example:
dialog layout grid = 10x5
This defines a grid with 10 grid units along the top and 5 grid units
down the side of the dialogs main area. Notice that there are no spaces
on either side of the x. The size of a grid unit along the x-axisthat is,
along the topis determined by dividing the width of the dialogs main
area by the number of grid units across the top. Similarly the size of a
grid unit along the y-axisthat is, down the side of the dialogs main
areais determined by dividing the height of the dialogs main area by
the number of grid units down the side. For example:
dialog layout width = 15c, height = 10c, grid = 10x5
This defines the size of a grid unit along the x-axis to be 1.5 centimetres
and the size of a grid unit along the y-axis to be 2 centimetres.
The position of a dialog item can be defined using the dialog items
XPOS, YPOS, XORIGIN, YORIGIN, XADJUST, YADJUST and LABELGAP
attributes.
The XPOS and YPOS attributes are used to define the position of the
dialog items origin. These are defined as dimension types and grid
units are allowed.
The XORIGIN and YORIGIN define the origin of a dialog item. The value
for XORIGIN must be one of LEFT, RIGHT, CENTRE or CENTER and
71
Chapter
Dialogs
defaults to CENTRE, and the value for YORIGIN must be one of TOP,
BOTTOM, CENTRE or CENTER and defaults to TOP.
TOP
CENTRE
BOTTOM
LEFT
CENTRE
RIGHT
TOP
BOTTOM
CENTRE
LEFT
CENTRE RIGHT
Figure 15. The possible origins of a complex and simple dialog items
Dialog items can consist of either two components or one component,
depending on whether they have a label or not. The XORIGIN attribute
has a different meaning for CENTRE depending on whether a dialog item
has one or two components. For complex dialog itemsthose with two
componentsthe centre is the left side of the component that is not a
label. For simple dialog items with one componentthat is, labels and
labelled or iconised buttonsthe centre is the middle of the dialog
item.
# Positioning dialog items (example11.tsl)
#
menu 1 "Database"
menu 1-1 "Popup..." action = "Popup"
menu 1-3 "Exit" action = "Exit"
dialog layout width = 5i, height = 1.5i
dialog text(7) partno "Part #" \
xpos = 1i, ypos = 0i, \
xorigin = centre, yorigin = top
dialog button default "Update Part" \
action = "Update", area = 1 \
'HILQLQJWKHSRVLWLRQRIGLDORJLWHPV
= top
\
= top
"Description" \
= top
repeat
askmenu
if %menuval = "Popup"
askdialog "Edit machine parts"
endif
until %menuval = "Exit"
73
Chapter
Dialogs
&KDQJLQJWKHFRQWUROEXWWRQV
As you have already seen, user dialogs are by default created with the
standard control buttons: 2., &DQFHO and +HOS. This configuration
provides the simplest model for managing dialogs: if a button is
pressed, the dialog is dismissed and if it was the 2. button, the
associated variables are set. TSL supports a number of other control
button configurations whose primary purpose is to allow a dialog to be
processed by the user and applied but then remain on the screen while
the application continues processing. When the dialog is reactivated the
user can enter new values and submit the dialog again. Such a dialog is
much more convenient to use in many applications, for example when
implementing simple data entry screens or graphic control panels.
You can change the dialogs control buttons by using the DIALOG
LAYOUT command and setting the MODE attribute. You can only execute
this command before you create any dialog items and before executing
the ASKDIALOG command. The parameter is set to one of the following
values:
Value
Description
&ORVH.
&KDQJLQJWKHFRQWUROEXWWRQV
You can change the default control buttons in the entire application by
setting the resource Tsl.defaultMode to be a value between 1 and 5.
See X Resources and the Applications defaults file on page 161 for a
complete description of how this value can be changed.
Returning briefly to the subject of default buttons, introduced when
application defined buttons were defined, each of the modes except
mode 3 defines a default action which is used if you do not define an
application defined button to be the default. For mode 0 and 1 this is
the 2. button and for modes 2, 4 and 5 this is the $SSO\ button.
The special variable %BUTTONVAL shows which button has been pressed
(or, more generally, the ACTION string of whichever dialog item was
activated). For the standard control buttons this variable is set to the
name of the button as described in the table below.
Button
Value of
%BUTTONVAL
Value of
%DIALOGVAL
2.
"OK"
TRUE
Variables changed;
dialog dismissed.
$SSO\
"Apply"
TRUE
Variables changed;
dialog not dismissed.
&DQFHO
"Cancel"
FALSE
Variables unchanged;
dialog dismissed.
5HVHW
"Reset"
FALSE
Variables unchanged;
dialog not dismissed.
&ORVH
"Close"
FALSE
Variables unchanged;
dialog dismissed.
Notes
75
Chapter
Dialogs
&KDQJLQJWKHFRQWUROEXWWRQV
dialog
dialog
dialog
dialog
dialog
dialog
button
button
button
button
button
button
77
Chapter
Dialogs
switch %buttonval
case "First"
query fetch first from rslt ;
case "Last"
query fetch last from rslt ;
case "Next"
query fetch next from rslt ;
if not %qok
error "At end of table"
endif
case "Prev"
query fetch previous from rslt ;
if not %qok
error "At start of table"
endif
case "Delete"
confirm "Delete [vfullname]?" \
"Yes, Delete" "No"
if %confirmval
query delete current from rslt ;
query fetch current from rslt ;
endif
case "Add"
query insert vfullname as fullname,
vhouse as house,
vaccessn as accessn
to rslt ;
query fetch from rslt
where fullname=vfullname ;
endswitch
set vfullname "[fullname]", \
vhouse "[house]", vaccessn [accessn]
until %buttonval="Close" or %buttonval="Cancel"
endif
0DQDJLQJPXOWLSOHGLDORJV
until %menuval="Exit"
query close ;
Notice how the script checks for the &DQFHO button being pressed even
though no button is defined on the dialog. This is needed because
closing the dialog using the window manager always returns &DQFHO.
The ABORT command and the variable %QOK which were used in the
above example are described in the section Error handling on page
156.
0DQDJLQJPXOWLSOHGLDORJV
Most applications require you to create more than one dialog. There are
two ways of managing this in your application: either you create each
dialog every time it is to be used, or you can use the features described
in this section to manage multiple dialogs.
To manage multiple dialogs properly you need to understand how
dialogs are created. TSL has a notion of the current dialog. All DIALOG
commands apply to the current dialogthat is, they add items to it, or
change the layout. When an ASKDIALOG command is executed the
current dialog is completed and displayed. Subsequently, any DIALOG
command will cause the current dialog to be destroyed.
What is required is a way of telling TSL that the following DIALOG
commands apply to a new dialogthat is, to change the current dialog.
The SETDIALOG command does just that. By default, the command
supports up to 200 dialogs but this limit may be changed using the
maxDialogs application resource. Every dialog specified with the
SETDIALOG command must be identified by a number or a name which
indicates the dialog to set as current. For example:
setdialog 1
or:
setdialog print_options
Note that when you identify a dialog by a name, you specify the name
as an unquoted string.
To create multiple dialogs you set the current dialog to a dialog name
or number, execute DIALOG commands to create that, set the current
dialog to another name or number and create that, and so on. When
your application needs to display a dialog with the ASKDIALOG
79
Chapter
Dialogs
command you must follow the command with the dialog name or
number you wish to display. For example:
askdialog 1 "Print Options"
The following example script creates three dialogs and opens them
from the menu. It uses numbers to identify dialogs.
# Multiple Dialogs (example13.tsl)
#
title "Multiple Dialogs"
menu 1 "Dialog"
menu 1-1 "Popup
menu 1-2 "Popup
menu 1-3 "Popup
menu 1-5 "Exit"
setdialog 1
dialog layout columns=1
dialog text(10) t1 "Text 1"
dialog text(10) t2 "Text 2"
setdialog 2
dialog layout
dialog toggle
dialog toggle
dialog toggle
dialog toggle
columns=2
b1 "Button
b2 "Button
b3 "Button
b4 "Button
1"
2"
3"
4"
setdialog 3
dialog list(2) "List" "Item1" "Item2" "Item3"
repeat
askmenu
switch %menuval
case "Popup 1"
askdialog 1
case "Popup 2"
askdialog 2
&KDQJLQJWKHFRQWHQWVRIDOLVW
&KDQJLQJWKHFRQWHQWVRIDOLVW
The list dialog item is used to select a string from a collection of
stringsfor example, to select a customer name from a set of
customers. During the execution you might find that customers are
either added to or removed from the system. As a result you must
update the list of customers so that it provides an accurate
representation of the systems current state.
TSL provides two mechanisms that allow you to change the contents of
a list dialog item. The first is to recreate the entire dialog by rebuilding
it. This is very time-consuming and slows down the application if it is
done frequently.
The second mechanism is through the use of list editing commands.
These can only be used on dialog list items in the current dialog and
the dialog must have been created beforein other words, an
ASKDIALOG command must have been performed on the dialog.
The list to be modified is identified by the variable in which the
selected item is to be stored, for example:
dialog list(10) cust "Customers" customer
81
Chapter
Dialogs
7KH,16(57OLVWHGLWLQJFRPPDQG
The insert command is used to insert one or more values into a list. As
mentioned above, the values are defined in the same way as the initial
values for list, option menu and panels. Therefore, you can either give a
list of strings or take values from the query buffer, for example:
query display fullname from kings ;
dialog list names insert 5 fullname
This inserts into the list identified by the variable names, starting at
position 5, the contents of the column fullname.
dialog list cust insert 4 "Customer 4" "Customer 5"
This command inserts the values Customer 4 and Customer 5 into the
list starting at position 4that is, at positions 4 and 5.
If the position is 0 or is greater than the number of items in the list, the
given values are appended to the end of the list. An error is returned if
the position is less than 0.
The values in the list which occur at or after the starting position are
moved down to make room for the new items.
7KH'(/(7(OLVWHGLWLQJFRPPDQG
The delete command is used to delete one or more items from a list. If
the number of items to be deleted is not specified, only one item is
deleted. For example:
dialog list cust delete 4 5
dialog list cust delete "Customer 2" 3
7KH5(3/$&(OLVWHGLWLQJFRPPDQG
The first command deletes five items starting from the fourth position of
the list identified by the variable cust.
The second command deletes three items from the list starting at the
first occurrence of the string Customer 2.
The final command deletes the second item from the list.
7KH5(3/$&(OLVWHGLWLQJFRPPDQG
The REPLACE command is used to replace a number of values in a list
starting at a given position with the given values. If the number of
values to be replaced is not given, it is assumed to be the same as the
number of values being inserted into the list.
For example:
dialog list names replace "Customer 2" "new Customer 2"
dialog list names replace 1 fullname
dialog list names replace "Customer 5" 2 \
"new Customer 5" "Customer 6" "Customer 7"
7KH$33(1'OLVWHGLWLQJFRPPDQG
The APPEND command is used to add values to the end of a list. If used
after a CLEAR command, the entire list is changed to the new values.
The APPEND command does not need to be given a position. Therefore
no errors can occur so %LISTOK is always set to TRUE after an APPEND.
As in the case of the INSERT and REPLACE commands the values
inserted into the list can either be given as a list of strings or as a
column name from the query buffer. For example:
dialog list names append fullname
83
Chapter
Dialogs
The first command appends the contents of the column fullname to the
end of the list identified by the variable names.
The second command appends the values Customer 1 and Customer
2 to the end of the list identified by the variable cust.
7KH&/($5OLVWHGLWLQJFRPPDQG
The clear command empties a list. It takes no parameters. For example:
dialog list names clear
This clears the list identified by the variable names. No errors can
occur when using this list manipulation command, so %LISTOK is
always set to TRUE after a CLEAR.
([DPSOH
This example shows how the list editing commands could be used to
select a number of items upon which an action is performed. In this
case a copy of the KINGS table is made and the selected items are
deleted from this copy.
Clicking on an item in the list labelled Kings to keep moves the item to
the list Kings to delete and vice versa. The temporary table TMP
contains an up-to-date image of the kings in the list Kings to delete. If
the user selects the 'HOHWH.LQJVbutton, the user is asked for
confirmation and, each king in TMP is deleted from RSLT.
# List editing commands (example14.tsl)
#
query open kings ;
# Create a copy of the KINGS table.
query select * from kings ;
# Create dialog
dialog layout mode = 3
query display fullname ;
dialog list(10) origlist "Kings to keep" fullname \
action = "MoveToDelete", \
scrollmode = 2, minwidth = 15
([DPSOH
85
Chapter
Dialogs
When the end of the TMP table is reached a query error will occur when
attempts are made to fetch the next row of the table. Thus the repeat
loop is told to halt when the special variable %QOK is set to FALSE
(which happens when an error is detected in a query). The ABORT
command and the variable %QOK are described more fully in Error
handling on page 156.
The %ROWS variable used in the above code is a special variable which
is set to the number of rows put in the query buffer by the last query
that affected the query buffer. This variable and the query buffer are
described in the next chapter.
8VLQJWKH6(16,7,9(DWWULEXWHLQDGLDORJ
For some of the dialogs you create there may be certain fields that are
only available when certain conditions are met. For example, if you
create a dialog that defines where to print a report you might use a
toggle to control the availability of a text field in which the user can
specify the file to print to. When the toggle is off, the report is printed
8VLQJWKH6(16,7,9(DWWULEXWHLQDGLDORJ
to TSLs main window and the text field is not available. When the
toggle is on, the text field is available and the report is printed to the
specified file.
In this example, the text field is only used if the toggle button has been
pressed. If the toggle is created using the following command:
dialog toggle tofile "Output to file?"
we can see that by setting the text fields SENSITIVE attribute to the
variable TOFILE, which is created/set by the toggle, if the toggle is on
that is, TOFILE is TRUEthe text field will be sensitive. If the toggle is
offTOFILE is FALSEthe text field will be desensitised.
This solves part of the problem. The sensitivity of the text field is set to
the value of the toggle whenever an ASKDIALOG is executed. To ensure
that the text fields sensitivity is updated each time the toggles value is
changed, we must define an action for the toggle. When an action is
defined, ASKDIALOG is executed each time the toggles value is changed
so the text fields sensitivity is updated accordingly.
A snapshot of the resulting code is:
dialog toggle tofile "Output to file?"\
action = "OutputChanged"
dialog text(20) filename "Filename:" \
sensitive = tofile
repeat
askdialog
until %buttonval = "OK" or %buttonval = "Cancel"
87
Chapter
This brief chapter tells you about the query buffer and
the commands you can use to move forward and
backward to examine the data in it.
89
Chapter
1DYLJDWLQJWKHTXHU\EXIIHU
Any data retrieved by a TQL command is returned in the query buffer.
This buffer is a large area of memory which is shared by the TSL
interpreter and the TQL Server. When a query is executed, the TQL
Server copies the data into the buffer so that it becomes available to
your application. Although the server provides a mechanism for
returning more than one buffers worth of data, TSL cannot make use of
this facility. Consequently, the results of a single query must fit in the
buffer.
A query may retrieve more than one row of data from the database and
so TSL has a notion of the current position in the query buffer. When
text substitution is performed on a column name, TSL looks at the row
of data at the current position to find the specified column. The
contents of the query buffer are maintained until another query is
executed that returns some data. (The TQL RUN command can also
cause the buffer to be lost.) You can create variables and perform
SELECT queries without damaging the query buffer; but a DISPLAY
command or an aggregation overwrites the contents of the query buffer.
When a query that causes data to be written to the query buffer is
executed a special variable, %ROWS, is set to be the number of rows of
data read into the query buffer.
After a query is executed, the buffer position is set to the first row in
the buffer. Subsequently, the buffer position can be changed using the
following TSL commands: FIRST, LAST, NEXT and PREV. For example:
query display exp#, volts from results ;
'First row, experiment number [exp#] voltage is [volts]
next
'Second row, experiment number [exp#] voltage is [volts]
last
'Last row, experiment number [exp#] voltage is [volts]
The NEXT command moves the current position to the next row in the
buffer; the PREV command moves the current position to the previous
row in the buffer; the FIRST command moves the current position to
the first row in the buffer; and the LAST command moves the current
position to the last row in the buffer.
Most applications use the query buffer in only two ways. Either the
query only returns one rowfor example, when retrieving the
maximum value of a column in a tableor the query returns multiple
rows and the entire buffer is used to print a report. The first of these
1DYLJDWLQJWKHTXHU\EXIIHU
usages we have already seen in this guide, the latter requires the use of
a special form of the REPEAT command. For example:
query display exp#, volts from results ;
repeat
' Experiment [exp#] Voltage [volts]
next
forall
When using the REPEAT FORALL commands you must take care that
the loop contains a NEXT or a PREV command. If it does not, the loop
will never terminate.
Another form of the REPEAT command can be used to place a limit on
the number of iterations, for example:
query display exp#, volts from results ;
repeat
' Experiment [exp#] Voltage [volts]
next
for 40
In this example, the loop iterates until either the end of the buffer is
reached or until 40 iterations have been made. Therefore, a maximum
of 40 rows will be printed.
As you can see, managing the query buffer and iterating through it is
straightforward. The techniques described above form the basis of
report writing in TSL, which is covered in the next chapter.
91
Chapter
prints the first value stored in the query buffer for the column
fullname. Similarly:
query display fullname as names from kings ;
first
' [names]
prints the first value stored in the query buffer for the column names.
If a variable exists that has the same name as a column in the query
buffer, the query also assigns a value to the variable. This is the value of
the column in the last row written in the query buffer.
For example, assuming that a variable NAMES is defined, the query:
query display fullname as names from kings
where kingno < 10 ;
and sets the NAMES variable to Egbert. Text expansion of the column
NAMES returns the value Edmund I
Thus it can be seen how the value of NAMES and [NAMES] are different.
When the query buffer is navigated using the FIRST, LAST, NEXT and
PREV commands the value returned by [NAMES] changes but the value
of the variable NAMES does not change.
This can cause confusion as illustrated by the following TSL script.
# A confusing report
declare names, x
query open kings ;
query display fullname as names from kings ;
first
repeat
set x names
' [x]
next
forall
This does not generate a report with the name of each king in the
KINGS table as might be expected when you look at this code. Instead it
displays the name of the last monarch 62 times (the number of rows in
the query buffer) because it is using the variable NAMES instead of the
column of the same name in the query buffer.
Text substitution must be used to access columns in the query buffer. It
always looks for a column in the query buffer first before checking for a
variable of the given name. To avoid the possibility of confusion it is
strongly recommended that you never create a variable with the same
name as a column.
The following scripts work correctly, but the second is more efficient
because it avoids the use of variables altogether.
# A working report
declare names, x
query open kings ;
query display fullname as names from kings ;
first
repeat
set x "[names]"
' [x]
93
Chapter
next
forall
# A more efficient report
query open kings ;
query display fullname as names from kings ;
first
repeat
' [names]
next
forall
Chapter
Reports
6
Reports
95
Chapter
Reports
Formatted reports
An important part of most applications is the production of reports from
the database. The reports may take many forms, ranging from simple
printouts of raw data to complex statistical reports that require
substantial data manipulation by the TQL Server. As you have seen, TSL
provides a powerful means of data manipulation and retrieval using the
QUERY command and a simple but flexible way of printing text and data
items. Combining these two features with some additional commands to
control page layout produces a flexible but straightforward report
writing environment.
More sophisticated reports can be created using the PRINT and PRINTLN
commands. These commands allow you to specify either the type of
data to be printed (type dependent) or let TSL determine the type (type
independent). In addition, the PRINT and PRINTLN commands allow
you to specify the field length and fraction length of the data to be
printed.
You can define pagestyles which determine a pages headers, footers,
where to start and stop printing, the pages margins and the length of a
page using the PAGESTYLE command, and define reports in terms of
these pagestyles using the REPORT command.
In addition, you can define the output to go to either a printer, pipe or
file and define logical printers using the PRINTER command.
Voltage
23.45
25.42
22.12
22.15
25.45
24.62
23.84
24.28
The real numbers are not lined up with the column title, even
though the text item in the input file is lined up with the title
The real numbers are not in a fixed positionthey move across the
line depending on the size of the number printed before in the first
column
97
Chapter
Reports
Now the values of the text items are lined up, the columns are equally
separated and the numbers are right-justified. (Notice that the actual
digits do not appear exactly at the position of the text item in the input.
This is because the numbers are being printed right justified in a field
length such that there are leading spaces.)
If table expansion is disabled (the default), when a text item is
encountered it is evaluated and all leading and trailing spaces are
removed. The result is inserted in the output line. Consequently,
subsequent text and text items may be shifted to the left or right
depending on the actual length of the value. As you will see, this type
of text item expansion is used for embedding data in more free format
reports.
If table expansion is enabled (by TABLE ON), when a text item is
encountered it is evaluated and formatted into a field whose field and
fraction length are determined by the TQL Server. The field is then
written into the output line at the same column position as the text item
appeared in the input line (relative to the '). Consequently, subsequent
text and text items are guaranteed to appear in fixed positions. This is
the behaviour that is required for most types of report.
Note that because all data, whether variables or columns, ultimately
resides in the TQL Server, it is the TQL notion of field length and
fraction length that is used when formatting the value. For example, if
the text item is a column name (as in the examples above), the data is
formatted according to the column definition in the database. Similarly,
for every variable, TQL has a defined field length and fraction length
that was determined from the last value that was assigned to the
variable.
This method generally works well for formatting reports as it means you
can control the layout by simply positioning text in the input filethe
file becomes a sort of template for the finished report. There are,
however, a number of things to be wary of. First, if a text item expands
to be much larger than the text item in the input file, it may be clipped
by the expansion of subsequent text items. Similarly, if the text item
itself is very long, it may not be possible to position subsequent items
as close as may be desired.
Here are two examples of these problems.
Suppose that descript is a variable containing the string Intake
Muffler Fitted and that result is a real variable with value 1.23
then:
produces:
Intake Muffle1.23
Notice that the description field is clipped by the following text item.
The second problem is exhibited in the example below where one may
wish the second value to be more closely aligned to the first item.
' [mean(sqrt(vara))/n+1] [v]
Bold
@U
Underlined
@E
Emphasised
@1
User enhancement 1
@2
User enhancement 2
The following example shows the code for a report that demonstrates a
number of the features described above (you need a KINGS database to
run this script).
# Example Report (example15.tsl)
#
title "Example Report"
query open kings ;
menu 1 "Report"
menu 1-1 "On Royal House..." action = "Royal"
menu 1-3 "Exit" action = "Exit"
repeat
askmenu
99
Chapter
Reports
if %menuval="Royal"
dialog text(10) h "Royal House"
askdialog
if %dialogval
'
' @BReport on Royal House of [h]@B
'
query display fullname, title, accessn, until
from kings where upc(house)=upc(h) ;
' Name
Title
Ruled From Until
if %rows=0
error "[h] is not a Royal House"
else
table on
repeat
' [fullname]
[title]
[accessn]
[until]
next
forall
table off
endif
endif
endif
until %menuval="Exit"
endif
next
forall
table off
The second form takes a sequence of data items and format strings and
prints the data in the specified format. The data item and format strings
are separated by two colons, ::. For example:
println testno::"%4v", voltage::"%8.3v"
The formatting string and colons may be omitted in which case the data
item is formatted using the default field length and fraction length
returned by the TQL Server when the data item is evaluatedfor
example, if the item is a column, this will be the columns field and
fraction length.
The data item can be one of the following:
An expression
The format string defines how the data item is to be printed and can
also include annotative characters such as leading and trailing
characters for units. The string must contain at least one format
101
Chapter
Reports
An optional decimal point which separates the field width from the
next digit string.
Real (decimal) number in the style #.####e## (scientific notation), where one digit appears before the
decimal point and the number of digits after the decimal point is the fraction length. The format character E can be used to obtain an upper case E. The
data type should be shortreal or real.
Character.
String.
103
Chapter
Reports
The real component of the complex number is formatted using the same rules as the f format character.
The imaginary part of the complex number is formatted using the same rules of the f format character.
If the data item is a date or time, the following characters can be used:
a
Format strings may also contain the enhancements @B, @U, @E, @1 and
@2. For example:
println mnth::"@UVariance Report for month %2v@U"
105
Chapter
Reports
Text substitution is performed on the format string before the data item
is evaluated. As such the enhancements for a particular line of text
could be stored in a variable, for example:
declare enh "@U"
println mnth::"[enh]Variance Report for month %2v[enh]"
would underline the line Variance Report for month %2v. In this way
users would be able to dynamically change the appearance of a report
by changing the value of the variable ENH.
The command above indicates that a page break should occur after 60
lines. (The initial default page length is 65 lines.)
The default left and right margins can also be controlled using the
MARGIN command. For example, assume that there are 80 columns
(numbered from 1 to 80). Then:
margin 2,78
sets the default left margin to be 1 column wide (that is, the text starts
in column position 2), and the default right margin to be 2 columns
wide (that is, the text finishes in column 78). The default values of the
left and right margins are 4 and 76. However, if the width of the main
window is changed (for example, in the X configuration file), the right
margin defaults to 4 columns in from the right-hand side.
progress messages you can of course use them to print data from the
database. For example:
query display average volts as avolts,
variance volts as vvolts
from results ;
Average of Voltage = [avolts]
Variance of Voltage = [vvolts]
might produce:
In the last 20
days there have been a total of 53 defects
in the process. The mean
flow rate was 1200.45 m3/hr.
By default, TSL produces a ragged right marginthat is, the text may
not flow exactly up to the right margin of the page. If you want a
justified right margin, you can use the JUSTIFY command:
justify on
107
Chapter
Reports
This type of free format data reporting is usually used only for reporting
on small amounts of data or for printing summary paragraphs before or
after longer, more structured reports.
When mixing the two types of report note that filling and justification
are automatically disabled when table mode is enabled (using the
TABLE command). When table mode is subsequently disabled, the
previous settings for JUSTIFY and FILL are restored.
Defining reports
TSL can print headers and footers for you at the beginning and the end
of a page, and allows you to configure the pages of report to have
different formats from each other. You can do this by defining a report
that consists of several pagestyles, where a pagestyle defines the
attributes of a page such as its header, footer and where to start and
end printing.
Pagestyles
TSL allows you to have up to thirty different pagestyles defined at any
one time while the application is running. The PAGESTYLE command is
used to define the attributes of the current pagestyle and the
SETPAGESTYLE command is used for changing the current pagestyle,
For example:
setpagestyle 12
pagestyle length = 40
Reports
defined, TSL starts to print the header on the line defined by the
HEADLINE attribute. Similarly if a FOOTER attribute is defined, TSL starts
to print the footer on the line defined by the FOOTLINE attribute.
The HEADER and FOOTER must be given a quoted string value. The
contents of the quoted string are passed to a PRINTLN command when a
header or footer is printed so the format of the contents of the quoted
string must be a format accepted by the PRINTLN command. For
example:
pagestyle headline = 1, footline = 60, \
header = 'reportNo::"This is report# %-2v"', \
footer = '" - End of page -"'
Notice how you need to use different quotes to surround the header
and footer definition and for defining the text to be printed.
The LENGTH attribute defines the number of lines that can fit on a page.
If this attribute is not defined, TSL uses the default length, as defined by
the LENGTH command or the initial default of 65 lines.
The LMARGIN attribute defines the column number at which to start
printing. This attribute defaults to the default left margin, as defined by
the MARGIN command or to 4.
Finally, the RMARGIN attribute defines the column number at which to
stop printing each line. This attribute defaults to the default right
margin, as defined by the MARGIN command, or to 78.
If the STARTLINE is not defined it defaults to line 2 and if ENDLINE is
not defined it defaults to the length of the page.
The attributes HEADER, FOOTER, FOOTLINE and FOOTER have no default
values and must be defined if they are to be used.
Reports
TSL allows you to have up to thirty report styles defined at any one
time. A report defines which pagestyles are to be used on which page.
The current report is defined using the REPORT command.
The pagestyles to use on each page of a report are defined using the
FIRST, LEFT, RIGHT and DEFAULT attributes.
The FIRST attribute defines the pagestyle to use on the first page of a
report, the LEFT attribute defines the pagestyle to use on even pages
and the RIGHT attribute defines the pagestyle to use on odd pages. The
109
Chapter
Reports
DEFAULT attribute defines the pagestyle to use on pages which have not
been assigned a pagestyle.
This defines the current report to be report number 10 and defines the
report to use pagestyle 12 on all pages.
The REPORT ON command is used to start using the current report style.
When a report is started the special variable %PAGENUM is created and
set to 1. This variable can be used in the HEADER and FOOTER attributes
of a pagestyle to print the current page number. TSL also sets the
current working pagestyle to be the pagestyle to use for the first page
of the report. Note, the current working pagestyle is not the same as the
current pagestyle. The current working pagestyle defines the pagestyle
to use for the page that is currently been printed while the current
pagestyle defines the pagestyle that would be modified by a PAGESTYLE
command.
Before printing the first line of text, TSL checks the current working
pagestyle to see if a header has been defined. If it has it goes to
HEADLINE and prints the HEADER. It then goes down to STARTLINE and
prints the text until it reaches ENDLINE. If more text is printed, TSL
checks to see if a footer has been defined. If a footer is defined, TSL
goes down to FOOTLINE and prints the FOOTER, and goes to LENGTH. It
then increments %PAGENUM and calculates the new current working
pagestyle and determines whether it should print a header. This process
is repeated until the report is finished using the REPORT OFF command.
The REPORT OFF command simply skips to the end of the page, prints a
footer (if required) and drops the %PAGENUM variable.
This defines the current printer to be printer 10 and defines that printer
to be the file /tmp/report1. The PRINTER command accepts four
attributes: OUTPUT, FILENAME, COMMAND and APPEND
The OUTPUT attribute defines which type of logical printer is to be used.
This can be one of FILE, PRINTER or PIPE. Based on this attribute TSL
determines whether to use the FILENAME attribute or the COMMAND
attribute.
If the OUTPUT attribute is set to FILE, TSL looks at the FILENAME
attribute to determine which file to put output in. When TSL first
accesses a file it can either overwrite the contents or append to the end
of the file. The APPEND attribute is used to define this behaviour; by
default its value is FALSE, so the file is overwritten. You should set the
value to TRUE if you would like to APPEND to the end of the file.
If the OUTPUT attribute is set to PRINTER or PIPE, TSL looks at the
COMMAND attribute to determine which command it should pipe the
command through.
So far we have only printed reports to the screen. To print a report to a
current printer you use the PRINTER ON command.
This command redirects all TSL output from the main window to the
current printer. All text that would normally be printed in the main
window is printed on the printer. Output can be restored to the screen
using:
PRINTER OFF
If the printer is a UNIX spooler (such as lp), the action of disabling the
printer causes the spool file to be closed and printing to begin.
The default logical printer, printer 1, is initialised by TSL using
command line arguments. The command used by TSL for spooling
output to the system printer is determined by the setting of the
printCommand application resource. For further information on
specifying logical printers refer to Chapter 8 (Miscellaneous Topics) and
to the Reference section of this manual.
The following example demonstrates how a panel on a dialog can be
used to control the report output.
# Example Report with Printing (example16.tsl)
#
title "Example Report"
query open kings ;
111
Chapter
Reports
Name
Title
Ruled From
Until
if %rows=0
error "[family] is not a Royal House"
else
table on
repeat
[fullname]
[title]
next
forall
table off
endif
endproc
[accessn]
[until]
repeat
askmenu
if %menuval="Royal"
repeat
askdialog
if %buttonval = "OK"
if outto <> "to Screen"
setprinter 1
if outto="to File" and fname<>""
printer output = file, \
filename = "[fname]"
elif outto="to Printer" and fname<>""
printer output = printer, \
command = "[fname]"
endif
printer on
endif
call report_on_house( h )
if outto <> "to Screen"
printer off
endif
endif
until not %buttonval <> "Destination Changed"
endif
until %menuval="Exit"
query close kings ;
In this example, the dialog closes once the user has selected a value to
report on and a destination to print to and the report is generated.
Every time the user opens the dialog and selects a value and output, a
new report is generated even if the user chooses to report on the same
value each time. This may be acceptable if the report is short and takes
only a moment to generate. However, for long reports regeneration may
take some time. In addition, if the user has only changed the output
destination and not the information on which to report, regeneration
may seem unnecessary.
An alternative is to maintain the dialog so that the user can adjust the
reports contents and destination and to copy the information that is
sent to screen to a buffer file. This file then holds a copy of the report
113
Chapter
Reports
sets the current logical buffer to 12 and defines the filename associated
with it as /tmp/buff12. The file will be overwritten when the file is
opened for the first time.
Output to the current buffer file is activated by a BUFFER ON command
and continues until a BUFFER OFF is executed.
The %DLOGCHANGED system variable indicates whether any of the values
in the current dialog have been changed. It therefore provides a way of
checking whether a report must be regenerated before printing.
Title
Ruled From
Until
if %rows=0
error "[family] is not a Royal House"
set rep_to_prn FALSE
115
Chapter
Reports
else
table on
repeat
'[fullname]
[title]
[accessn]
[until]
next
forall
table off
# Set a flag to say we produced a report
set rep_to_prn TRUE
endif
buffer off
endproc
repeat
askmenu
if %menuval="Royal"
repeat
askdialog
switch %buttonval
# If the dialog txt item has been changed, or no
# report has yet been produced, then produce it
case "Screen"
if %dlogchanged = TRUE
or rep_to_prn = FALSE
call report_on_house(h)
endif
# If we have a report to print, simply print it else
# give an error message to the user
case "Printer"
if rep_to_prn
shell lp [BFILE]
else
error "No report to print"
endif
endswitch
until %buttonval = "Close"
endif
until %menuval="Exit"
117
Chapter
Reports
next
forall
report off
if printon
printer off
endif
endproc
menu 1 "Database"
menu 1-1 "Output
menu 1-2 "Output
menu 1-3 "Output
menu 1-4 "@Exit"
length 60
endif
<Print the Report>
if to_print
printer off
margin 4,76
length 65
endif
119
Chapter
Graphics
7
Graphics
121
Chapter
Graphics
Kingfisher graphics
Kingfisher provides a powerful set of graph types and graph attributes
that allow a wide range of application specific displays to be produced.
This exact capability is made available to you in TSL through a range of
commands that provide both high level capabilities for simple
applications down to fine control of graph attributes for more
demanding situations.
In order to access this capability Kingfisher is executed by TSL in a
special modecalled TSL mode. In this mode Kingfisher does not create
the usual query window but instead just provides the display window
where graphs are produced. Commands in TSL can then be executed to
draw graphs in this window.
All of the following capabilities can be accessed from TSL:
The canvas
The Kingfisher display window is known as a canvas. Before any
graphics commands can be executed, a canvas must be created. This is
done in one of three ways:
The canvas
123
Chapter
Graphics
If you want to delete all the canvasses created by your TSL script, use
the command:
canvas off all=TRUE
Canvas types
The examples above create a display window with a complete menu
systemthat is, the same menu entries as are normally provided in
Kingfisher. This means that you can change the format of graphs in the
window, reposition and resize them and so on. All the usual capabilities
are provided. This type of canvas is best used when you are developing
an application as it provides an environment in which you can fine tune
your graphs for the application and then save them to be used from
your final TSL scripts. However, a canvas can be created in two other
important ways: with no ability to change the graphs, and with no
menu or other decorations at all.
The example below creates a canvas with a minimal menu system. Only
the cursor, measure, zoom and similar commands are made available on
the menu system and you cannot change the format of the graphs.
canvas on noedit 100 100 500 400
Kingfisher Procedures
Kingfisher Procedures
Once you have created a canvas you can produce graphs in the
window. The simplest way of doing this is by executing a Kingfisher
procedure. A Kingfisher procedure is essentially a sequence of queries
together with the description of a graphical format in which to display
the output from those queries. Procedures are defined independently of
TSL using Kingfisher. For full details on how to create, manage and edit
procedures refer to the documentation for Kingfisher.
To invoke a previously defined Kingfisher procedure in TSL, use the
KFPROC command. For example, if you have previously created a
procedure called spectra you can execute it using the command:
kfproc spectra
125
Chapter
Graphics
Accessing procedures
When a procedure is created in Kingfisher it is associated with the
database which is open at that time. A procedure may be specified as
shared, in which case it is available to all users of that database, or
private in which case it is visible only to the user who created it. The
TSL application must open the database associated with a procedure
before trying to execute that procedure and, except for shared
procedures, must be run with the same user name as that which was
used when the procedure was created.
Once you have completed your application you may wish to collect
together all the procedures you use to make it easier to distribute or
manage your application. In this case you should put all the procedure
files in a directory and set the environment variable KF_PROC_PATH
accordingly. This variable is set to a colon separated list of directories.
Having searched the usual private and shared directories, Kingfisher
looks for procedures in all the directories on this path.
Variables
When creating a Kingfisher procedure you may specify that the values
of certain variables used in the procedure should be obtained by
prompting the user when the procedure is run. When running the
procedure from TSL you may want to set these variables from within
the TSL application, perhaps as the result of a dialog interaction or from
the results of a previous query. In this case you must prevent the
procedure server re-prompting for these variables when the procedure
is executed by specifying the NOPROMPT modifier. For example:
kfproc noprompt spectra
Errors
After execution of the procedure, the TSL interpreter sets the special
integer variable %GRSTATUS to indicate the success or failure of the
procedure. A value of 0 indicates that the procedure was executed
Example
Description
An error was detected by the TQL Server during the execution of the procedure.
The procedure could not be executed at present as Kingfisher was executing on behalf of another TSL application.
If you are running a canvas in the default modethat is, you did not
specify NOEDIT or NOMENU in the CANVAS ON commandKingfisher
displays an error dialog whenever an error condition occurs. This helps
you to solve any problems as you develop the application. However, if
the canvas is in NOEDIT or NOMENU mode, Kingfisher does not report any
errors and it is up to your application to test %GRSTATUS if an error
might reasonably be expected.
Example
The following example, which uses the KINGS database, illustrates the
use of the KFPROC command. Both this example and the associated
procedure (PLOT_CHILDREN) are supplied with your system. It allows
the user to edit a dialog to set whether the NOPROMPT modifier is used
when executing the procedure.
# Execution of a procedure (example18.tsl)
#
#
#
#
127
Chapter
Graphics
repeat
askmenu
switch %menuval
case "Run"
# If we are running the procedure without prompting
# then we get the Royal House from a dialog in TSL
if no_prompt
askdialog 2
endif
# now run the procedure with the requested modes
if no_prompt
kfproc noprompt PLOT_CHILDREN
else
kfproc PLOT_CHILDREN
endif
Printing a canvas
case "Options"
# Let the user set the procedure option
askdialog 1 "Procedure Options"
endswitch
until %menuval = "Exit"
query close ;
canvas off
Printing a canvas
You will often want to provide the user with a means of producing a
hardcopy of a graph. Although the menu system on a display window
normally has the print option enabled, it is sensible to provide a
hardcopy option in the TSL menu system itself.
Kingfisher is only able to print or plot what is currently displayed in the
current canvas, so you must first generate the graph or graphs by
executing a procedure or using the GRAPH command as described later
in this chapter. The command below prints the contents of the current
canvas to a printer or plotter:
canvas print
After the SET keyword there follows a list of name/value pairs. The
name is the name of a property and the value depends on the property
that is being set. There are eighteen properties that control hardcopy
output from a canvas and all of them can be set using this command
(including the UNIX commands used to send the output to the
129
Chapter
Graphics
Errors
After execution of a CANVAS CONFIG LOAD command, the TSL
interpreter sets the special integer variable %GRSTATUS to indicate the
success or failure of the command. A value of 0 indicates that the
command was executed successfully. Other values indicate various
error conditions:
Value
Description
10
The CANVAS CLEAR command clears the current canvas. All graphs
on the canvas are destroyed.
131
Chapter
Graphics
Creating a graph
While procedures provide a very straightforward way of incorporating
graphics into TSL they lack a lot of the flexibility that may be needed in
a more substantial application. The main difficulty is that the procedure
itself contains the queries that are needed to retrieve and otherwise
manipulate the data in the database. It is often much more convenient if
the database manipulation and retrieval commands are specified in TSL
where they can easily make use of variables and the more sophisticated
control structures of the language.
Consequently TSL provides a number of commands to create and
individually control graphs in the canvas. A graph can be thought of as
an object in the canvas. The object has a position and a size, it also has
a large amount of formatting information associated with it, and finally,
the object is able to plot the results of queries. Graphs are created
implicitly whenever a GRAPH command is used. Consider the following
example:
graph draw display spectrum from spectra
where test#=23 ;
Graph formats
The example above demonstrates the minimum that needs to be done
to produce a graph. However, you will probably want to use a
predefined graph format for a graph. A graph format contains all the
information about the layout, titles, colours and so on, that are used in
a graphit does not contain any information about what sort of data is
to be plotted on the graph.
The example below shows how to create a graph and load a graph
format called XYLINE:
graph format load xyline
graph draw display spectrum from spectra
where test#=23 ;
The GRAPH FORMAT command creates the graph and position it to fill
the canvas. The subsequent GRAPH DRAW command executes the query
and plots the data in the specified format.
This creates a formatted graph in the right hand half of the canvasthat
is, positioned half way along the top edge, extending for the full height
and half the width of the canvas. Again note that the GRAPH POSITION
command implicitly creates a new graph.
The first two commands create a new graph and plot the specified data
in it. The first GRAPH FORMAT command implicitly creates a graph. The
subsequent GRAPH FORMAT command destroys the existing graph (in fact
all graphs on the current canvas will be clearedas will be explained
later) and creates a new one. This implicit destruction and creation is
very convenient when you are building an application that produces
graphs from various menu entries. All you need to do for each menu
action is:
133
Chapter
Graphics
Any existing graphs are automatically cleared and a new graph created.
All GRAPH commands, other than GRAPH DRAW and GRAPH CURSOR,
perform implicit destruction and creation. Note that an existing graph is
destroyed only if it contains datathat is, a GRAPH DRAW command has
been executed.
Errors
Errors
After execution of a GRAPH LOAD, GRAPH DRAW or GRAPH SAVE command
the TSL interpreter sets the special integer variable %GRSTATUS to
indicate the success or failure of the command. A value of 0 indicates
that the command was executed successfully. Other values indicate
various error conditions as described below:
Value
Description
11
The query in the GRAPH DRAW command did not return any
data.
If you are running the canvas in the default modethat is, you did not
specify NOEDIT or NOMENU in the CANVAS ON command, Kingfisher
displays an error dialog whenever an error condition occurs. This helps
you to resolve any problems as you develop the application. However,
if the canvas is in NOEDIT or NOMENU mode, Kingfisher does not report
any errors and it is up to your application to test %GRSTATUS if an error
might reasonably be expected.
Example
The following example, which uses the KINGS database, illustrates the
use of the GRAPH command. Both this example and the associated graph
formats (CHILDREN and SPOUSES) are supplied with your system.
135
Chapter
Graphics
"Plot"
1-1 "No. of children" action = "Children"
1-2 "No. of spouses" action = "Spouses"
1-4 "Exit" action = "Exit"
repeat
askmenu
switch %menuval
case "Children"
graph format load children
graph draw display children, kingno
from kings
sequence by kingno ;
case "Spouses"
graph format load spouses
graph draw display marriages, kingno
from kings
sequence by kingno ;
endswitch
until %menuval="Exit"
query close ;
canvas off
Plotting overlays
describes some more facilities in TSL that allow you to get finer control
over the graphs that you produce.
Plotting overlays
If you are familiar with Kingfisher, you know that a graph can display
data from more than one dataseteither as an overlay or on a
secondary Y axis, or both. This same capability is available from TSL
simply by executing additional GRAPH DRAW commands after the
command that produced the primary dataset. The data will be drawn on
the current graph in a manner determined by the graph format and the
graph type. The example below demonstrates this technique:
graph
graph
graph
graph
Graph properties
The format of a graph is defined by the current values of the properties
of that graph. There are over one hundred properties that define the
graph format, controlling attributes ranging from the graph typefor
example, line or scatter, to the horizontal pixel offset of the legend box.
All of these properties are set when you load a graph format.
Each property has a name, a type (integer, real or string) and it may
contain one or many values. For example, the graphtype property,
which determines the basic type of graph, such as line or scatter, takes
a single integer value. The colour property, which sets the colour of
the main graphical elements associated with the datasets, is also an
integer but it takes up to eight valuesone for the primary dataset, and
the rest for the secondary datasets. The complete list of graph
properties, their type and valid values is documented in the Kingfisher
Reference guide.
137
Chapter
Graphics
To add annotation to the graph on the fly. You may wish to add
labels that depend on other calculations that you have performed or
requests from the user.
Example
This command causes the TQL variable pcolour to be set to the colour
of the primary dataset. The variable will be created if it does not already
exist.
Example
The following example plots a graph with a legend. The script creates a
dialog which allows you to set the format of the legend entries and the
text for the main entry via TSL. This example uses the KINGS database
and a graph format (LEGEND) which is provided on the standard
distribution.
# Setting graph properties (example20.tsl)
# Plots a graph with a legend and allows the
# user to control the legend entry format and
# the text entry via a TSL dialog.
# Enable the canvas
#
canvas on noedit
query open kings ;
menu 1 "Plot"
menu 1-1 "Graph with legend" action = "Graph"
menu 1-3 "Exit" action = "Exit"
menu 2 "Edit"
menu 2-1 "Legend..." action = "Legend"
repeat
askmenu
switch %menuval
case "Graph"
graph format load legend
graph draw display children, kingno
from kings
sequence by kingno ;
139
Chapter
Graphics
case "Legend"
dialog layout columns=1
dialog option style "Legend style" \
"Coloured Text" "Text & Colour" "Text & Style"
dialog text(12) entry1 "Main entry"
askdialog
if %dialogval
switch style
case "Coloured Text"
declare istyle 0
case "Text & Colour"
declare istyle 1
case "Text & Style"
declare istyle 2
endswitch
canvas mode edit=on
graph property set lgstyle=[istyle] \
lgdstext/0="[entry1]"
canvas mode edit=off
endif
endswitch
until %menuval="Exit"
query close ;
canvas off
Example
The X, Y and Z values are in data coordinatesthat is, they are the
actual data values that would be plotted at that position on the graph.
The values are always real numbers.
If the user does not click on the current graph, the variables will be set
to NULL. The example below shows how the command might be used:
graph cursor
if %xval<>null and %yval<>null
info "Value is [%xval] [%yval]"
else
error "Missed!"
endif
Example
The following example demonstrates how the cursor can be used to
implement range selection on a simple graph. A graph is drawn and the
cursor is used to read off a range in the X domain. This range is then
used to generate a condition for a query in the database and the graph
is redrawn.
# Using the graph cursor (example21.tsl)
# Plots a graph. The cursor can be used to select
# an X range from which to construct a new query.
# Enable the canvas
#
canvas on noedit
query open kings ;
declare minx
declare maxx
menu 1 "Plot"
menu 1-1 "Graph" action = "Graph"
menu 1-3 "Exit" action = "Exit"
menu 2 "Cursor"
menu 2-1 "Select range" action = "Range"
repeat
askmenu
141
Chapter
Graphics
switch %menuval
case "Graph"
graph format load children
graph draw display children, kingno
from kings
sequence by kingno ;
case "Range"
info "Select left edge of range to zoom on"
graph cursor
if %xval<>null and %yval<>null
set minx %xval
info "Select right edge of range to zoom on"
graph cursor
if %xval<>null and %yval<>null
set maxx %xval
graph format load children
graph draw display children, kingno
from kings
where kingno>=minx and kingno<=maxx
sequence by kingno ;
endif
endif
info
endswitch
until %menuval="Exit"
query close ;
canvas off
Loading a colourmap
If you are using surface plots or maps, you may wish to load a different
colourmap either from the standard Kingfisher selection or one that you
have created yourself. The environment variable KF_COLOURMAP_PATH
can be used to define a set of directories where user-defined
colourmaps are located. These directories are searched before the
standard Kingfisher directories.
Errors
Errors
After execution of a CANVAS COLOURMAP LOAD command the TSL
interpreter sets the special integer variable %GRSTATUS to indicate the
success or failure of the command. A value of 0 indicates that the
command was executed successfully. Other values indicate various
error conditions as described below:
Value
Description
143
Chapter
Graphics
setgraph 1
So to create multiple graphs you set the current graph to 1 (the default),
execute GRAPH commands to position, format and draw the graph, then
set the current graph to 2 and create that, and so on. The example
below creates two graphs on the left and right of the canvas.
setgraph 1
graph position 0 0 50 100
graph format load xyline
graph draw display spectrum from spectra
where test#=23 ;
setgraph 2
graph position 50 0 50 100
graph format load xyline
graph draw display spectrum from spectra
where test#=24 ;
There are two complications to this model which are brought about by
restrictions in Kingfisher. The first concerns the GRAPH DRAW command
and the second concerns what happens when a graph is destroyed.
The GRAPH DRAW command, unlike the other commands, does not
draw data on the current graph but actually draws data on the last
graph created in the current canvasknown as the graph with the
data focus. In most situations the current graph will have the data
focus and you will not encounter any problems. However, you will
get an error if you execute a GRAPH DRAW command when the
current graph does not have the data focus.
Example
This example demonstrates how you can manage multiple graphs on a
canvas. The script allows you to plot up to four graphs on the canvas
and automatically positions and sizes the existing graphs to make space
on the canvas.
# Multiple graphs (example22.tsl)
# Plots many graphs on the same canvas
Example
145
Chapter
Graphics
from kings
where upc(house)=upc(h) ;
endif
endswitch
until %menuval="Exit"
query close ;
canvas off
As for graphs, there is a notion of the current canvas and all canvas and
graph commands apply to the current canvas. The current canvas is
identified by a number, a name or a combination of the two. (The
default value is 1 with no name.)
If the current canvas already exists, that canvas will be attached to and
subsequent graph and canvas commands will apply to it. Otherwise, it
is created when the next graph or canvas command is performed.
When using the SETCANVAS command to control multiple windows, it is
possible to determine information about each canvas without having to
store it in your application. When a canvas is created or attached to, it
is possible to find the number of graphs (if any) currently drawn in that
canvas, the graph that has the data focus and the graph that is selected
Example
(that is, the graph whose properties can be changed). This information
is available from the following variables:
%NUM_GRAPHS
%GRFOCUSSED
%GRSELECTED
and set the current graph identifier after setting the canvas identifier, for
example:
SETCANVAS 2
SETGRAPH [%GRFOCUSSED]
Example
This example shows how multiple canvasses can be created and
controlled.
# Multiple canvasses (example23.tsl)
# Plots graphs on multiple canvasses
#
# Enable the initial canvas
#
canvas on nomenu
canvas mode edit=on autoraise=on
query open kings ;
declare numgraphs 0, \
canvasses 1, \
acanvas 1, \
h "Anjou"
menu 1 "Plot"
menu 1-1 "Royal House" action = "House"
menu 1-2 "Create Canvas" action = "CreateCanvas"
menu 1-3 "Change Canvas" action = "ChangeCanvas"
menu 1-4 "Exit" action = "Exit"
147
Chapter
Graphics
repeat
askmenu
switch %menuval
case "House"
dialog layout columns=1
dialog text(12) h "Royal House"
dialog toggle samec "On same canvas"
askdialog
if %dialogval
if not samec
setgraph 1
canvas clear
set numgraphs 1
else
if numgraphs=4
error "Too many graphs - 4 is maximum"
else
set numgraphs numgraphs+1
declare i 1
repeat
setgraph [i]
graph position 0\
[(i-1)*100/numgraphs] 100 [100/numgraphs]
set i i+1
until i>numgraphs
endif
endif
graph format load house
graph draw display children, kingno
from kings
where upc(house)=upc(h) ;
endif
case "CreateCanvas"
set canvasses canvasses + 1
setcanvas [canvasses]
canvas on nomenu
canvas mode edit=on autoraise=on
set numgraphs %num_graphs
set samec FALSE
case "ChangeCanvas"
if canvasses <> 1
149
Chapter
Graphics
not normally be edited by hand. Thus queries in the TSL script may
more easily be modified than those in procedures.
can access the data in a single DISPLAY command, on the other hand
you may have to execute many queries and perform significant data
analysis before the data is ready for plotting. Bear the following in
mind:
Having developed the queries to retrieve the data, simply finish off the
sequence with commands such as the following:
graph format load npxy
graph draw print a ;
That is, simply choose a name for the graph format and plot the
resulting data as appropriate. When you run the script you will at least
get a default representation of the data as a line chart and this will help
you to determine whether you are retrieving the correct data.
Having verified that your queries are correct, work on the graph format
to produce the finished graph:
Make sure that you start the canvas in the default modethat is, not
NOMENU or NOEDIT. This allows you to edit the graph in the canvas
and means that Kingfisher displays a message when it encounters
an error.
Run the script to produce the default graph in the canvas. Now use
the normal Kingfisher graphics dialogs to format and modify the
format. When you are finished save the graph format, using the
Save Format As menu command, with the name you used in the TSL
script.
You can now rerun the script and the format will be loaded and
used.
151
Chapter
Miscellaneous Topics
8
Miscellaneous Topics
153
Chapter
Miscellaneous Topics
Loading data from flat ASCII files where the fields are delimited by
spaces or some other delimiter
Loading data from flat ASCII files where the fields are in fixed
columnar positions
Loading data from binary files where the data is in the standard
native binary format and is not aligned
Loading data from a pipe where the UNIX command filters the data
to be in one of the formats above
format
delimiter
" "
terminator 0
overwrite
Errors
After execution of the transfer, the TSL interpreter sets the special
variable %XFSTATUS to indicate the success or failure of the transfer. A
value of 0 indicates that the transfer completed with no errors. Other
values indicate various error conditions:
Value
1
Description
The end of file was encountered during the processing of a
row. EOF is only expected after an entire row has been read.
The missing values are set to NULL and the row will probably be discarded by the TQL Server.
155
Chapter
Miscellaneous Topics
Value
2
Description
The end of row terminator was encountered when not all
fields had been encountered in the row. The missing fields
will be set to NULL and may be discarded by the TQL Server.
Error handling
In the process of executing a TSL script the TSL interpreter executes
very many commands on the TQL Server. Some of these commands
result directly from QUERY commands in the script, some come from the
evaluation of IF expressions and other internal functions in TSL. There
are many circumstances that can cause a TQL command to return an
error, so your application should be aware of where errors may occur
and what it can do about them.
By default when TSL encounters an error (whether it be a query error or
a TSL syntax error) it prints an error message and stops execution. It
may also display an error dialog depending on the value of a special X
resource (see page 200 for a complete description of the displayError
resource).
The response of TSL to query errors can be changed using the ABORT
command. Abort mode can be enabled or disabled for all errors or just
for certain errors.
If a query returns an error for which abort mode has been disabled, the
script is not aborted but a special status variable %QOK is set to indicate
that an error occurred. %QOK is a boolean variable which is set to TRUE if
the last query executed successfully and FALSE otherwise. If the
application needs to take special action when a query fails, it can test
the value of this variable. For example:
abort off
query open mydb ;
abort on
if %qok
# Execute a script to generate a report
#
script report.tsl
else
error "Failed to open database!"
endif
Error handling
Notice how we have bracketed the QUERY command with ABORT OFF
and ABORT ON. We disable abort mode to allow us to test for errors and
then we re-enable abort mode so that any subsequent commands fail
normally.
In the above example abort mode was disabled for all errors, but the
ABORT command can be defined to restrict the errors for which abort
mode is disabled. The ABORT ON EXCEPT command leaves abort mode
enabled for all commands except the errors that follow, for example:
abort on except q-85
This disables abort mode only for query error -85, thus every error
except query error -85 will cause TSL to exit. The ABORT ON ONLY
command leaves abort mode enabled only for the errors that follow, for
example:
abort on only q-85
This disables abort mode for all query, filer and database errors except
query error -85, thus only query error -85 will cause TSL to exit. You
can define a list of error codes by preceding the error number with a
character representing the level of the error; q for query level errors,
d for database level errors and f for filer level errors. For example:
abort on except q-85, d22, q-86, f70
This enables abort mode for all errors except query level errors -85 and
-86, database level error 22 and filer level error 70.
As an alternative to testing %QOK explicitly the application can use the
IFOK command. The command IFOK is equivalent to IF %QOK.
Note that if a TQL error is detected during the evaluation of a condition
in an IF, ELIF, UNTIL, SWITCH or CASE statement, the application
always aborts, regardless of the current abort mode setting.
When developing an application we would strongly recommend that
you run your scripts with abort mode enabled. This ensures that you
quickly catch any syntax errors in TQL commands or commands that
may fail due to maths errors or lack of data errors. Only disable abort
mode for those commands that you know are quite likely to fail, and
only for the errors that you are prepared to write code to handle.
Three further variables are set after the execution of a query: %QERR,
%DERR and %FERR. These contain the query level error code, database
level error code and file level error code for the last command
executed. If any of these values is non-zero, an error has occurred.
157
Chapter
Miscellaneous Topics
Please refer to the TQL Guide and Reference for information on error
codes. The messages generated by TSL when an error occurs and abort
mode is disabled are stored in the variables %QMSG, %DMSG and %FMSG.
These variables hold the query level message, the database level
message and the filer level message respectively.
The example below shows how you can test for a particular error, in
order to print more specific error messages or recover from the error.
abort on except d22
query open mydb ;
abort on
ifok
# Execute a script to generate a report
#
script report.tsl
else
# We only handle database error number 22,
# which is returned if the user is not known.
error "[sysuser()] is not a known user."
stop
endif
sets the timeout for the ASKMENU command to be ten seconds and the
command:
TIMEOUT DIALOG 10
More
More
Another feature of TSL that you may wish to control is the --More--
prompt which appears at the bottom of the main window whenever it is
about to scroll. The user can respond to this prompt in three ways:
You can disable the more prompt completely using the following
command:
more off
This is often the best approach unless you are producing a long report
that you know will not fit in the window and which you want the user
to see all of (that is, it is not just a preview).
If the user presses Q in response to the --More-- prompt, TSL
generates an abort signal. A signal is a bit like an error that you can
catch or trap. If you do not trap the signal, the script aborts and an error
message is printed. The REPEAT command catches these signals, as the
--More-- prompt is usually generated from within a repeat loop. If the
--More-- prompt occurs outside a loop, pressing Q always aborts the
script. Consider the example below:
more on
query display exp#, volts from results ;
repeat
' [exp#] [volts]
next
forall
159
Chapter
Miscellaneous Topics
In this case, when Q is pressed the signal will not be caught by the
repeat loop. If there is no other loop around this bit of the script, the
signal to quit is ignored. Notice that if you have nested loops, outer
loops can trap signals from inner loops.
The end point of the current selection is extended to the current cursor
position when the button is pressed. The new selected area expands or
contracts as the mouse is moved. Releasing the mouse button completes
the selection.
If a selection is made in another window, the TSL application loses the
selection and the text is no longer highlighted.
Fonts
Unlike some X applications, TSL uses application resources to specify a
set of fonts that it will use in the user interface. TSL defines the
following font types which it uses consistently in all dialogs and
windows.
Font type
Usage
Tsl.labelFont
Tsl.dataFont
Tsl.buttonFont
161
Chapter
Miscellaneous Topics
Font type
Usage
Tsl.menuFont
The font to use for all menu entries in the pulldown menu system.
Tsl.toolboxFont
Tsl.normalFont
The font to use in the main TSL window for normal, non-enhanced text.
Tsl.boldFont
Tsl.useVueFonts
Description
Tsl.rows
The number of rows that fit in the terminal window i.e not including the menu bar.
Tsl.columns
Tsl.bufrows
Print spooler
Print spooler
The definition of the print spooler is defined using an application
resource:
Resource
Description
Description
Tsl.alignRows
Tsl.alignColumns
Tsl.alignItems
Defines the default value for the ALIGNITEMS attribute. If this resource is not
defined, the default value for ALIGNITEMS is set to TRUE..
Tsl.defaultColumns
Defines the default value for the COLUMNS attribute. If this resource is not
defined, the default value for COLUMNS
is set to 2.
163
Chapter
Miscellaneous Topics
Attribute
Description
Tsl.defaultButtonColumns Defines the default value for the BUTTONCOLUMNS attribute. If this resource is
not defined, the default value for BUTTONCOLUMNS is set to 1.
Tsl.defaultMode
Tsl.buttonLayout
Defines the default value for the BUTTONLAYOUT attribute. If this resource is
not defined, the default value for BUTTONLAYOUT is set to COLUMNCENTRE.
Tsl.busyOnApply
Defines the default value for the BUSYONAPPLY attribute. If this resource is
not defined, the default value for BUSYONAPPLY is set to TRUE.
Toolbox attributes
The default values for all of the TOOLBOX attributes are specified in the
resource file.
Attribute
Description
Tsl.toolboxToolGap
Tsl.toolboxGravity
Attribute
Description
Tsl.toolboxRows
Tsl.toolboxColumns
Description
Tsl.maxDialogs
Tsl.maxMenuItems
Tsl.maxMenuNesting
165
Chapter
Miscellaneous Topics
Description
Tsl*january: <month>
Tsl*february: <month>
Tsl*march: <month>
Tsl*april: <month>
Tsl*may: <month>
Tsl*june: <month>
Tsl*july: <month>
Tsl*august: <month>
Tsl*september: <month>
Tsl*october: <month>
Tsl*november: <month>
Tsl*december: <month>
Tsl*monday: <day>
Tsl*tuesday: <day>
Tsl*wednesday: <day>
Tsl*thursday: <day>
Tsl*friday: <day>
Tsl*saturday: <day>
Tsl*sunday: <day>
Tsl*january: <janvier>
Tsl*monday: <lundi>
You can edit the defaults file directly. You should only do this if
you are the only person using the system as the changes you make
affect all other users of TSL on that system. If you do wish to affect
all usersperhaps you have an in-house font policyyou should
change the resources here.
You can use xrdb(1) to load specific resources into the X server
that only apply when you are using a specific display.
Command-line options
You can specify resources on the command line to TSL using the
standard -xrm argument. For example the following command sets
the window width to 132 columns:
tsl -xrm "Tsl.columns: 132" script.tsl
Notice that instead of the class name Tsl you use the application name
ictest (which must start with a lower case letter). You might call the
file ictest.rdb. To run your application with its own special resources
you would execute commands such as:
xrdb -merge ictest.rdb
st.tsl
The xrdb(1) command loads your resources into the X server and the
-name argument to TSL sets the application name to ictest.
You can avoid having to use the -name option by creating a symbolic
link to the tsl executable with your application name, for example:
ln -s tsl ictest
Command-line options
The TSL interpreter is invoked using the tsl command. This command
takes a number of options which control the behaviour of both the
interpreter and the TQL Server.
The available options are described below.
tsl <X-options> [-user <username>] [-host <hostname>]
[-server <hostname>] [-outfile <file>]
[-printer] [-raw] [-buffersize <bytes>] [-old]
[-debug] [-nowindow] [-nomap] [-term <termname>]
[-logFile <file>] [-printCommand <command>]
167
Chapter
Miscellaneous Topics
Before any of the TSL-specific arguments come the X options. If you are
using the Motif versions, these are all the standard options to the X
toolkit such as -display, -name -geometry and so on. Following the X
options come the TSL options (note that case is important):
-buffersize
-debug
-host
-nomap
Command-line options
-nowindow
-old
-outfile
-printer
-raw
-server
as for -host
-term
-user
169
Chapter
Miscellaneous Topics
If you are running TSL in nowindow mode (described above), TSL will
not find the X resources specified in $TQL_CLIENT_DIR/appdefs/Tsl.
Resources that configure the log file, the default printer and the
input/output formats of dates, times and constants can be defined using
the following command-line arguments. Additional information on
these command-line arguments can be found by looking for the
appropriate X resource in the file $TQL_CLIENT_DIR/appdefs/Tsl.
-complexOutputFormat
-dateInputFormat
-dateOutputFormat
-logFile
-printCommand
This argument is followed by the command TSL should use to spool output to
the printer. This corresponds to the X
resource Tsl.printCommandfor
example:
-printCommand lp -dps
Command-line options
-printerModel
This argument is used to obtain highlighting details for the printer. It must
be followed by the name of a model
file in $TQL_CLIENT_DIR/etc/models.
If you are using tbprint in PostScript
mode, this should be set to TBPS. This
corresponds to the X resource
Tsl.printerModel.
-rawPrintCommand
-timeOutputFormat
or:
setenv TB_TSL_SPEC_PATH \
/users/ssw/scripts:/usr/local/scripts
171
Chapter
Miscellaneous Topics
Chapter
173
Chapter
General principles
When designing an interface for a TSL application the most important
points to be aware of are:
Consistency
One of the most important things you can do to make your application
easy to use is to ensure that it is consistent both with other applications
you write and, more importantly, with the other tools that are used on
the system.
Users who have used one Motif application have learnt, and are still
learning, how the user interface works. It is important that your TSL
application works in a manner consistent with other Motif software. To
some extent a lot of this consistency is guaranteed since TSL uses
standard toolkits to create the user interface and so you can be sure
that, for example, a slider you create in TSL looks and behaves like
other sliders on the screen.
This basic level of consistency is not enough: it is important that your
application is structured in a similar fashion, that menu items are
organised consistently and so on. As users become more and more
familiar with modern user interfaces they expect new applications to
behave in certain ways. If your application behaves in the same way,
they will become familiar with the application more quickly; if it
behaves differently, their expectations will be dashed and they will
become confused and unsure.
The principle of consistency applies within an application too. It is
important that you adopt a consistent style in your applicationthis
applies to menu layout and action names, dialog usage and layout and
indeed all areas of the user interface that you have control of through
TSL.
Robustness
Robustness
Once your application is consistent, a second principle comes into
playencourage exploration and make it safe! Once the users see that
your application behaves like many others they will start to explore by
looking through menus, opening dialogs and so on. Most people find
this a very effective way of learning. However, this exploration must be
safe. One certain way of discouraging users is to delete all their data
when they select a menu action that is not protected!
This principle also includes securing your database. Your application
should ensure that users who are not allowed to perform certain actions
are unable to do so.
Style guide
TSL can create user interfaces that are consistent with the Look & Feel
of Motif. Although many of the notes below apply to both environments
there are many areas of style that are different in each. If consistency of
Look & Feel is very important to you, we strongly recommend that you
read the appropriate Graphical User Interface Style Guide for your
particular environment.
Icons
Menus
Try to arrange that all menu actions are a similar length. A menu
pane with one 60 character label and 10 short labels looks silly.
175
Chapter
Define mnemonics for all menu entries if possible. You may prefer
to use the mouse but your users may not!
Always put the Exit action at the bottom of the leftmost menu pane
and always separate it from the other menu actions. This is where
the user expects it to be from using other programs.
Arrange menu panes so that the most frequently used actions are at
the top. Use separators to group together logically related actions. If
two actions are barely distinguishable, consider using a cascading
menu.
Tools which are related to each other should be put in the same
tool group. Similarly, unrelated tools should be put in different tool
groups.
Arrange tool groups so that the most frequently used tool groups
are at the top left of the toolbox.
The icons in a tool group should all have the same dimensions.
Confirmation dialogs
Error dialogs
The button labels must clearly answer the question posed by the
confirmation message. Consider repeating the action in the positive
label, for example Yes, Delete Data.
Error dialogs
Clearly state the error condition in the message, using multiple lines
if necessary. Consider using text items in the message to specify the
condition more exactlyfor example, Parameter [PARM] not
defined is better than Bad parameter.
Progress dialogs
Use a progress message if the user has selected an action that may
take more than a short time and which they may want to interrupt.
Because no other interaction is possible during this processing,
users are often concerned that the program has failed or is hung.
What short is depends on the expectations of your users but is
certainly no more than 20 seconds and often less.
177
Chapter
Information dialogs
Use the file selection dialog whenever the user must be prompted
for a fileeither for input or output. This dialog will be familiar
from many other applications.
Selection dialog
Main window
Use the main window to display reports and other application data.
Use the main window for progress messages if you judge the
information dialog is inappropriate or if the user can usefully
review the progress using the scroll barsthat is, a log of actions
taken.
If you can predict the length of reports and they are a reasonable
size, configure the window buffer size accordingly and disable the
--More-- prompt. If you cannot predict the length of reports and
they are likely to be long, use the --More-- prompt.
Dialogs
Dialogs
Consider creating context sensitive help files for each dialog in your
application.
179
Chapter
Dialog items
Use text items when the input data is not in a contained domain
that is, it is not one of a set of values or a small range of values.
Try to use text fields that have the same maximum length and
display length. Use scrolling text fields only if layout dictates it or if
the maximum length is long. Avoid text items with similar display
and maximum lengths.
The allow null error message should state clearly which text field a
value is missing for.
The out of range error message should state clearly which text field
the error occurred and specify the maximum and minimum values,
if known.
Always use a fixed space font, particularly for numeric input, if your
environment allows it.
If you have a large range, increase the size of the slider to reduce
its sensitivity.
Dialog items
Avoid using verbs such as enable in the toggle label as this can be
confusing. Never put negatives in the label as this is always
confusing!
Use scrolled lists when there are a large number of choices, say 10
or more.
The positions of the various dialog items may change if the width of
a list changes as a result of a list editing command. In addition, the
dialog might widen or narrow to cater for the new size of the list.
This can look unprofessional to users. To avoid this you can do the
following:
If the set of values has obviously come from the database, use a
scrolled list.
181
Chapter
Dialog layout
Try not to use more than 10 dialog items in the same dialog unless
the dialog mimics some panel or display familiar to the user.
PART 2
TSL Reference
TSL Reference
TSL Reference
185
TSL Reference
Notation
{}
|
()
name
Description
TQL_expression
quoted_TQL_bool_expr
TQL_variable_name
TQL_bool_var
integer
Construct
Description
data_type
quoted_string
filename
bitmap_file
commands
system_command
dimension_unit
187
TSL Reference
| YADJUST = dimension_unit
| LABELGAP = dimension_unit_no_grid
Finally, the SENSITIVE, READONLY and ALLOWNULL attributes use the
type boolean_attribute
boolean_attribute = TQL_bool_variable
| TRUE | FALSE | YES | NO
| quoted_TQL_bool_expr
ABORT
Arguments
errlist = errcode { , errcode }
errcode = ( Q| q | D| d | F | f) integer
Description
Abort mode can be enabled using the ABORT ON command, and
disabled using the ABORT OFF command. The modifiers EXCEPT and
ONLY can be used with ABORT ON to enable abort mode for some errors
but not others. The ABORT ON ONLY command instructs TSL to enable
abort mode only for the given list of errors, and the ABORT ON EXCEPT
command instructs TSL to enable abort mode for all errors except the
given list of errors.
If abort mode is enabled for a TQL error, the application aborts with an
error message, when that error is detected by the TQL Server.
If abort mode is disabled for a TQL error then, when the TQL error is
detected, no error is reported but the query variable %QOK is set to
FALSE (and the IFOK command evaluates to FALSE). In addition, the
variables %QERR, %DERR, %FERR, %QMSG, %DMSG and %FMSG are created to
hold the error numbers and error messages for the query, database and
filer level of the TQL error.
Only errors resulting from the execution of QUERY and GRAPH DRAW
commands or from substitution of text items may be trapped in this
way. In particular, note that TQL errors resulting from the execution of
queries performed during the evaluation of conditions in IF, ELIF,
UNTIL, SWITCH or CASE commands cannot be trapped. In these cases, a
query error always causes the script to abort.
ABORT on its own is equivalent to ABORT ON.
189
TSL Reference
Example
ABORT OFF
Enables abort mode only for query level errors -113 and -114, database
level error 52 and filer level error 51.
ABORT ON EXCEPT q-113, d52, q-114, f51
Disables abort mode only for query level errors -113 and -114, database
level error 52 and filer level error 51.
ADJUST
Arguments
nlines = integer
Description
The internal record of the current page position is incremented by
nlines.
If text output from another program (for example, from a REPORT query
or a SHELL command) is included in the TSL output, the TSL interpreter
loses track of its current page position. This problem can be corrected
using ADJUST where nlines is the number of lines output by the called
program.
Text substitution is performed on nlines.
191
TSL Reference
Application
Resources
Description
labelFont
dataFont
buttonFont
menuFont
toolboxFont
normalFont
The font used for displaying text in the TSL terminal window. Should be a fixed-width font.
boldFont
useVueFonts
Each font resource may be set to the name of any font recognised by
the X windows server.
XFontSets
TSL uses FontStructs placed in FontLists to store the fonts used by the
application. However in order to enable TSL to support international
characters, for example the Korean and Japanese languages which
consist of thousands of characters, the FontStructs need to be combined
Description
labelFontset
dataFontset
buttonFontset
menuFontset
toolboxFontset
normalFontset
The font used for displaying text in the TSL terminal window. Should be a fixed-width font.
boldFontset
useVueFontset
193
TSL Reference
Terminal Window
Resource
Description
rows
columns
bufrows
bufcols
halfBright
Dialog Appearance
Resource
Description
columnGap
rowGap
horizMargin
Integer. Gap in pixels between left and right borders of dialog and nearest dialog element.
vertMargin
Resource
Description
labelGap
buttonGap
buttonRowGap
buttonExtra
separatorGap
Dialog layout
The following resources set the default values for dialog layout
attributes. They may be overridden for an individual dialog using the
DIALOG LAYOUT command.
Resource
Description
defaultColumns
alignColumns
alignItems
defaultMode
195
TSL Reference
Resource
Description
buttonLayout
busyOnApply
Description
horizontalscroll
verticalscroll
Toolbox Appearance
The following resources set the default values for toolbox attributes.
They may be overridden using the TOOLBOX command.
Resource
Description
toolboxToolGap
toolboxGroupGap
toolboxFrame
toolboxGravity
toolboxRows
Resource
Description
toolboxColumns
197
TSL Reference
Description
dateInputFormat
dateOutputFormat
timeOutputFormat
Printing
Resource
Description
printCommand
rawPrintCommand
printerModel
Description
maxDialogs
maxMenuItems
maxMenuNesting
199
TSL Reference
Miscellaneous
Resource
Description
logFile
queryBufferSize
complexOutputFormat
displayErrors
killCanvasOnError
ASK
Arguments
varname = TQL_variable_name
Description
When the ASK command is executed the application pauses to read a
line of input from the main TSL window. It then creates the TQL
variable varname (if necessary) and assigns the value read from the
terminal. Note that the value is treated as a string. If the application
needs to treat the value as a number, it must use the TQL function VAL
to convert to a real.
performs a DISPLAY query based upon a value for cust_name read from
the terminal.
201
TSL Reference
ASKDIALOG
Arguments
dialog_number = 1 200
dialog_name = string
dialog_title = quoted_string
Description
If dialog_number or dialog_name are not specified, the current dialog is
processed. A dialog window is created and displayed, labelled with
dialog_title.
Each of the items in the dialog is initialised from the associated query
variable. If any variable does not exist or has an invalid value, it is
initialised to NULL. Note that the items are initialised from the value of
the variable at the time of the ASKDIALOG command, not from the value
at the time the dialog item was defined.
When an ASKDIALOG command is encountered TSL evaluates the
sensitivity of each dialog item and application defined buttons on the
server before displaying the dialog. In addition, the readonly status of
text and multiline text items are evaluated.
The application waits until the user presses one of the standard control
buttons, one of the application defined buttons or changes the value of
an active dialog item.
If any text or multiline text items have been defined with ALLOWNULL,
RANGEMIN or RANGEMAX, TSL checks the values of these text items to
ensure that they meet the desired criteria. If they do not, TSL displays
an error message and ASKDIALOG repeats the above process until
acceptable values are entered or the Cancel or Close button is pressed.
The system variable %DLOGCHANGED indicates whether the user has
changed the value of any of the dialogs items since it was first
displayed. When the dialog is displayed, %DLOGCHANGED is set to FALSE.
If the user changes the value of one or more of the dialogs items,
%DLOGCHANGED is set to TRUE. Subsequent ASKDIALOG commands reset
%DLOGCHANGED to FALSE. When generating lengthy or time-consuming
203
TSL Reference
Examples
ASKDIALOG
ASKMENU
Description
The application waits until the user selects an item from the menu
system or the toolbox. On return, the action string of the selected item
is placed in the special query variable %MENUVAL.
The first execution of the ASKMENU command actually builds the menu
system and the toolbox according to the currently defined menu and
tool items. No further menu or tool items may be defined thereafter.
On completion of the ASKMENU command, the items in the menubar and
the toolbox are deactivated (or desensitised) to prevent the user from
interacting with them. The items whose SENSITIVE attribute evaluates
to TRUE are reactivated only during subsequent executions of the
ASKMENU command. When a menu item is desensitised, a visual
indication is provided by the window systemthe exact indication
depends upon the Look and Feel but typically the text for the menu
items is greyed out. A desensitised tool item looks the same as a
sensitive tool item.
205
TSL Reference
BEEP
Produces a beep
Syntax
BEEP
Description
Produces a beep.
BREAK
Description
The BREAK command is used to exit from a loop and continue
processing at the statement immediately following the end of the loop.
Example
REPEAT
...
IF id=null
BREAK
ENDIF
...
FORALL
The REPEAT loop is broken when the variable ID has a null value.
207
TSL Reference
BUFFER
Arguments
attributes = attribute | attribute
attribute = FILENAME = quoted_string
|APPEND = ( TRUE | FALSE | YES | NO )
Description
This command can be used to specify attributes of the current buffer
file and send a copy of the text displayed in the TSL window to the file.
The current buffer file is set by the SETBUFFER command.
After execution of a BUFFER ON command, a copy of the text displayed
in the TSL output window is sent to the current buffer file until a
BUFFER OFF command is executed. Initially, text buffering is off.
The BUFFER command is also used to define attributes of the current
buffer file. The FILENAME attribute defines the name of the file.
Normally when a file is opened for the first time, TSL overwrites the
file. If you want to add output text to the file, define the APPEND
attribute as TRUE/YES.
The BUFFER command also redefines a special TQL macro %BUFFERED.
This is set to TRUE by a BUFFER ON command and FALSE by a BUFFER
OFF command.
Text substitution is performed on the value given in the FILENAME
attribute.
BUFFER on its own is equivalent to BUFFER ON.
Example
SETBUFFER 12
BUFFER FILENAME="/tmp/tsl12.buf", APPEND=TRUE
BUFFER ON
sets the current buffer file to 12, associates the file /tmp/tsl12.buf
with the buffer and turns text buffering on. TSL will append text to the
end of the file, rather than overwriting.
CALL
Arguments
procname = procedure_name
arguments = argument { , argument }
argument = TQL_variable_name | TQL_expression
Description
The CALL command calls the specified procedure, passing it the values
in parentheses. The procedure must have already been defined, and the
correct number of arguments must be given. If the procedure definition
specified that an argument is passed by reference, that argument must
be a variable name.
When the procedure ends, TSL continues processing the script at the
line following the CALL command.
Text substitution is performed on arguments.
Examples
CALL do_report( v_cust, v_date )
209
TSL Reference
CANVAS
Commands
CLEAR
HIDE
PRINT
RAISE
REFRESH
SNAPSHOT
Description
The CANVAS CLEAR command clears the graphics canvas. All graphs on
the canvas are destroyed and all graphics is cleared from the display.
The current graph number is set to 1.
The CANVAS HIDE command causes the graphics canvas to become
unmapped from the displaythat is, it is no longer visible. The canvas
is still active and can be quickly made visible by executing a CANVAS
RAISE command or by plotting data to the canvas with AUTORAISE
mode enabled.
The CANVAS PRINT command causes the current contents of the
graphics canvas to be printed or plotted. The format and other details of
the printed output are controlled by the hardcopy property space. By
default the same hardcopy details as those used by Kingfisher for the
current user are employed. An application may change these values
using the CANVAS HARDCOPY command.
The CANVAS RAISE command causes the graphics canvas to be brought
to the front of the display. If the canvas is unmapped it is mapped, if
the canvas is iconified it is deiconified.
The CANVAS REFRESH command causes the display to be cleared and all
graphs to be redrawn in the order that they were created. The graphs
are otherwise unchanged.
The CANVAS SNAPSHOT command causes a snapshot of the current
graphics canvas to be taken. A new window is created which contains
the contents of the canvas.
For all of these commands, if no graphics canvas exists a CANVAS ON
command is executed automatically.
CANVAS
COLOURMAP
Arguments
colourmap = filename
Description
The CANVAS COLOURMAP command is used to load a colourmap into the
canvas.
The command reads the specified colourmap file and sets the
colourmap into the canvas causing the colours to change immediately
on the display. The colourmap file must have been created by
Kingfisher.
The colourmap is searched for first in the directories on the path
specified by the environment variable KF_COLOURMAP_PATH, in the
users private colourmap directory,
$TQL_CLIENT_DIR/etc/colourmaps/user_name, and then in the
shared directory, $TQL_CLIENT_DIR/etc/colourmaps/shared.
After execution of the command, the TQL variable %GRSTATUS is set to
one of the following:
Value
Description
0:
3:
7:
8:
211
TSL Reference
Example
CANVAS COLOURMAP LOAD myramp
CANVAS
CONFIG
Arguments
config = filename
Description
The CANVAS CONFIG command is used to load a hardcopy configuration
into the canvas.
The command reads the specified configuration file and sets the
hardcopy properties on the canvas. The configuration file must have
been created by Kingfisher.
The configuration file is searched for in the shared directory,
$TQL_CLIENT_DIR/etc/hardcopy.
After execution of the command the TQL variable %GRSTATUS is set to
one of the following:
Value
Description
0:
3:
9:
10 :
213
TSL Reference
CANVAS
HARDCOPY
Arguments
property_value_list = property=value [property_value_list]
property_var_list = property=TQL_variable_name [property_var_list]
Description
The CANVAS HARDCOPY command is used to set or get the values of the
property space which controls the configuration of hardcopy output
from Kingfisher.
If the command is followed by the SET modifier, or by no modifier, the
command sets valuesthat is, it changes the hardcopy configuration.
The property_value_list consists of one or more property names,
followed by an equals sign and the appropriate value for that property.
The value can either be a number or a quoted string.
The correct type and range of values for a property, as well as the
names of all hardcopy properties, are described in Chapter 9 of the
Kingfisher Reference.
Text substitution is carried out on property_value_list.
If the command is followed by the GET modifier, the command gets
values from the hardcopy configuration. The property_var_list consists
of one or more property names, each followed by an equals sign and
the name of a TQL variable. The value of each named property is
retrieved and stored in the associated TQL variable. The value will
either be an integer (long), a real or a string. If the variable does not
exist it is created automatically.
Text substitution is carried out on property_var_list.
If no graphics canvas exists, a CANVAS ON command is executed
automatically.
Examples
CANVAS HARDCOPY SET graphfile="/tmp/out"
Sets the graphfile property, the destination file for graphics output, to
/tmp/out.
CANVAS HARDCOPY pageheight=11 pagewidth=8
Sets the printer page height to 11 inches and the width to 8 inches.
CANVAS HARDCOPY GET orientation=ovar
215
TSL Reference
CANVAS
MODE
Arguments
mode_value_list = mode=value [ mode_value_list ]
Description
The CANVAS MODE command is used to set various modes on the
graphics canvas.
The mode_value_list consists of one or more mode names, each
followed by an equals sign and an appropriate value. The command
sets each specified mode to the specified value.
EDIT mode controls the canvas graphics edit mode. If EDIT mode is
disabled any GRAPH command, other than GRAPH DRAW and GRAPH
CURSOR, which is executed on a current graph will cause that graph and
all other graphs on the canvas to be destroyed. If EDIT mode is
enabled, GRAPH commands continue to apply to the current graph and
can change the format or position of that graph as appropriate. EDIT
mode takes a boolean valuethat is, ON or OFF.
AUTORAISE mode is used to control the raising of the graphics canvas
window when certain commands are executed. If AUTORAISE mode is
enabled, the graphics canvas is raised by executing a CANVAS RAISE
command, whenever a GRAPH DRAW or KFPROC command is executed
that is, a command that plots new data in the canvas. AUTORAISE mode
takes a boolean valuethat is, ON or OFF.
CANVAS
ON,
CANVAS
OFF
Arguments
canvas_mode = NOEDIT | NOMENU | NOWINDOW
geometry = x_position y_position width height
attributes = attribute { , attribute }
attributes =
RESIZE = boolean_attribute
| HIDE = boolean_attribute
| CLASS = quoted_string
off_attributes = ALL = boolean_attribute
Description
The CANVAS ON command creates a graphics canvas in which graphs
and procedures can be executed under the control of the TSL script. If
no copy of Kingfisher is running in TSL mode, TSL executes Kingfisher
in the appropriate mode and with the appropriate initial geometry.
Once Kingfisher is running, TSL attempts to make a connection with the
display window via the X server. If Kingfisher is already running in TSL
mode, a connection is made with this process and any canvas_mode or
geometry arguments are ignored.
The canvas_mode controls how Kingfisher is executed:
217
TSL Reference
The geometry controls the initial placement and size of the canvas
window. The geometry is specified as a sequence of four numbers
corresponding to the X position, Y position (where the X position 0, Y
position 0 is the top left corner of your screen), width and height. The
position is specified in pixel coordinates of the root window; the size is
specified in pixels. Any or all of the numbers can be replaced by an
asterisk indicating that the default position or size, as specified in the X
resource database, is to be used.
Text substitution is performed on geometry.
Setting the resize attribute to FALSE allows you to remove the resize
option for ICCM compliant window managers, therefore making the
canvas a fixed size. The default value for this attribute is TRUE. Text
substitution is performed on the resize value.
Setting the hide attribute to TRUE starts the canvas in an unmapped
state. This is useful when the canvas should not be seen at all by the
user, for example, when using the canvas to create batch graphics. To
map the canvas after creation use the CANVAS RAISE command. The
default value for this attribute is FALSE. Text substitution is performed
on the hide value.
The class attribute can be set to change the application class of the
canvas. The application class determines the primary part of any
resource specification and you would normally only change the class if
you wish to change a large number of resources for all users (for
example, when using the canvas in an application you are writing).
The following is an example of a resource set for the application class
Kingfisher (the default class):
Kingfisher*foreground: White
closes the connection with the Kingfisher display. The canvas will be
destroyed if no other clients are connected to Kingfisher.
219
TSL Reference
CANVAS
RESIZE
Arguments
geometry = x_position y_position width height
Description
The CANVAS RESIZE command allows you to resize the current graphics
canvas programmatically.
The geometry is specified as a sequence of four numbers corresponding
to the X position, Y position (where the X position 0, Y position 0 is the
top left corner of your screen), width and height. The position is
specified in pixel coordinates of the root window; the size is specified
in pixels. Any or all of the numbers can be replaced by an asterisk
indicating that the default position or size, as specified in the X
resource database, is to be used.
Text substitution is performed on geometry.
Examples
CANVAS RESIZE 0 0 600 500
CLEAR
Description
Clears the TSL terminal window and resets the output position to the
top of the window.
221
TSL Reference
CLOSEDIALOG
Arguments
dialog_number = 1 200
dialog_name = string
Description
When a dialog is submitted using an application defined button or a
standard control buttons such as Apply, the dialog remains on the
screen until a CLOSEDIALOG is executed for that dialog. The
CLOSEDIALOG command is used to close a dialog that is no longer
required by the application.
If one of dialog_number or dialog_name are not specified, the current
dialog is closed.
It is not an error to close a dialog that is already closed.
Text substitution is performed on dialog_number and dialog_name.
Example
CLOSEDIALOG 3
Comment
Arguments
commentany sequence of characters
Description
Any line in a TSL script whose first non-space character is # is treated as
a comment and is ignored by the TSL interpreter.
Example
# This is a comment
223
TSL Reference
CONFIRM
Arguments
msg = quoted_string
yes_label = quoted_string
no_label = quoted_string
Description
The string msg is displayed in the message area of the dialog. The
dialog has two buttons, a Yes button and a No button which are
labelled by yes_label and no_label. The application waits until the user
dismisses the dialog using one of these buttons.
When the dialog is dismissed the boolean query variable %CONFIRMVAL
is set to TRUE if the dialog was dismissed using the Yes button,
otherwise it is set to FALSE.
Text substitution is performed on msg but not on either yes_label or
no_label. The msg argument may comprise multiple lines of text with
newlines denoted by the character sequence \n.
If yes_label or no_label are omitted, the default strings OK and Cancel
are used.
Examples
CONFIRM "Exit the System?" "Yes, Exit" "No"
CONFIRM "All data will be lost.\nProceed?"
DECLARE
Description
The DECLARE command is used to create the specified list of TQL
variables on the TQL Server. The command is followed by a comma
separated list of variable names and optional TQL expressions to assign
to the variables.
Text substitution is allowed anywhere after the command keyword.
The command should be used in preference to creating TQL variables
directly using the QUERY CREATE VAR construct as some optimisation is
done to limit the number of queries sent to the server.
Examples
DECLARE a
declares a variable called A. The variable will be set to the null value.
DECLARE x 12, y sqrt(2)
declares two variables X and Y and assigns them the values 12 and the
square root of 2 respectively.
225
TSL Reference
DEFPROC,
ENDPROC
Arguments
procname = procedure_name
parameters = parameter { , parameter }
parameter = [VAR] TQL_variable_name
Description
The DEFPROC and ENDPROC commands are used to define a procedure.
The TSL commands between the DEFPROC and ENDPROC are the body of
the procedure, and may use local variables. The parameters given in the
DEFPROC command represent values (or variables) which are passed to
the procedure when it is called (see CALL). The parameter variables are
local to the procedure.
Preceding a parameter name with the keyword VAR means that the
corresponding argument in the CALL command must be a variable
name. If this parameter variable is changed by the procedure, the
argument variable is also changed.
Text substitution is not performed on procname or parameters. Refer to
description of each command in this section to see where text
substitution is performed on commands.
Example
DEFPROC power ( var x, n )
IF n = 0
DECLARE x 1
ELSE
DECLARE y x-1
CALL power( y, n-1 )
DECLARE x x*y
ENDIF
ENDPROC
DIALOG
item
Arguments
dialog_type = LABEL | TEXT | MULTITEXT |
SLIDER | HSLIDER | VSLIDER |
LIST | OPTION | PANEL |
TOGGLE | BUTTON | CALENDAR | TIMERANGE
parametersdepend upon dialog_type
varname = TQL_variable_name
label = quoted_string
extradepends upon dialog_type
attributesdepends upon dialog_type
Description
A dialog item is a single user interface element. It may be one of the
following:
Label
(LABEL)
Text field
(TEXT)
(MULTITEXT)
Horizontal slider
(SLIDER or HSLIDER)
Vertical slider
(VSLIDER)
Scrolling list
(LIST)
Option menu
(OPTION)
Selection panel
(PANEL)
Toggle button
(TOGGLE)
Push button
(BUTTON)
227
TSL Reference
Calendar
(CALENDAR)
(TIMERANGE)
Most items have a label string label. To create an unlabelled item, set
label to the empty string (""). The maximum length of a label is 60
characters.
Each item, except a LABEL or BUTTON item, must have a TQL variable
associated with it. The value of this variable is used to initialise the
dialog element when the dialog is displayed and is used to store the
return value of that element when the dialog is submitted. The data
type of the variable should be appropriate for the dialog item. The
variable need not be declaredif it does not exist it is created when the
dialog first opens (see ASKDIALOG).
Text substitution is performed on label and some other attributes,
depending upon the dialog item type.
Note that elements can be added to a dialog only as long as that dialog
has not been processed (using the ASKDIALOG command). If a DIALOG
command is executed for a dialog after that dialog has been processed,
that dialog is discarded and construction of a new dialog begins.
All dialog items which are placed in the main dialog area (that is, not in
the user-defined button area) have optional positioning attributes. If
any of these are set, they override or adjust the default position of the
dialog item. These attributes are given at the beginning of this section,
under Notation. Their use is described in Chapter 4 (Dialogs).
A detailed reference for each of the individual dialog item types, as well
as DIALOG LAYOUT and DIALOG SKIP, may be found on the following
pages.
DIALOG
BUTTON
Arguments
button_label = quoted_string
button_action = quoted_string
primary_bitmap = bitmap_file
active_bitmap = bitmap_file
attributes = attribute { , attribute }
attribute = ACTION = quoted_string
| AREA = 0 | 1
| SENSITIVE = boolean_attribute
| position_attribute
Description
The DIALOG BUTTON command is used to create a button on the current
dialog, either in the dialogs main area or the application defined button
area. The application defined button area is positioned between the
main area and the standard control buttons.
The first style of the command creates a button with a label on it. The
second creates an iconic buttonthat is, a button that has an icon on it
instead of a label. This normally uses the primary_bitmap for the icon,
but uses active_bitmap (if this is given) while the button is depressed.
An iconic button may also have a label positioned next to it, provided it
is in the dialogs main area.
The values primary_bitmap and active_bitmap are bitmaps which are
searched for in the directories specified by the XBMLANGPATH
environment variable. See Icons on page 20 for a description of this
environment variable.
Text substitution is performed on button_label, primary_bitmap,
active_bitmap and on the values given with the ACTION, SENSITIVE,
XPOS, YPOS, XADJUST, YADJUST and LABELGAP attributes.
229
TSL Reference
Activation
When a button is pressed the dialog is submitted, with the variable
%DIALOGVAL set to TRUE and %BUTTONVAL set to the buttons ACTION
attribute. Note that the ACTION attribute must be defined for all buttons.
An application defined button may be designated as the dialogs default
buttonthat is, the button that is activated if the user double clicks on
a list or presses return. The default button is identified on the dialog by
a box surrounding the button. A dialog can only have one default
button.
Sensitivity
The value of the SENSITIVE attribute determines whether button can be
pressed or not. Each time the ASKDIALOG command is executed, TSL
evaluates the SENSITIVE attribute (if defined) and sets the button to be
sensitive only if it is TRUE.
Positioning
The AREA attribute is used to control the location of the button, and is
assigned a value of 0 to signify the application defined button area and
a value of 1 to signify the dialogs main area.
The buttons placed in the application defined button area are arranged
in columns as controlled by the BUTTONCOLUMNS attribute (set using the
DIALOG LAYOUT command). Buttons placed in the dialogs main area
are positioned in the same way as other dialog items. In addition, if the
button is a labelled iconic button the attribute LABELGAP can be used to
define the gap between the label and the iconic button.
All labelled buttons are made the same size, determined by the largest
button. Iconic buttons use the size of the bitmap to determine their size.
Example
DIALOG BUTTON "Next Row" ACTION = "Next"
DIALOG BUTTON DEFAULT "Add Customer" ACTION = "AddCust"
DIALOG BUTTON DEFAULT ICON "kingfisher" \
ACTION = "Start Kingfisher"
DIALOG BUTTON "Delete Row" ICON "delete.bm" \
AREA = 1, ACTION = "Delete", \
SENSITIVE = "sysuser() = 'DBA'"
DIALOG BUTTON "Weekly Nett Report" \
AREA = 1, ACTION = "WNett", \
XPOS = 3i, YPOS = 2i, XORIGIN = LEFT
DIALOG
CALENDAR
Arguments
datevar= TQL_variable_name
label= quoted_string
attributes = attribute { , attribute }
attribute = ACTION = quoted_string
| SENSITIVE = boolean_attribute
| position_attribute
Description
This dialog item allows the user to select dates from a calendar
interactively. The item consists of two option items that indicate which
month and year is currently displayed and a calendar from which the
user can select a date.
The user can change which month is displayed by clicking on the
month option item. This displays a pop-up menu listing the months of
the year. When the user selects a new month, the dates in the calendar
change to reflect the new selection. To select another year, the user
clicks on the forward and back arrows on the year item. As a new year
is selected, the calendar changes to reflect the selection.
The date the user selects is stored in the datevar variable that is
associated with the item when it is created. If, at the time of creation,
datevar contains a valid date, the calendar item is created with this date
selected. Otherwise, the calendar is displayed with the current date
selected.
Note that, unlike most other dialog items, if the user selects a date, the
value of %DLOGCHANGED is not affected. Using this item in a dialog may
give unexpected results when used in conjunction with %DLOGCHANGED.
Text substitution is performed on label and on the values given with the
ACTION, SENSITIVE, XPOS, YPOS, XADJUST, YADJUST and LABELGAP
attributes.
231
TSL Reference
Activation
If the ACTION attribute is defined, the dialog item is made active
whenever a new date is selected. If the dialog item is made active, the
value of the ACTION attribute is stored in the variable %BUTTONVAL and
TRUE is stored in the %DIALOGVAL variable.
Sensitivity
If the SENSITIVE attribute evaluates to FALSE, the calendar is
insensitivethat is, it is greyed out and the user cannot select it.
Positioning
The position of the time range slider can either be determined by TSL
or defined by position_attributes.
Example
DECLARE report_date \[11/1/98]
DIALOG CALENDAR report_date "Report Date"
defines a calendar dialog item labelled Report Date with the initial
display date set to 1 November 1998.
DIALOG
LABEL
Arguments
label = quoted_string
bitmap = bitmap_file
attributes = attribute { , attribute }
attribute = SENSITIVE = boolean_attribute
| position_attribute
Description
A label item is simply an output field intended for use as a title in a
dialog. This can consist of either text or an icon. If this is text, the label
is limited to 60 characters.
The first command creates an output field containing text, while the
second places an icon in the dialog. By default, both types are centred
in the current column of the dialog.
The value bitmap is a bitmap which is searched for in the directories
specified by the XBMLANGPATH environment variable. See Icons on page
20 for a description of this environment variable.
Text substitution is performed on label and on the values given with the
SENSITIVE, XPOS, YPOS, XADJUST and YADJUST attributes.
Activation
Labels cannot be made active.
Sensitivity
The SENSITIVE attribute can be used, but this only affects the labels
appearance (a label cannot initiate an action). Insensitive text labels
appear greyed out but insensitive iconic labels appear the same as
sensitive iconic labels.
233
TSL Reference
Positioning
The position can be modified using the position attributes, XPOS, YPOS,
and so on. As a label has only one component, the LABELGAP attribute
cannot be used.
Example
DIALOG LABEL "Parameter Details"
DIALOG
LAYOUT
Arguments
attributes = attribute { , attribute }
attribute = COLUMNS = integer
| BUTTONCOLUMNS = integer
| BUTTONLAYOUT = blayval
| ALIGNCOLUMNS = boolean
| ALIGNROWS = boolean
| ALIGNITEMS = boolean
| BUSYONAPPLY = boolean
| MODE = integer
| WIDTH = dimension_unit_nogrid
| HEIGHT = dimension_unit_nogrid
| GRID = integer x integer
blayval = COLUMNCENTRE
| DIALOGCENTRE
Description
Within a dialog, items are, by default, laid out left to right in the order
that they are created. The number of columns and the way that the
default positions of items may be altered using this command.
Also, the size of a dialog and the size of the dialogs grid can be
changed using this command
In addition the configuration of the standard control buttons can be
controlled using the MODE parameter.
The parameters that can be altered are:
Parameter
Description
COLUMNS
235
TSL Reference
Parameter
Description
BUTTONLAYOUT
ALIGNCOLUMNS
ALIGNROWS
ALIGNITEMS
BUSYONAPPLY
MODE
Parameter
Description
WIDTH
HEIGHT
GRID
Resource
Internal Default
BUTTONCOLUMNS
defaultButtonColumns
BUTTONLAYOUT
buttonLayout
COLUMNCENTRE
COLUMNS
defaultColumns
ALIGNCOLUMNS
alignColumns
TRUE
ALIGNROWS
alignRows
TRUE
ALIGNITEMS
alignItems
TRUE
BUSYONAPPLY
busyOnApply
TRUE
MODE
defaultMode
237
TSL Reference
LAYOUT
LAYOUT
LAYOUT
LAYOUT
COLUMNS = 3
ALIGNROWS = FALSE, ALIGNITEMS = FALSE
MODE = 1
WIDTH = 3i, HEIGHT = 2.5i, GRID = 10x5
The last command defines the dialogs main area to be three inches
wide and two and a half inches high. The size of a grid unit across the
top is set to 3/10 inches, or 0.3 inches and the size of a grid unit down
the side is set to 2.5/5 inches, or 0.5 inches. Notice that, when defining
the grid, there are no spaces on either side of the x.
DIALOG
LIST
Arguments
size = integer
label = quoted_string
stringvar = TQL_variable_name
choice_items = quoted_string { , quoted_string }
| query_buffer_expansion
| file_name
query_buffer_expansion = column_name [/ count ]
count = integer
list_attributes = list_attribute { , list_attribute }
list_attribute = ACTION = quoted_string
| SENSITIVE = boolean_attribute
| MINWIDTH = integer
| MAXWIDTH = integer
| SCROLLMODE = 0 2
| SELECTION_POLICY = SINGLE | BROWSE
| MULTIPLE | RANGE | DISCONTIGUOUS
| SELECTION_DELIM = quoted_string
| SELECTION_MAXITEMS = integer
| position_attribute
Description
This dialog item allows the user to make a choice from an enumerated
list of options. These are displayed in a scrollable list in which size
items are visible; the other items may be viewed by scrolling the list.
The currently selected item is highlighted. If size is omitted, all items in
the list are visible.
In all three cases the choice is represented by a string. No other data
types may be used with these dialog items.
The list of choices may be specified in one of two ways:
239
TSL Reference
Positioning
The attributes, XPOS, YPOS, and so on, can be used to override or
modify TSLs default positioning of these dialog items.
Configuring the lists width and scroll bars
LIST dialog items can also use the SCROLLMODE, MINWIDTH and
MAXWIDTH attributes set the size of the width and to define how the lists
scroll bars are managed:
The SCROLLMODE attribute defines which scroll bars are enabled and
when. The default is SCROLLMODE = 0, which enables a vertical scroll
bar only when there are more items in the list than can be seen at a
time. Setting SCROLLMODE to 1 enables the vertical scroll bar all the time.
Scrollmodes 0 and 1 never have horizontal scroll bars. Setting the lists
SCROLLMODE to 2 enables both horizontal and vertical scroll bars all the
time.
The width of the list automatically updates itself after a list command
when SCROLLMODE is 0 or 1. The minimum and maximum widths of a
list in characters are set using the MINWIDTH and MAXWIDTH attributes.
If SCROLLMODE is set to 2that is, there is a horizontal scroll barTSL
checks whether MAXWIDTH has been defined and uses this value to set
the width of the list item. Otherwise it uses the value set for the
MINWIDTH attribute. If neither were defined, the width of the widest
item in the list is used.
For more information on SCROLLMODE, see page 60.
Selection policy
The SELECTION_POLICY attribute specifies whether the user can select
one or several items from the list. It may take the following values:
Attribute
Meaning
SINGLE
BROWSE
241
TSL Reference
Attribute
Meaning
MULTIPLE
RANGE
Allows multi-selection. Items are selected by clicking and dragging the cursor over a single block of
items. Only adjacent list items may be selected.
DISCONTIGUOUS
For list types that allow multi-selection, the maximum number of items
that may be selected can be specified with the SELECTION_MAXITEMS
attribute. By default, this is set to the number of items in the list.
If the selection policy is MULTIPLE, RANGE or DISCONTIGUOUS, the TQL
variable associated with the list is set to the selected values as a comma
separated list. An alternative list delimiter can be set using the
SELECTION_DELIM attribute.
Three system variables hold information that aid in the processing of
multiple selections:
Note that TQL has an internal limit of 4096 characters as the maximum
length of a string literal. If a list allows a large number of items to be
selected, this limit could be exceeded. If a user tries to select items that
will cause this limit to be exceeded, a warning message is displayed
and the items are not selected from the list.
Examples
DIALOG LIST(3) town_name "Town" "Aberdeen" "Aviemore" \
"Dunbar" "Edinburgh" "Eskdalemuir"
creates a scrolling list with 5 items, 3 of which are visible at any one
time.
QUERY DISPLAY param_name AS pname FROM setup
creates a scrolling list with at most 10 items (4 visible) where the items
are obtained from a display query on the database.
DIALOG LIST(4) parmchosen "Parameter to Plot" pname/10 \
ACTION = "Parm Selected", \
SCROLLMODE = 2, MAXWIDTH = 10
creates a scrolling list with horizontal and vertical scroll bars which
displays 4 items at a time and where only ten characters of each item
can be seen at a time. If an item is selected from the list, ASKDIALOG
validates any text dialog items. If this is successful ASKDIALOG, returns
and puts Parm Selected in %BUTTONVAL and TRUE in %DIALOGVAL.
DIALOG LIST(4) parmchosen "Parameter to Plot" pname/10 \
SELECTION_POLICY = MULTIPLE, SELECTION_MAXITEMS = 5
SELECTION_DELIM= ";"
243
TSL Reference
DIALOG
LIST
(list
commands)
Arguments
varname = TQL_variable_name
command = INSERT pos values
| DELETE pos [num]
| REPLACE pos [num] values
| APPEND values
| SAVE [filename]
| READ [filename]
| CLEAR
pos = integer | quoted_string
num = integer
values = quoted_string { , quoted_string }
| query_buffer_expansion
query_buffer_expansion = column_name [/ count ]
count = integer
Description
This command is used to change the contents of a list without having to
recreate the entire dialog. This can only be done to a list in the current
dialog, which must already have been displayed using the ASKDIALOG
command.
All the commands, except CLEAR, require parameters.
The position in the list where the contents change can either be a string
or a number. The INSERT command accepts any number greater than or
equal to 0. The DELETE and REPLACE commands accept a number if it is
greater than 0 and less than or equal to the number of items in the list.
If a string is given, the string must exist in the list.
If the position is invalid, the variable %LISTOK is set to FALSE and the
list is not modified. Otherwise %LISTOK is set to TRUE and the list is
updated. The APPEND and CLEAR commands do not require a position to
be given and %LISTOK is always set to TRUE after executing one of these
commands.
The INSERT and APPEND must be given values to put into the list. This is
done in the same way as when defining a lists initial valuesthat is,
either as a sequence of strings or as data from the query buffer.
The INSERT command adds values to a list at a given position. If the
position is 0 or is greater than the number of items in the list, it
appends the given values to the end of the list.
The DELETE command deletes one or more items from a list starting
from a given position. If the number of items to be deleted is not given,
only one item is deleted.
The REPLACE command replaces a number of items with given values
starting at a given position. If the number of items to be replaced is not
given, the number of items replaced is equal to the number of values
being added to the list.
The APPEND command appends a number of items to the end of a list.
The SAVE command copies the items in the list to a file. The contents of
the file is overwritten each time this command is executed.
The READ command appends a number of items to the end of a list
with the contents of the file.
Finally the CLEAR command empties the list.
Text substitution is performed on pos, num and values.
The width of the list automatically updates itself after a list command
when SCROLLMODE is 0 or 1. For more information on SCROLLMODE, see
page 60.
Examples
DIALOG LIST town_name \
INSERT 10 "Aberdeen" "Aviemore" \
"Dunbar" "Edinburgh" "Eskdalemuir"
deletes the first occurrence of the string evaluated from the variable
ingred1 from the list identified by the variable ingredient.
DIALOG LIST output_dest \
REPLACE "[printer]" 1 "Plotter" "Screen" "HPGL file"
245
TSL Reference
replaces one item, the first occurrence of the string evaluated from the
variable printer, with the given values in the list identified by the
variable output_dest.
QUERY DISPLAY param_name AS pname FROM setup
WHERE batch = [batch_no] ;
DIALOG LIST parmchosen APPEND pname/10
appends at most ten items from the column pname to the list identified
by the variable parmchosen.
DIALOG
MULTITEXT
Arguments
size_spec = columns [, rows ]
columns = integer
rows = integer
textvar = TQL_variable_name
label = quoted_string
attributes = attribute { , attribute }
attribute = SENSITIVE = boolean_attribute
| READONLY = boolean_attribute
| ALLOWNULL = boolean_attribute
| NULL_ERR_MSG = quoted_string
| MAXLEN = integer
| position_attribute
Description
A multitext item is a multiline text editor in which the user can enter
multiple lines of text and can use simple text editing capabilities. A
multiline text item can only be used to display and edit string data. The
size of the text item is controlled by specifying the number of columns
in the item and the number of rows. The item is created at this size but
the user can enter longer lines or more lines into the item in which case
scroll bars are added automatically.
Unlike the normal text dialog item, the maximum size of the string
returned by the dialog item cannot be specified. The TSL script must be
prepared to process a string up to the maximum allowable size of 4096
characters.
If, when the dialog is processed, textvar is not defined or its value is not
valid for a string, the field contents are initialised to an empty string.
If the user changes the content of the text field, the system variable
%DLOGCHANGED is set to TRUE. Note, however, that selecting the default
or preselected value does not affect the value of %DLOGCHANGED. In
247
TSL Reference
addition, if, after editing a text field the user returns to the original
value, %DLOGCHANGED is not updated.
Text substitution is performed on size_spec, label and the values given
with the SENSITIVE, READONLY, ALLOWNULL, NULL_ERR_MSG, MAXLEN,
XPOS, YPOS, XADJUST, YADJUST and LABELGAP attributes.
Activation
Multiline text items cannot be made active, but they are validated when
the user submits the dialog.
Sensitivity
The SENSITIVE attribute can be used to define whether or not the
multiline text item can be selected or not. If it is insensitive, its contents
cannot be modified or selected.
The READONLY attribute is used to define whether or not the contents of
the multiline text item can be changed. This defaults to FALSEthat is,
the multiline contents of the text field can be changed by the user. The
difference between an insensitive multiline text item and a readonly
multiline text item is that the readonly multiline text item can be
selected and its contents copied to another text field.
Positioning
The position of the multiline text item can be set by TSL or by using the
positioning attributesXPOS, YPOS, and so on.
Validation
When the dialog is submitted (by pressing a button or activating an
active dialog item) ASKDIALOG can test the values of multiline text items
for NULL values, and not allow ASKDIALOG to return until a non-NULL
value is entered for the multiline text item. This is done by setting the
ALLOWNULL attribute to an expression that evaluates to FALSE. By
default the ALLOWNULL attribute is set to TRUE. The error message
generated can be determined by TSL, or you can set it yourself using
the NULL_ERR_MSG attribute.
TSL generates an error and exits if readonly is true and data validation
failsthat is, ALLOWNULL evaluates to FALSE and the multiline text field
is set to NULL.
In addition, the maximum length of the string that may be put in the
multiline text items can be defined using the MAXLEN attribute. If this is
defined, TSL prevents users from typing strings which are longer than
the value associated with this attribute.
Examples
DIALOG MULTITEXT(40,5) notes1 "Experiment Notes" \
READONLY = TRUE, \
ALLOWNULL = FALSE, \
MAXLEN = 200, \
XPOS = 3c, YPOS = 4c, \
XORIGIN = RIGHT, YORIGIN = CENTRE
This creates a readonly multiline text dialog item which has 40 columns
and 5 rows. TSL does not allow strings greater than 200 characters in
length to be entered in this dialog nor does it allow null values.
249
TSL Reference
DIALOG
OPTION
Arguments
stringvar = TQL_variable_name
label = quoted_string
choice_items = quoted_string { , quoted_string }
| query_buffer_expansion
query_buffer_expansion = column_name [/ count ]
count = integer
option_attributes = option_attribute { , option_attribute }
option_attributes = ACTION = quoted_string
| SENSITIVE = boolean_attribute
| position_attribute
Description
This dialog item allows the user to make a choice from an enumerated
list of options which are displayed in a menu-pane. Only the value for
the current selection is displayed in the dialog area. Other choices are
viewed by displaying the menu.
The choice is represented by a string. No other data types may be used
with this dialog item.
The list of choices may be specified in one of two ways:
If, at the time that the dialog is processed, stringvar is not defined or
does not have a valid value, the first item is selected.
If the user makes a selection from the list of items, the system variable
%DLOGCHANGED is set to TRUE. Note, however, that selecting the default
or preselected value does not affect the value of %DLOGCHANGED.
Text substitution is performed on label, choice_items and the values
given with the ACTION, SENSITIVE, XPOS, YPOS, XADJUST, YADJUST and
LABELGAP attributes.
Activation
If an ACTION attribute is defined, the dialog item is made active
whenever the value of the option menu is changed. If the dialog item is
made active, the value of the ACTION attribute is stored in the variable
%BUTTONVAL and TRUE is stored in the %DIALOGVAL variable.
Sensitivity
The option menu dialog item can use the SENSITIVE attribute. An
insensitive OPTION can not be selected and appears greyed out.
Positioning
The attributes, XPOS, YPOS, and so on can be used to override or modify
TSLs default positioning of these dialog items.
Examples
DIALOG OPTION ingredient "Ingredient" "[ingred1]" \
"[ingred2]" "[ingred3]" "[ingred4]"
creates an option menu with four choices. Note how the actual choices
are obtained using text substitution.
QUERY DISPLAY param_name AS pname FROM setup
WHERE batch = [batch_no] ;
DIALOG OPTION parmchosen "Parameter to Plot" pname/10
creates an option menu with at most 10 items where the items are
obtained from a display query on the database.
DIALOG OPTION parmchosen "Parameter to Plot" pname/10 \
ACTION = "Parm Selected"
This creates an option menu, the contents of which are taken from the
query buffer. If an item is selected from the option menu, ASKDIALOG
251
TSL Reference
DIALOG
PANEL
Arguments
stringvar = TQL_variable_name
label = quoted_string
choice_items = quoted_string { , quoted_string }
| query_buffer_expansion
query_buffer_expansion = column_name [/ count ]
count = integer
panel_attributes = panel_attribute { , panel_attribute }
panel_attributes = ACTION = quoted_string
| SENSITIVE = boolean_attribute
| position_attribute
Description
This dialog item allows the user to make a choice from an enumerated
list of options which are permanently displayed in the dialog area. Each
has an indicator alongside which shows whether or not it is currently
selected. Only one choice may be selected at a time.
The choice is represented by a string. No other data types may be used
with this dialog item.
The list of choices may be specified in one of two ways:
253
TSL Reference
If, at the time that the dialog is processed, stringvar is not defined or
does not have a valid value, PANEL item is created with no item
currently selected.
If the user makes a selection from the list of items, the system variable
%DLOGCHANGED is set to TRUE. Note, however, that selecting the default
or preselected value does not affect the value of %DLOGCHANGED.
Text substitution is performed on label, choice_items and the values
given with the ACTION, SENSITIVE, XPOS, YPOS, XADJUST, YADJUST and
LABELGAP attributes.
Activation
If an ACTION attribute is defined, the dialog item is made active
whenever the value of the panel is changed or, if nothing was originally
selected, when a value is selected. When the dialog item is made active
the value of the ACTION attribute is stored in the variable %BUTTONVAL
and TRUE is stored in the %DIALOGVAL variable.
Sensitivity
The panel dialog item can use the SENSITIVE attribute. An insensitive
PANEL can not be selected and appears greyed out.
Positioning
The attributes, XPOS, YPOS, and so on, can be used to override or
modify TSLs default positioning of these dialog items.
Examples
DIALOG PANEL output_dest "Output destination" \
"Plotter" "Screen" "HPGL file"
creates a scrolling list with at most 10 items where the items are
obtained from a display query on the database.
DIALOG PANEL parmchosen "Parameter to Plot" pname/10 \
ACTION = "Parm Selected", \
This creates a panel whose values were taken from the query buffer. If
an item is selected from the list, ASKDIALOG validates any text dialog
items. If this is successful, ASKDIALOG returns and puts Parm Selected
in %BUTTONVAL and TRUE in %DIALOGVAL.
255
TSL Reference
DIALOG
SKIP
Arguments
nskip = integer
Description
The effect of this command is to ensure that the next nskip column
spaces of the dialog are left blank. If nskip is omitted, one column space
is skipped. This command is only meaningful for multi-column dialogs.
Text substitution is performed on nskip.
Examples
DIALOG SKIP
DIALOG SKIP(2)
DIALOG
SLIDER
(also
HSLIDER
and
VSLIDER)
Arguments
int_type = BYTE | SHORT | LONG
slider_type = SLIDER | HSLIDER | VSLIDER
size = integer
var = TQL_variable_name
label = quoted_string
min = integer
max = integer
attributes = attribute { , attribute }
attribute = ACTION = quoted_string
SENSITIVE = boolean_attribute
| position_attribute
Description
A slider allows the user to select a value between a specified minimum
and maximum by moving a slider bar along a scale. It may be used only
with integer data (TQL data types short or long). If no data type is
specified, long is assumed.
If slider_type is SLIDER or HSLIDER, the slider bar runs horizontally
across the dialog. If slider_type is VSLIDER, the bar runs vertically. If size
is present, it determines the length (in pixels) of the slider bar,
otherwise the length is defaulted by the underlying window system.
If, at the time the dialog is processed, var is undefined or its value is
not valid for the specified data_type, the slider is initialised to the
minimum value. If the value of the variable is out of range for the slider,
it is rounded to the minimum or maximum as appropriate.
If the slider is moved and a new value is selected, the system variable
%DLOGCHANGED is set to TRUE. Note, however, that selecting the default
or preselected value does not affect the value of %DLOGCHANGED.
Text substitution is performed on size, label, min and max and on the
values given with the ACTION, SENSITIVE, XPOS, YPOS, XADJUST,
YADJUST and LABELGAP attributes.
257
TSL Reference
Activation
If the ACTION attribute is defined, the dialog item is made active
whenever the value of the slider is changed. If it succeeds, the value of
the ACTION attribute is stored in %BUTTONVAL and TRUE in %DIALOGVAL.
Sensitivity
If the slider is insensitive, it cannot be selected or changed. By default,
a slider is sensitive.
Positioning
The position of the slider can be determined by TSL or defined using
the positioning attributes.
Examples
DIALOG VSLIDER(200) num_ticks "Number of ticks" 10 30 \
ACTION = "Changed Ticks" \
XADJUST = 3p, YADJUST = 5p
DIALOG SHORT SLIDER x_axis_min "X axis minimum" \
[minval] [maxval] \
SENSITIVE = FALSE
DIALOG
TEXT
Arguments
length_spec = display_length [, max_length ]
display_length = integer
max_length = integer
textvar = TQL_variable_name
label = quoted_string
attributes = attribute { , attribute }
attribute = SENSITIVE = boolean_attribute
| SECRET = secret_attr
| READONLY = boolean_attribute
| ALLOWNULL = boolean_attribute
| NULL_ERR_MSG = quoted_string
| RANGEMIN = TQL_variable_name |
TQL_constant |
quoted_TQL_expr
| RANGEMAX = TQL_variable_name |
TQL_constant |
quoted_TQL_expr
| RANGE_ERR_MSG = quoted_string
| position_attribute
secret_attr = TRUE
| FALSE
Description
A text item is an editable text field in which the user can enter any
character sequence. A text item may be used to display and edit data of
any type.
In addition to the standard data_type arguments, the DIALOG TEXT
command may take an AUTO type. This allows users to type any valid
TQL expression in a text field. The expression is then checked and
assigned to the appropriate data type.
A text field has a display width (the number of characters visible in the
field) and a maximum width (the number of characters that can be
entered in the field), which are determined by display_length and
259
TSL Reference
Positioning
The position of the dialog can either be set by TSL or defined by you
using the positioning attributes.
Secrecy
You may want to display an asterix (*) each time a character is entered
in a text field, for example, when passwords are entered. If the SECRET
attribute evaluates to TRUE, text entered in the TEXT field is not
displayed. The default value for this attribute is FALSE.
Validation
When the dialog is submitted, the ASKDIALOG command can check for
invalid NULL values and values out of range in text fields.
If you wish TSL to test for NULL values, set ALLOWNULL so that it
evaluates to FALSE. You can specify the error message to display if a
NULL value is detected using the NULL_ERR_MSG attribute otherwise TSL
generates its own message.
Range checking is performed if either or both the RANGEMIN and
RANGEMAX attributes are defined. An error is reported if a value is
entered that is less than the RANGEMIN attribute or greater than the
RANGEMAX attribute. The error message generated can be defined using
the RANGE_ERR_MSG attribute otherwise TSL determines its own error
message.
TSL generates an error if the text field is readonly and its contents are
invalid.
Examples
DIALOG DATE TEXT(8) date1 "Start Date" \
READONLY = TRUE
DIALOG TEXT(15,60) outfile "Output File"
DIALOG COMPLEX TEXT(12) sensor_pos "Sensor Position" \
RANGEMIN = \[3,5], RANGEMAX = \[10,4]
261
TSL Reference
DIALOG
TIMERANGE
Arguments
rangevar = TQL_variable_name
label = quoted_string
attributes = attribute { , attribute }
attribute = ACTION = quoted_string
| SENSITIVE = boolean_attribute
| GRANULARITY = short
| MAXRANGES = short
| position_attributes
Description
This dialog item allows the user to define multiple time ranges within
one day.
The item is displayed as a horizontal bar with 24 points denoting hours
in the day. To define a time range, the user clicks on the bar and drags
the cursor to the beginning or end time of the range. As the user
defines a range, it is displayed below the barfor example, 9:4511:00.
Note that the user cannot overlap time ranges or join two existing time
ranges. However, he or she can modify an existing range by dragging
its beginning or end time markers and delete a range by dragging a
beginning or end time marker over the other marker that defines the
range.
The rangevar variable stores the ranges that have been selected as an
array of TQL times. The start and end times of each time range are
stored in consecutive pairs within the arraythat is, the first element is
the start of range 1, the second element is the end time of range 1, the
third element is the start of range 2, and so on. If the user does not
define any time ranges, rangevar is a one element array where the time
value is NULL.
If, at the time of creation, the rangevar variable contains an array of
times, these are used as an initial set of ranges and displayed by the
dialog item.
Note that, unlike most other dialog items, if the user creates a new time
range or changes an existing one, the value of %DLOGCHANGED is not
affected. Therefore, using this item in a dialog may give unexpected
results when used in conjunction with %DLOGCHANGED.
Text substitution is performed on label and on the values given with the
ACTION, SENSITIVE, GRANULARITY, MAXRANGES, XPOS, YPOS, XADJUST,
YADJUST and LABELGAP attributes.
Activation
If the ACTION attribute is defined, the dialog item is made active
whenever a new time range is created, modified or deleted. If the
dialog item is made active, the value of the ACTION attribute is stored in
the variable %BUTTONVAL and TRUE is stored in the %DIALOGVAL variable.
Sensitivity
If the SENSITIVE attribute evaluates to FALSE, the dialog item is
insensitivethat is, it is greyed out and the user cannot select it.
Accuracy and number of time ranges
The GRANULARITY attribute defines the smallest unit, in minutes, with
which the user can define the start and end times of a range. A unit is
always defined in minutes but may be greater than one hour. The
default is 15.
The MAXRANGES attribute defines the number of ranges the user can
define. The maximum number of ranges that can be defined is
dependent on the value of GRANULARITY. The default is 50.
Positioning
The position of the time range bar can either be determined by TSL or
defined by position_attributes.
Example
DIALOG TIMERANGE shop_hours "Opening Hours" \
GRANULARITY=5, MAXRANGES=2
263
TSL Reference
DIALOG
TOGGLE
Arguments
boolvar = TQL_variable_name
label = quoted_string
attributes = attribute { , attribute }
attribute = ACTION = quoted_string
| SENSITIVE = boolean_attribute
| position_attribute
Description
A toggle is a user interface item with two states, On and Off, and is
used for input/output of boolean data (TQL data type bool).
If, at the time the dialog is processed, the variable boolvar does not
exist or does not have a valid boolean value, the toggle is initialised to
the Off state.
If the user changes the toggle value, the system variable %DLOGCHANGED
is set to TRUE. Note, however, that selecting the default or preselected
value does not affect the value of %DLOGCHANGED.
Text substitution is performed on label and the values given with the
ACTION, SENSITIVE, XPOS, YPOS, XADJUST, YADJUST and LABELGAP
attributes.
Activation
If the ACTION attribute is defined and the value of the toggle changes,
ASKDIALOG submits the dialog. If this succeeds, ASKDIALOG returns and
stores the value of the ACTION attribute in the %BUTTONVAL variable and
TRUE in the %DIALOGVAL variable.
Sensitivity
The SENSITIVE attribute defines whether the toggle can be selected and
its value changed. By default, toggle items are sensitive.
Positioning
The position of the toggle can either be determined by TSL or defined
using the positioning attributes.
Example
DIALOG TOGGLE do_totals "Calculate Totals?" \
ACTION = "Calc Tot"
265
TSL Reference
EJECT
Description
When the output device is the TSL window, this command has no
effect. For output to a logical printer, a form-feed is placed in the
output stream.
ERROR
Arguments
error_message = quoted_string
Description
Displays an error dialog containing the specified error message and
suspends the application until the dialog is dismissed. The error dialog
has a single OK button which is used to dismiss it.
If TSL is running in -nowindow mode, the message associated with the
ERROR command is written to the standard error output and TSL log file
and TSL continues to execute the program.
Text substitution is performed on error_message. The error message may
comprise multiple lines of text; newlines are denoted using the
character sequence \n.
Examples
ERROR "No data is available for parameter [PARM]"
ERROR "Test failed:\n Std.Deviation was out of range."
267
TSL Reference
EXPAND
Arguments
TSL_command = A TSL command line that may include text
expansion in any or all fields.
Description
Most TSL commands allow text substitution only in a limited set of
fields and arguments and text expansion is performed at the same time
as the command is executed. The EXPAND command performs all text
expansion before the command line is executed and allows text
expansion to be used in any field and argument of the command.
Using text substitution to assign values to variables within a command
provides a powerful programming tool which, if used correctly, enables
you to create more flexible programs that are easier to maintain.
Example
MENU 1 "Database"
MENU 1-1 "Open" ACTION = "Open"
MENU 1-2 "Close" ACTION = "Close"
MENU 1-3 "Drop" ACTION = "Drop"
MENU 1-4 "Exit" ACTION = "Exit"
REPEAT
ASKMENU
IF NOT %MENUVAL = "Exit"
EXPAND CALL proc_[%MENUVAL] ()
ENDIF
UNTIL %MENUVAL="Exit"
creates a menu system and, depending on the users selection from the
menu, calls one of three procedures, defined elsewhere in the script
proc_Open, proc_Close or proc_Drop. The procedure called depends
on the value of %MENUVAL which holds the selected menu options
ACTION string. This variable forms part of the procedure name which
will be expanded before the CALL command is executed.
FILL
Description
When fill mode is enabled (FILL ON), text output using the PRINT,
PRINTLN or textline (') commands is output in a paragraph format.
Words are collected from input text lines and assembled into an output
text line until a word cannot fit on that line. At that point the assembled
text is output followed by a newline. Multiple spaces between words
are collapsed to single spaces (unless justification is also enabled, see
JUSTIFY). New lines in the input text are not significant except that an
empty input text line denotes the end of the paragraph and causes the
current partially assembled output line to be flushed, followed by a
newline. When fill mode is disabled (FILL OFF), each input text line
generates one output text line. The spacing in the output line is the
same as in the input line (unless justification is enabled). Initially fill
mode is disabled.
FILL on its own is equivalent to FILL ON.
Note that when table mode is enabled (see TABLE), fill mode is
temporarily disabled until table mode is turned off.
Example
FILL ON
'This example
illustrates
'the use of fill mode. Note that multiple spaces are
'collapsed to a single space
'& line breaks are ignored. Note also that words which
'do not fit on the current line are
'carried over in their
entirety onto the following
'line.
269
TSL Reference
FIRST
Description
Move to the first row in the query buffer. If the query buffer is currently
empty, the cursor position becomes invalid.
GRAPH
CURSOR
Description
The GRAPH CURSOR command enables a graphics cursor on the current
graph. The cursor changes to a small crosshair when the user moves the
pointer over the graphics canvas. The application waits till the user
clicks Select (normally the left mouse button) on the canvas.
The position of the cursor is translated to data coordinatesthat is, the
values for X and Y data that would cause a point to be plotted at that
position. The coordinates are then stored in the TQL variables %XVAL,
%YVAL and %ZVAL The values are always real numbers.
If the user does not click on the current graph or the graph does not
support cursors, the variables are set to NULL.
If no graphics canvas exists, a CANVAS ON command is executed
automatically. If no graph exists, a default graph is created
automatically.
271
TSL Reference
GRAPH
DRAW
Description
The GRAPH DRAW command passes the query to Kingfisher where it is
executed and the resulting data is plotted on the current graph. The
query may span several lines of the script file and must be terminated
by a semi-colon. The query is limited to 2048 characters in length. Text
substitution is performed on query before it is passed to Kingfisher.
If the current graph does not contain any data, the dataset retrieved by
this command is the primary dataset. Any subsequent GRAPH DRAW
commands will generate secondary datasets which will be overlaid on
the graph or drawn on secondary Y axis as defined by the graphs
property space.
The current graph must be the last graph that was created otherwise an
error occurs.
If the TQL Server detects an error during the parsing or execution of the
query then, if ABORT mode is currently enabled, the TSL application
prints an appropriate error message and exits; otherwise, if ABORT mode
is currently disabled, the script continues execution. The special
variable %QOK is set TRUE or FALSE depending on whether the query
was executed successfully or not. If an error occurred, the variables
%QERR, %DERR and %FERR are set with the appropriate error codes. In
addition the variables %QMSG, %DMSG and %FMSG are set with the
appropriate error messages.
The TQL variable %GRSTATUS is set to one of the following values after
the execution of this command:
Value
Description
11
273
TSL Reference
GRAPH
FORMAT
Arguments
format = filename
Description
The GRAPH FORMAT command is used to load a graph format into the
current graph or to save the format of the current graph.
If the command is followed by the LOAD modifier, or by no modifier, the
command reads the specified format file and sets the properties of the
current graph. The format file must have been created by Kingfisher or
by a GRAPH FORMAT SAVE command. The format file contains a list of
property-value specifications which are used to set the property space
of the current graph.
If the current graph contains datathat is, a GRAPH DRAW command has
been executedand canvas graph edit mode is not enabled, the graph
is destroyed. If edit mode is enabled, the graphs property space is
changed and the graph is automatically redrawn.
The graph format is searched for first in the directories on the path
specified by the environment variable KF_FORMAT_PATH, in the users
private graph directory, $TQL_CLIENT_DIR/etc/graphs/user_name,
and then in the shared directory,
$TQL_CLIENT_DIR/etc/graphs/shared.
If the command is followed by the SAVE modifier, the command saves
the property space of the current graph under the named format in the
users private directory. This facility can be used to save users
preferences.
After execution of the command the TQL variable %GRSTATUS is set to
one of the following:
Value
0
Description
The command was executed successfully.
Value
Description
Format names are not case dependent and are limited to 14 characters
in length. Text substitution is performed on format.
If no graphics canvas exists a CANVAS ON command is executed
automatically. If no graph exists, a default graph is created
automatically.
Example
GRAPH FORMAT LOAD spectra
275
TSL Reference
GRAPH
POSITION
Arguments
geometry = x_position y_position width height
Description
The GRAPH POSITION command sets the position and size of the current
graph.
The geometry controls the initial placement and size of the graph in the
canvas window. The geometry is specified as a sequence of four
numbers corresponding to the X position, Y position, width and height.
The position is specified as a percentage of the canvas with 0,0 at the
top left; the size is specified in percentage of the canvas. Any or all of
the numbers can be replaced by an asterisk indicating that the default
position or size is to be used. The default is 0 0 100 100.
Text substitution is performed on geometry.
If the current graph contains datathat is, a GRAPH DRAW command has
been executedand canvas graph edit mode is not enabled, the graph
is destroyed. If edit mode is enabled, the graphs position is changed
and the graph is automatically redrawn.
If no graphics canvas exists, a CANVAS ON command is executed
automatically. If no graph exists, a default graph is created
automatically.
Example
GRAPH POSITION 0 0 50 100
GRAPH
PROPERTY
Arguments
property_value_list = property[/qualifier]=value
[ property_value_list ]
property_var_list = property[/qualifier]=TQL_variable_name
[ property_var_list ]
Description
The GRAPH PROPERTY command is used to set or get the values of the
property space which controls the format of a graph in the graphics
canvas.
If the command is followed by the SET modifier, or by no modifier, the
command sets valuesthat is, it changes the graph format. The
property_value_list consists of one or more property names, each
followed by an optional qualifier, an equals sign and the appropriate
value for that property. The qualifier is a number introduced by a
forward slash. The value can either be a number, quoted string or a TQL
variable which has been set to either a number or a string.
The correct type and range of values for a property, as well as the
names of all graph properties, are described in Chapter 9 of the
Kingfisher Reference.
Text substitution is carried out on property_value_list.
If the command is followed by the GET modifier, the command obtains
values from the graph format. The property_var_list consists of one or
more property names, each followed by an optional qualifier, an equals
sign and then the name of a TQL variable. The qualifier is a number
introduced by a forward slash. The value of each property named is
retrieved and stored in the associated TQL variable. The value is either
an integer (long), a real or a string. If the variable does not exist it is
created automatically.
Text substitution is carried out on property_var_list.
277
TSL Reference
Gets the value of the linestyle property for the fourth dataset, which
controls the linestyle used for each dataset on a graph, and stores it in
the TQL variable lvar.
Help
The rightmost item on the TSL menubar is always labelled Help. This
menu item has a pull-down menu associated with it, with two items On
Revision and On Application.
Selecting the first item opens a small dialog which gives the revision of
TSL being used, the revision number of the TQL Server and the revision
of the user interface toolkit which was used to build this version of TSL.
Selecting the second item displays the contents of the current
application help file (as specified by the HELPFILE command) in a
dialog. If no help file has been specified, the Revision help is displayed
instead.
Each application defined dialog window also has a help button (at the
bottom right corner), which also displays a dialog displaying the current
help file.
279
TSL Reference
HELPFILE
Description
The contents of the file is displayed in either a pop-up help window or
an external editor when the user asks for Application Help from the
help menu, or presses the help button in a dialog.
Lines in a helpfile where the first significant character (that is, not a
space or a tab) is a # are ignored as comments. Thus a helpfile which
contained the lines:
# This is a comment
# This is another comment
This is # not a comment
The text of a help file should comprise no more than 2000 characters. If
the text is larger than this, only the first 2000 characters are shown.
Note that filename is not enclosed in quotes. Text substitution is
performed on filename.
If filename contains a / character, it is assumed to be the full pathname
of the help file otherwise the application searches for the help file as
follows:
Otherwise:
Otherwise:
directories on that path, the application does not search the directories
on TB_SPEC_PATH but generates an error.
The environment variable TSL_HELP_EDITOR specifies the path and
name of any external editor used to display the help files, for example
/usr/netscape/netscape.
The environment variable TSL_HELP_DEFAULTPAGE specifies the name
of the default file that is displayed if the current help file is not located,
for example $NPR_DIR/default_help.html.
281
TSL Reference
Highlighting
Indicator
Bold
@B
Underline
@U
Emphasis
@E
User1
@1
User2
@2
Once a particular attribute flag has been enabled all text is output with
the corresponding attribute until that flag is disabled. Any number of
attribute flags may be enabled at one time and they must all be disabled
individually.
The actual visual effect of enabling a particular attribute depends upon
the output device in use. For output to the TSL window:
Attribute
Effect
Bold
Underline
Underlined
Emphasis
User1, User2
Ignored
Example
'@BThis text is bold. @UThis text is underlined and
'bold. @BThis text is underlined only. @UThis text is
'not highlighted.
283
TSL Reference
IF,
ELIF,
ELSE,
ENDIF
Arguments
if_expression = TQL_expression
elif_clause = ELIF elif_expression
commands
[ elif_clause ]
else_clause = ELSE
commands
elif_expression = TQL_expression
Description
The if_expression is evaluated. If it evaluates to TRUE, the commands
following the IF up to the next ELIF, ELSE or ENDIF are processed after
which all lines up to the matching ENDIF are skipped.
If the if_expression evaluates to FALSE, the lines up to the next ELIF,
ELSE or ENDIF are skipped.
If ENDIF is encountered, processing continues with the next line.
If ELSE is encountered, the lines following the ELSE are processed until
the ENDIF is reached.
If an ELIF is encountered, the elif_expression is evaluated. If it evaluates
to TRUE, the lines following the ELIF are processed up to the next ELIF,
ELSE or ENDIF after which any further lines up to the ENDIF are
skipped. If the elif_expression evaluates to FALSE, the lines are skipped
up to the next ELIF, ELSE or ENDIF which is then processed as above.
Text substitution is performed on each of the TQL expressions before
evaluation. The if_expression and each elif_expression must evaluate to a
boolean result otherwise an error is generated. A NULL value for an
expression is treated equivalent to FALSE.
IF constructs may be nested to any level. Note that each IF construct
must be entirely contained within a single script file. Thus, for example,
285
TSL Reference
IFOK
Arguments
elif_clause = ELIF elif_expression
commands
[ elif_clause ]
else_clause = ELSE
commands
elif_expression = TQL_expression
Description
The behaviour of the IFOK command is identical to that of the IF
command except that the commands following the IFOK up to the next
ELIF, ELSE or ENDIF are executed only if the last QUERY command did
not generate an error.
This command is only useful if abort mode is disabled, otherwise the
application aborts when an error is detected in the QUERY.
Example
QUERY OPEN kings ;
IFOK
SCRIPT kings.tsl
ELSE
ERROR "Could not open Kings database"
ENDIF
INFO
Arguments
info_message = quoted_string
Description
When info_message is present, that message is displayed to the user.
The message is displayed in a dialog and may contain multiple lines of
text. If TSL is running in -nowindow mode, the message associated with
the INFO command is written to the standard error output and TSL log
file and TSL continues to execute the program.
Text substitution is performed on info_message. Newlines can be placed
in the message using the character sequence \n.
If info_message is not present, the current information message (if any)
is closed.
The user may dismiss the information dialog explicitly using the OK
button.
Examples
QUERY SELECT PARM# FROM RAWDATA ;
INFO "Selecting data for parameter [PARM#]"
# Pop down the current dialog
INFO
287
TSL Reference
JUSTIFY
Description
When justification is enabled (JUSTIFY ON) extra spaces may be
inserted between words in the output to ensure that the right margin of
the text is justified.
When justification is disabled (JUSTIFY OFF) a ragged right margin is
produced.
JUSTIFY on its own is equivalent to JUSTIFY ON.
KFPROC
Arguments
procname = filename
Description
Procedure names are not case dependent and are limited to 14
characters in length. Text substitution can be performed on procname.
The procedure is searched for first in the directories on the path
specified by the environment variable KF_PROC_PATH, then in the users
private procedure directory,
$TQL_CLIENT_DIR/etc/procedures/database.user_name, and then in
the shared directory,
$TQL_CLIENT_DIR/etc/procedures/database.shared.
The special variable %GRSTATUS is set after the execution of the
procedure to indicate whether the procedure succeeded or failed. This
variable may take the following integer values:
Value
Description
A TQL error was detected during the execution of the procedure. The actual error was reported by the Kingfisher server
if the canvas was in the default mode.
The procedure could not be executed at present as Kingfisher was executing on behalf of another TSL application.
289
TSL Reference
LAST
Description
Move to the last row in the query buffer. If the query buffer is currently
empty, the cursor position becomes invalid.
291
TSL Reference
LENGTH
Arguments
length = integer
Description
The default printer page length is reset to length lines. The new page
length takes effect AFTER the line immediately following the command.
Thus even if the page length is reduced to a length below the current
line number the next line is printed on the current page before a page
is ejected.
If length is less than or equal to 2, the command is silently ignored.
The initial page length is 65 lines.
Text substitution is performed on length.
MARGIN
Arguments
left_margin = integer
right_margin = integer
Description
left_margin specifies the default column position of the first character
after the left margin. It must be at least 1, smaller values are silently
rounded up to 1. right_margin specifies the default column position of
the last character before the right margin. In other words, the margin
command really specifies the range of columns on which text is printed.
If right_margin is omitted or is less than left_margin, only the left
margin is set and the right margin is unchanged. The new margins take
effect on the next line to be printed. Initially there is a margin of 4
characters on the left and 1 character on the right. So, for example, with
a terminal window of width 80 the initial margin positions are 5 and 79.
When using pagestyles, the margins can be set using the PAGESTYLE
command.
Text substitution is performed on left_margin and right_margin.
Examples
MARGIN 2,78
293
TSL Reference
MENU,
MENU SKIP
Arguments
menu_id see below
menu_label = quoted_string
menu_accelerator = standard Xt keysym definition
menu_accelerator_label = quoted_string
attributes = attribute { , attribute }
attribute = ACTION = quoted_string
| SENSITIVE = boolean_attribute
Description
menu_id identifies the position of the menu item in the menu hierarchy.
For a top level menu item (that is an item whose label appears on the
menu bar of the application) the menu-id is a single integer giving the
position in the menubar. Items are numbered starting from the left,
starting with 1. Each item on the menubar may have up to four levels of
pull-down menus associated with it. For a menu item appearing in the
nth level of pull-down menus the menu-id comprises a dash-separated
sequence of n+1 integers. The last integer in this sequence gives the
position of the item in the menu-pane in which its label appears. The
preceding characters give the menu-id of the item in the higher level
menu from which the menu-pane was generated. By default, a menu
pane at any level of the hierarchy may contain at most 20 items.
However, this limit may be changed using the maxMenuItems
application resource. Menu items may be defined in any order. If a
menu-id is used in more than one MENU command, the last definition
takes precedence.
The menu_label can contain the special character @ to indicate a
mnemonic for the menu entry. The first occurrence of the character
after the @ is taken as the mnemonic and is underlined in the menu,
thus the label Print @Report underlines the R in Report and the
label Print Repo@rt underlines the r in Print.
295
TSL Reference
Examples
MENU 1 "File" ACTION = "File"
defines the first and second items on the pull-down menu pane
associated with the second item on the menubar. The entries have
mnemonics O and C. The Open menu item can not be selected if the
variable already_open is set to TRUE. Similarly the Close menu item
can not be selected if the variable already_open is set to FALSE.
MENU 2-1-1 "Open Exclusive" "Ctrl<Key>X" "Ctrl-X" \
ACTION = "Open Exclusive"
MENU 2-1-2 "Open Shared" ACTION = "Open Shared"
defines two items in the cascading menu associated with the menu item
with menu-id 2-1. The first has an accelerator of Ctrl-X defined
MENU 3-1 "Open Database [UPC(dbname)]" ACTION = "OPEN"
MORE
Description
When paging mode is enabled (MORE ON), output to the terminal
window is paused after each screenful and the prompt "--More--" is
displayed. If the space-bar is pressed, the output advances by another
screenful. If return is pressed, the output advances by a single line.
If TSL is executing a REPEAT loop, pressing q in response to the
"--More--" prompt causes that loop to be abandoned and control
transfers to the first line after the end of the loop. This behaviour can
be modified by using the NOTRAP clause to the REPEAT command (q.v).
Outside of a loop pressing q has no effect.
If paging mode is disabled (MORE OFF), when a screenful of output is
produced the terminal window scrolls automatically without pausing.
MORE on its own is equivalent to MORE ON.
297
TSL Reference
NEXT
Description
Move forwards one row in the query buffer. If the cursor was already
positioned at the last row, it becomes invalid.
PAGESTYLE
Arguments
attributes = attribute { , attribute }
attribute = STARTLINE = integer
| ENDLINE = integer
| HEADLINE = integer
| FOOTLINE = integer
| HEADER = quoted_string
| FOOTER = quoted_string
| LENGTH = integer
| LMARGIN = integer
| RMARGIN = integer
Description
The PAGESTYLE command can be used to set the page style attributes of
the current pagestyle. The meanings of the attributes are:
Attribute
Meaning
STARTLINE
ENDLINE
HEADLINE
FOOTLINE
HEADER
FOOTER
LENGTH
LMARGIN
RMARGIN
299
TSL Reference
Default value
STARTLINE
ENDLINE
HEADLINE
No default.
FOOTLINE
No default.
HEADER
No default.
FOOTER
No default.
LENGTH
LMARGIN
RMARGIN
This sets a pagestyle with a header string in line 1 and defines the
header string to be Status of Kings.
PAGESTYLE LENGTH=60, \
ENDLINE=57, \
FOOTLINE=59, \
FOOTER='%pagenum::"Page %d"'
This defines a page which is 60 lines long and text stops being printed
on line 57. A footer has also been defined which uses the special
variable %PAGENUM to print the number of the current page.
301
TSL Reference
PREV
Description
Move back one row in the query buffer. If the cursor was already
positioned at the first row, it becomes invalid.
PRINT,
PRINTLN
Arguments
print_arg = quoted_string
| data_item :: format
data_item = TQL_variable_name | column_name
format = quoted_string
Description
These commands provide a more powerful means of performing
formatted output than text substitution in output lines. They should be
used when writing reports in TSL.
The PRINT and PRINTLN commands print either a string literal, if a
quoted string is specified, or a set of data items in the specified format.
C style escape sequencesfor example, \n for newline and \t for
tabsare allowed in quoted_string and format.
The output goes to the screen or logical printer as controlled by the
PRINTER command. The output is formatted within the page length and
margins defined either by the current pagestyle if reporting is enabled
(using the REPORT ON command) or using the default values set using
the LENGTH and MARGIN commands.
The PRINTLN command outputs the specified data followed by a
newline; the PRINT command does not output a newline.
The data_item can be the name of a TQL variable, the name of a
column that has been retrieved by a QUERY command or an
expression. The item is evaluated and is printed according to the
format. Text substitution can be done to generate a variable for
data_item.
Format strings can contain any printable characters and must contain a
single format designator except in the special case of complex numbers
and dates and times which are described below. A format designator is
introduced using the percent sign. Following the % you can include:
303
TSL Reference
An optional decimal point which separates the field width from the
next digit string.
Description
Description
Character
Description
Real (decimal) number in the style #.####e## (scientific notation), where one digit appears before the decimal point and the number of digits after the decimal
point is the fraction length. The format character E can
be used to obtain an upper case E. The data type
should be shortreal or real.
Character.
String.
Description
The real component of the complex number is formatted using the same rules as the f format character.
The imaginary part of the complex number is formatted using the same rules of the f format character.
If the data item is a date or time, the following characters can be used:
Character
Description
305
TSL Reference
Character
Description
The full month name for the current locale (for example, January).
The highlighting indicators @B, @E, @U, @1 and @2 can be used in the
PRINT and PRINTLN format strings (see Highlighting on page 282).
Examples
PRINT aDate::"@UNett Variance Report for %d/%m/%y@U"
PRINTLN aCust::"%s" "used [total] kW"
PRINTLN
307
TSL Reference
PRINTER
Arguments
attributes = attribute { , attribute }
attribute = OUTPUT = ( PRINTER | PIPE | FILE )
| FILENAME = quoted_string
| COMMAND = quoted_string
| APPEND = ( TRUE | FALSE | YES | NO )
Description
After execution of a PRINTER ON command, all text output is sent to the
current printer (which may be a printer, file or pipe) rather than the TSL
terminal window, until a PRINTER OFF is executed. The current printer
defaults to the output destination selected when the TSL interpreter was
started, and is set using the SETPRINTER command.
If the printer is turned on and off several times during the execution of
a script, a separate print job is created each time.
The PRINTER command is also used to define the attributes of the
current printer (see SET-PRINTER on page 331). The destination of the
output is specified using the OUTPUT attribute.
If the destination is a file, the OUTPUT attribute should be defined as
FILE and the name of the file should be defined with the FILENAME
attribute. Normally when a file is opened for the first time, TSL
overwrites the file. However, if you would prefer to append your output
to the end of the file, define the APPEND attribute as TRUE.
If the destination is either a command or a printer, OUTPUT should be
defined appropriately and the command executed should be defined
with the COMMAND attribute.
Initially the printer is turned off, so all output is sent to the TSL main
window.
This command also redefines a special TQL macro %OUTPUT. This is
defined to the name of the current output destination. When output is
going to the screen (PRINTER OFF or no logical printer specified)
%OUTPUT is defined as screen. When the PRINTER is on and the logical
309
TSL Reference
QUERY
Description
The query may span several lines of the script file and must be
terminated by a semi-colon. The query is limited to 6000 characters in
length. Text substitution is performed on query before it is passed to the
TQL Server.
Queries executed in this fashion may be grouped into three broad
categories:
Those that execute other TQL client applications (for example, RUN)
The result of the query can subsequently be tested using the IFOK
command (q.v) or by testing the value of the %QOK variable.
Note that all of the data returned by the query must fit in the query
buffer. If it does not, the query fails and produces the query error
Overflow in query buffer. The size of the query buffer can be changed
using the buffersize command-line argument (see page 168).
Examples
QUERY DISPLAY test_date, test_result FROM tests ;
places the results of the query in the query buffer and sets %ROWS to the
number of rows retrieved (provided %DISPLAY is TRUE).
QUERY SELECT test_date, test_result FROM tests
WHERE test_date > \[24/06/91] ;
creates a result relation but has no effect on the query buffer; %ROWS is
set to 0.
QUERY RUN myprog ;
runs the TQL client program myprog. Clears the query buffer; %ROWS is
set to 0.
QUERY SET %DISPLAY FALSE ;
QUERY MAXIMUM test_result AS max_result FROM tests ;
QUERY SET %DISPLAY TRUE ;
The Maximum query has no effect on the query buffer as the TQL
system variable %DISPLAY is FALSE.
311
TSL Reference
REPEAT,
FORALL,
FOR,
UNTIL
or:
REPEAT [ NOTRAP ]
commands
FOR number
or:
REPEAT [ NOTRAP ]
commands
UNTIL TQL_expression
Arguments
number = integer
Description
The REPEAT command provides three different loop constructs. In each
case, the commands that form the body of the loop are executed
repeatedly until a termination condition is met or the BREAK command
is executed.
When REPEAT FORALL is used, the loop body is executed as long as
the current query buffer cursor position remains valid. To avoid looping
indefinitely the loop body must therefore contain either a NEXT or PREV
command to increment or decrement the query buffer cursor position.
REPEAT FOR number is equivalent to REPEAT FORALL except that
no more than number iterations of the loop are performed. Text
substitution is performed on number.
Note that in each case the termination condition is checked only at the
end of the loop so the commands which form the body of the loop are
executed at least once.
The NOTRAP modifier
If during the execution of the loop, the user presses q in response to a
--More-- prompt (see MORE on page 297), the usual behaviour is to
abort the loop and continue execution with the command immediately
after the end of the loop. Specifying the NOTRAP modifier at the start of
the loop prevents the loop from being aborted in this fashion. For
nested loops the loop aborted in response to q is the innermost loop
for which NOTRAP was not specified.
If paging mode is disabled, NOTRAP has no effect.
REPEAT loops may be nested to a maximum depth of 20. The start and
end of a loop must be in the same script file. Thus it is not permissible
to begin a loop within an included file and to end it in the including
file.
Examples
REPEAT
'[exp_no] [exp_result]
NEXT
FORALL
prints the values of exp_no and exp_result for each row in the query
buffer.
REPEAT
'[exp_no] [exp_result]
NEXT
FOR 10
prints values from the query buffer as long as the value of exp_no is not
greater than 20.
DECLARE batch_no 1
REPEAT
313
TSL Reference
REPORT
Arguments
attributes = attribute { , attribute }
attribute = FIRST = 1 30
| LEFT = 1 30
| RIGHT = 1 30
| DEFAULT = 1 30
Description
The REPORT command can be used to switch report mode on and off, or
to define the attributes of the current report style. The current report
style is set using SETREPORT.
Reporting is enabled using the REPORT ON command. When this
command the variable %PAGENUM is set to 1. This variable is updated as
more pages are printed and can be used in a pagestyles HEADER or
FOOTER attributes (see PAGESTYLE on page 299). The %PAGENUM variable
is dropped when reporting is disabled using the REPORT OFF command.
LEFT and RIGHT define the page style to use for left (even numbered)
and right (odd numbered) pages, respectively. FIRST defines the style
for the first page, and DEFAULT gives the pagestyle use for any page
whose style is otherwise undefined.
If the current page is odd, but it is not the first page, use the value
of the RIGHT attribute if that is defined, otherwise use the value of
the DEFAULT page. If that is not defined, use pagestyle 1.
Finally, if the current page is even, use the value of the RIGHT
attribute if that is defined, otherwise use the value of the DEFAULT
page. If that is not defined, use pagestyle 1.
315
TSL Reference
Examples
REPORT FIRST = 1, DEFAULT = 2
This sets the pagestyle to be 1 for the first page, and 2 for all others.
REPORT FIRST = 3, LEFT = 4, RIGHT = 5
REPORT ON
This sets the pagestyle for the current report and turns report mode on.
RETURN
Description
Causes TSL to return from a TSL procedure immediately (that is, before
reaching the ENDPROC command).
317
TSL Reference
SCREEN
Description
Moves the cursor to the bottom of the terminal area, displays a
--More-- prompt and waits until the space-bar is pressed. The
terminal area is cleared and the output position is reset to the top of the
terminal window.
SCRIPT
Description
The TSL interpreter reads and processes commands from the specified
file. When the end of the script file is reached, execution continues with
the line immediately following the SCRIPT command.
Note that filename is NOT enclosed in quotes. Text substitution is
performed on filename.
If filename contains a / character, it is assumed to be the full pathname
of the script file; otherwise the application searches for the script file as
follows:
Otherwise:
319
TSL Reference
Note that within any script file any multi-line commands (IF, REPEAT,
SWITCH, QUERY,DEFPROC) must be completely contained in that file. So
for example, it is not permitted to start an IF command in one file with
the ENDIF appearing in an included script file.
Examples
SCRIPT script1.tsl
If the script script1.tsl was not found, TSL looks for the encrypted
file script1.tse.
SCRIPT script1
TSL first looks for the file script1. If this is not found, TSL looks for
the file script1.tsl. Finally, if this is not found, TSL looks for the
encrypted file script1.tse.
SCRIPT /users/tsluser/scripts/script1.tsl
SELECT
Arguments
text_label = quoted_string
choice_items = { quoted_string } | query_buffer_expansion
query_buffer_expansion = column_name [/ count ]
count = integer
Description
Pops up a list selection dialog whose scrolled list contains the
choice_items and whose text field is labelled with text_label and
suspends the application until the dialog is dismissed. The selection
dialog has buttons labelled OK and Cancel. If the user presses the OK
button and the text field is not empty, the special variable %SELECTVAL
is set to the value otherwise it is set to NULL.
In addition, if the OK button is pressed, %DIALOGVAL is set to TRUE and
%BUTTONVAL is set to OK. If the Cancel button is pressed, %DIALOGVAL
is set to FALSE and %BUTTONVAL is set to Cancel
If you do not want the %DIALOGVAL and %BUTTONVAL variables to be set,
set the environment variable TSL_13_COMPATIBILITY to 1.
The list of choices may be specified in one of two ways:
321
TSL Reference
Example
QUERY DISPLAY fullname FROM kings ;
SELECT "King" fullname
SELECTFILE
Arguments
file_label = quoted_string
filter = quoted_string
base_dir = quoted_string
Description
Pops up a file selection dialog whose text field is labelled with
file_label.
If filter is specified, this is used as the filter pattern in the dialog
otherwise no filter is used. The filter is used to limit the files that are
shown. For example, a filter *.tsl only shows files that end in the
string .tsl.
If base_dir is specified, the current working directory of the dialog is set
to this value else the actual current directory is used.
The file selection dialog has buttons labelled OK, Filter and Cancel. If
the user presses the OK button and the file text field is not empty or if
the user double clicks on a value in the files list, the special variable
%FILEVAL is set to the selected value otherwise it is set to NULL.
If the user presses the Filter button or double clocks on a value in the
directories list, the directory is rescanned using the current pattern.
If the OK button is pressed, %DIALOGVAL is set to TRUE and %BUTTONVAL
is set to OK. If the Cancel button is pressed, %DIALOGVAL is set to
FALSE and %BUTTONVAL is set to Cancel.
If you do not want the %DIALOGVAL and %BUTTONVAL variables to be set,
you should set the environment variable TSL_13_COMPATIBILITY to 1.
Text substitution is performed on file_label, filter and base_dir.
Example
SELECTFILE "Output File" "*.data" "/usr/spool/data"
323
TSL Reference
SET
Description
The SET command is used to set values in the specified list of TQL
variables. The command is followed by a comma-separated list of
variable names and TQL expressions.
The command should be used in preference to setting TQL variables
directly using the QUERY SET VAR construct, because TSL tries to
reduce the number of queries sent to the server by grouping several
SET commands together into one query.
Text substitution is allowed anywhere after the SET keyword.
Example
SET x x+1
SETBUFFER
Arguments
buffernum = 130
Description
The SETBUFFER command sets the current logical buffer number.
Subsequent BUFFER commands control attributes of the buffer, such as
the file name associated with it, and turn text buffering on and off. A
maximum of 30 logical buffers can be defined.
Text substitution is performed on buffernum.
Example
SETBUFFER 14
BUFFER FILENAME="BUFFER14.OUT"
sets the current logical buffer to 14. The BUFFER command defines the
buffer file as BUFFER14.OUT. TSL will overwrite the file on the first write
after opening.
325
TSL Reference
SETCANVAS
Arguments
canvas_number = 1 30
canvas_name = quoted_string
Description
The SETCANVAS command allows you to create and control multiple
canvasses from the same TSL application.
All canvas and graph commands apply to the current canvas. The
current canvas is identified by a number, a name or a combination of
the two. (The default value is 1 with no name.)
If the current canvas already exists, that canvas is attached and
subsequent graph and canvas commands will apply to it.
If the current canvas does not exist, it is created when the next graph or
canvas command is performed.
When using the SETCANVAS command to control multiple windows, it is
possible to determine information about each canvas without having to
store it in your application. When a canvas is created or attached to, it
is possible to find the number of graphs (if any) currently drawn in that
canvas, the graph that has the data focus and the graph that is selected
(that is, for which properties can be changed). This information is
available from the following variables:
%NUM_GRAPHS
%GRFOCUSSED
%GRSELECTED
and set the current graph identifier after setting the canvas identifier, for
example:
SETCANVAS 2
SETGRAPH [%GRFOCUSSED]
327
TSL Reference
SETDIALOG
Arguments
dialog_number = 1 200
dialog_name = string
Description
The default number of dialogs that may be defined at any one time is
200. However, this limit may be changed using the maxDialogs
application resource. All DIALOG (item), DIALOG SKIP and DIALOG
LAYOUT commands apply to the current dialog.
If no SETDIALOG command has been executed, the most recently
defined dialog is used.
Text substitution is performed on dialog_number and dialog_name.
Example
SETDIALOG 3
SETGRAPH
Arguments
graph_number = 1 50
Description
Up to 50 graphs may be defined at any one time. All GRAPH commands
apply to the current graph.
If no SETGRAPH command has been executed, graph 1 is used.
Text substitution is performed on graph_number.
Example
SETGRAPH 3
329
TSL Reference
SETPAGESTYLE
Arguments
stylenum = 1 30
Description
SETPAGESTYLE sets the current pagestyle number, to which subsequent
PAGESTYLE commands apply. TSL allows up to 30 pagestyles to be
defined, numbered from 1 to 30. Pagestyles define the appearance of
pages of reports, and are set using the PAGESTYLE command.
SETPRINTER
Arguments
printernum = 1 30
Description
SETPRINTER sets the current logical printer number, which can be
defined and turned on and off by subsequent PRINTER commands. TSL
allows up to 30 logical printers to be defined, numbered from 1 to 30.
After a PRINTER ON command, output is directed to the current printer
instead of to the screen.
This example sets the current printer to 25 and defines it to be the file
/tmp/log1. It also says that TSL should append to the file, instead of
overwriting it on the first write.
SETPRINTER 25
PRINTLN "\tStarting output to log file..."
PRINTER ON
PRINTLN "Testing"
PRINTER OFF
PRINTLN "\tWritten log message."
This sets the current printer to 25 (as defined earlier), prints a message
on the screen, outputs a message to the file and prints another message
on the screen.
331
TSL Reference
SETREPORT
Arguments
reportnum = 1 30
Description
SETREPORT sets the current report style, which can then be defined and
turned on and off using the REPORT command. TSL allows up to 30
report styles to be defined, numbered from 1 to 30.
SHELL
Arguments
system_commandsee below
Description
Text substitution is performed on system_command which is executed
using the operating system command shell as given by the SHELL
environment variable. If SHELL is not set, the Bourne shell sh is used.
The standard output, input and error of the command are redirected to
the TSL terminal window. Any output thus appears at the current
position in the terminal window. Commands that expect to read input
from the terminal should not usually be executed in this way as the TSL
terminal window does not support any line-editing characters (for
example, backspace).
If TSL is being used by a cron job, the terminal emulator that is to be
used commands executed by the SHELL command may be undefined.
This can be defined using the -term command-line argument. If the
terminal is not defined using the -term argument, the value of the TERM
environment variable is used or, if this does not exist, the default
terminalxterm.
The return value of the command executed using SHELL is stored in the
variable %STAT.
333
TSL Reference
STOP
Arguments
exitcode = 0, 1,
Description
Terminates the application. The TSL window is removed and the
application exits with an exit code of exitcode or 0 if exitcode is not
specified.
Text substitution is performed on exitcode.
SWITCH,
CASE,
OTHERWISE,
ENDSWITCH
Arguments
switch_expression = TQL_expression
case_expression = TQL_expression
Description
The TQL expression following the SWITCH is evaluated. All lines
following the SWITCH up to the next CASE or OTHERWISE are skipped.
The following procedure is then repeated until the matching ENDSWITCH
is found:
If the values are not equal then the lines up to the next CASE,
OTHERWISE or ENDSWITCH are skipped.
335
TSL Reference
SWITCH statements may be nested to any level. Note that each SWITCH
construct must be entirely contained within a single script file. Thus, for
example, it is not permissible for the SWITCH statement to appear in an
included file with the matching ENDSWITCH in the including file.
TABLE
Description
Table mode affects the way that text items are substituted and displayed
in output text.
If table mode is enabled (TABLE ON), an expanded text item is output
starting at the same column position as the text item appears within the
script file. If the expansion requires less space than the original text
item, it is right-padded with spaces. If the expansion requires more
space than the original item, any text immediately following the text
item may be overwritten. This mode allows reports which contain text
items to be produced in a tabular format with correct column
alignment. When calculating the position of a text item in the input
script, characters up to and including the text line indicator (') are
ignored.
If table mode is disabled (TABLE OFF) when a text item is expanded it is
output at the current output column position regardless of its position
in the script file. The expansion is stripped of any leading and trailing
spaces. This mode allows text items to be expanded naturally into freeformat text reports. When table mode is enabled, the current filling and
justification modes are saved. They are restored when table mode is
next disabled.
TABLE on its own is equivalent to TABLE ON.
337
TSL Reference
TELL
Arguments
promptany sequence of characters
Description
Outputs prompt to the terminal window followed by a new-line.
This command provides a means of sending output to the terminal even
when the main application output is diverted to the printer. It is
intended to be used either for prompting the user for input immediately
before executing an ASK command or for providing information and
error messages.
It is provided for backwards compatibility only. New applications
should use a dialog to obtain input from the user and use the ERROR
and INFO commands to display messages.
Terminal
Window
The terminal window is the area of the TSL main window immediately
below the menubar. All output which has not been diverted to the
printer appears here.
This area can be viewed as a window onto a larger buffer area. The
position of the window in the buffer is altered using the scroll bar to
the right of the window. Initially the window is positioned at the top of
the buffer area.
The size of the window and of the buffer area can be configured using
the X defaults database. (See the Application Resources section in this
Reference.) Depending upon the underlying window system it may be
possible to alter the height (but NOT the width) of the window whilst
TSL is running. It is not possible to increase the number of lines in the
window beyond the number in the underlying buffer. If an output line
is too long for the terminal width, the characters are automatically
wrapped onto the next line.
The TSL terminal window is designed to be used for output only. Thus
if the SHELL command or TQL RUN query is used to run commands in
the window which expect terminal input they may not perform as
expected. The environment variable TERM is set to tslwin for all
programs executed from the TSL application.
The window actually provides a partial emulation of a VT100 terminal.
The full terminfo description of the window is given here for
reference:
tslwin| Dumb terminal for TSL,
am, vt#3, mir, xon,
cols#80, lines#24, vt#3,
el=\E[K, ed=\E[J, home=\E[H,
bel=^G, cr=\r, cudl=\n, ind=\n,
bold=\E[1m, rev=\E[7m, dim=\E[5m, smul=\E[4m,
cup=\E[%i%p1%d;%p2%dH, hpa=\E[%p1%{1}%+%dG,
home=\E[H, hpa=\E[%p1%{1}%+%dG, ind=\n, rev=\E[7m,
sgr0=\E[0m, rmul=\E[0m,
sgr=\E[0%?%p1%p6%|%t;1%;%?%p2%t;4%;%?%p1%p3%|%t;
7%;%?%p5%t;5%;m%?%p9%t^N%e^O%;,
339
TSL Reference
Text Item
If the item is a valid TQL column name, and that name matches a
column name currently in the query buffer, then, provided the
current query buffer cursor position is valid, the value of that
column in the current row of the query buffer is used.
If the item does not meet any of the criteria above, it is assumed to
be a TQL expression and its value is obtained by evaluating the
expression on the server.
Printing description
Data type
Printing description
SHORTREAL, REAL
BOOL
STRING, CHAR
TIME
DATE
COMPLEX
341
TSL Reference
Text Output
Arguments
outputany sequence of characters
Description
Any line whose first non-space character is ' (single quote) is a text
output line. This means that the remainder of the line is treated as text
to be copied to the current output destination. Text substitution is
performed on the text before it is output.
The way in which the text is positioned in the output can be altered
using the FILL, JUSTIFY and TABLE commands.
Highlighting indicators (@B, @E, @U, @1 and @2) may be included in the
text to toggle highlighting in the output (see Highlighting on page 282).
Examples
'A simple text output line
'The range of values is from [minval] to [maxval]
'The @Blargest@B value for [parm_name] was [maxval]
TIMEOUT
Arguments
duration = integer
Description
This command defines how long TSL should wait for an action to be
initiated by a user when the ASKMENU or ASKDIALOG command is being
executed.
The TIMEOUT MENU command defines the timeout duration for the
ASKMENU command and the TIMEOUT DIALOG command defines the
duration for the ASKDIALOG command. The value duration, which is
defined in seconds, is the length of time that the application waits
before the timeout occurs.
If the defined timeout period expires, TSL quits, thus freeing a TQL
licence to be used by another customer.
If neither MENU or DIALOG are specified by the command, TSL assumes
that you are referring to MENU. If duration is not defined, the
appropriate timeout is cancelled.
Text substitution is performed on duration.
Examples
TIMEOUT MENU 120
This command instructs TSL to exit if a menu item is not selected within
120 seconds (2 minutes) after the start of an ASKMENU command.
TIMEOUT DIALOG 600
This command cancels the current time out period. Thus ASKMENU
commands will wait indefinitely until a menu item is selected.
343
TSL Reference
TITLE
Arguments
title = quoted_string
Description
The given string is used as the title of the main window. Text
substitution is performed on title.
Example
TITLE "TSL Signal Analysis Demo - user: [sysuser()]"
TOOL
Arguments
toolid = groupnum - position
groupnum, position = number
label = quoted_string
primary_bitmap = bitmap_file
active_bitmap = bitmap_file
attributes = attribute { , attribute }
attribute = ACTION = quoted_string
| SENSITIVE = boolean_attribute
Description
The TOOL command is used to either define the label positioned on
top of a group of tools or to define a tools bitmap(s) and attributes.
The first command given above is used to define the label of the tool
group numbered groupnum to be label.
The second command defines a tool in position of toolgroup to use the
bitmap file primary_bitmap as its inactive bitmap. Each tool must have
its ACTION attribute defined. When a tool is pressed, if the optional
bitmap active_bitmap is defined, the bitmap displayed is changed to
active_bitmap.
The values primary_bitmap and active_bitmap are bitmaps which are
searched for in the directories specified by the XBMLANGPATH
environment variable. See Icons on page 20 for a description of this
environment variable.
A tool is activated by pressing and releasing the tool whilst the mouse is
over the tool when an ASKMENU command is been executed. When a
tool is activated the ASKMENU command ends and the value associated
with the tools ACTION attribute is put in the %MENUVAL variable.
The sensitivity of the tool is defined by the SENSITIVE attribute.
Insensitive tools appear the same as sensitive tools but users cannot
select insensitive tools.
345
TSL Reference
Examples
TOOL 1 "Kingfisher"
TOOLBOX
Arguments
attributes = attribute {, attribute}
attribute = GRAVITY = ( NORTH | SOUTH | EAST | WEST )
| ROWCOLS = integer
| FRAME = ( TRUE | FALSE | YES | NO )
| GROUPGAP = dimension_unit_no_grid
| TOOLGAP = dimension_unit_no_grid
Description
The TOOLBOX command is used to define the attributes of a toolbox, for
example where it is positioned, and what the gap between each tool
should be. The meanings of the attributes are:
Attribute
Description
Default value
GRAVITY
EAST
Defines where the toolbox should be
placed. If this is set to NORTH then the
toolbox is positioned on top of TSLs
main scrollable window. Similarly a
value of SOUTH positions the toolbox
below TSLs main scrollable window, a
value of EAST positions the toolbox to
the left of TSLs main scrollable window and a value of WEST positions the
toolbox to the right of TSLs main
scrollable window.
ROWCOLS
FRAME
True
347
TSL Reference
Attribute
Description
Default value
GROUPGAP
TOOLGAP
Examples
TOOLBOX GRAVITY = NORTH, ROWCOLS = 2
TRANSFER
LOAD,
TRANSFER
UNLOAD
Arguments
table = name
file_or_pipe = filename | unix_command
Description
The TRANSFER LOAD command emulates the functionality of the
Kingfisher Transfer Tool in loading a database table from a file or pipe.
The format and other details of the transfer are controlled by the values
of the transfer property space which can be changed using the
TRANSFER PROPERTY command.
The TRANSFER UNLOAD command reads data from the specified table
and writes it to the specified file or pipe, creating the file if necessary. If
the file already exists it is overwritten.
Text substitution is performed on file_or_pipe.
The default format is delimited ASCII, with whitespace delimiter and a
linefeed row terminator.
After execution of the command, the TQL variable %XFSTATUS is set to
one of the following:
Value
Description
The end of file was encountered when not all the fields in a
row of the table had been read. The fields were set to null
and the row may be discarded.
The end of row was encountered when not all the fields in
a row of the table had been read. The fields were set to null
and the row may be discarded.
349
TSL Reference
Value
Description
In addition, the variable %XFROWS is set to the number of rows that were
successfully transferred and %XFDISCARD is set to the number of rows
discarded during the transfer. A row might be discarded either because
the row contains a null value where one is not allowed, or because the
row is not unique with respect to some index, or because an invalid
real number, integer (for example, 2,098 is too large for a BYTE), date or
time were written to the TQL Server.
Examples
TRANSFER LOAD spectra /tmp/spectra
TRANSFER
PROPERTY
Arguments
property_value_list = property=value [ property_value_list ]
property_var_list = property=varname [ property_var_list ]
Description
The TRANSFER PROPERTY command is used to set or get the values of
the property space which controls the execution of the TRANSFER LOAD
and TRANSFER UNLOAD commands. This property space is designed to
emulate the capabilities of the Kingfisher Transfer Tool.
If the command is followed by the SET modifier, or by no modifier, the
command sets valuesthat is, it changes the transfer configuration. The
property_value_list consists of one or more property names, each
followed by an equals sign and the appropriate value for that property.
The value can either be a number or a quoted string.
The correct type and range of values for a property, as well as the
names of all transfer properties, are described in Chapter 8 of the
Kingfisher Reference.
Text substitution is carried out on property_value_list.
If the command is followed by the GET modifier, the command gets
values from the transfer configuration. The property_var_list consists of
one or more property names, each followed by an equals sign and the
name of a TQL variable. The value of each property named is retrieved
and stored in the associated TQL variable. The value is either an integer
(long), a real or a string. If the variable does not exist it is created
automatically.
Text substitution is carried out on property_var_list.
Example
TRANSFER PROPERTY delimiter=";" terminator=0
351
TSL Reference
TRY, [PROGRESS],
RECOVER,
ENDTRY
Arguments
message = quoted_string
Description
The TRY/RECOVER/ENDTRY construct allows for the interruption of
potentially time-consuming operations and provides steps for recovery.
The user may be given feedback on the progress of the operation and
the opportunity to interrupt it with one or more progress dialogs.
The construct defines two blocks of commands. The first block defines
the commands to be attempted while the second block defines the
recovery procedure if the user stops the operation. TSL tries to execute
the first block of commands. If those commands are interrupted, the
commands in the second block are executed.
The optional PROGRESS command creates a progress dialog containing
two buttonsStop and Close. The Close button allows the user to
dismiss the dialog but continue the process. The Stop button lets the
user interrupt the process. When this button is selected, TSL executes
the recovery sequence of commands and resumes execution after the
outermost TRY/RECOVER block. If the user dismisses the dialog with the
Stop button, the special query variable %STOPPED is set to TRUE.
The progress message is displayed in the progress dialog. A message
may contain multiple lines of textnewlines can be placed in the
message using the \n character sequence.
If TSL is running in -nowindow mode, the message associated with a
PROGRESS command is written to the standard error output and TSL
continues to execute the program.
Text substitution is performed on message.
Example
TRY
PROGRESS "Extracting wafer data .."
QUERY OPEN wafer ;
QUERY DISPLAY * FROM rawdata ;
TRY
DECLARE aveval, maxval, minval
PROGRESS "Finding average value .."
QUERY DISPLAY average value AS aveval
FROM rawdata;
PROGRESS "Finding maximum value .."
QUERY DISPLAY maximum value AS maxval
FROM rawdata;
PROGRESS "Finding minimum value .."
QUERY DISPLAY minimum value AS minval
FROM rawdata;
'Average wafer test value is [aveval]
'Minimum wafer test value is [minval]
'Maximum wafer test value is [maxval]
RECOVER
SET aveval NULL, minval NULL, maxval NULL
CONFIRM "No statistics calculated for wafer \
testing"
ENDTRY
RECOVER
CONFIRM "Query aborted by user, database closed"
QUERY CLOSE wafer;
ENDTRY
IF %STOPPED = FALSE
QUERY CLOSE wafer;
CONFIRM "Query successful"
ENDIF
The example shows two nested TRY/ENDTRY blocks. The outer block
extracts data from the wafer database while the inner block performs
some statistical analysis of the data in the database. Progress commands
update the message that is displayed to the user so that he or she is
aware of the progress being made.
Note that the inner RECOVER block is carried out only if the user clicks
on the STOP button while the inner TRY/ENDTRY block is executing.
353
TSL Reference
However, the outer RECOVER block is executed if the user presses STOP
while TSL is executing either block
If the user does not press the STOP button at all, the %STOPPED variable
is not set. The value of this variable is checked to find out whether the
query was successful and close the database as necessary.
WHILE,
ENDLOOP
Description
The WHILE command provides a loop construct whose exit condition is
tested at the start of the loop. The commands which form the body of
the loop are executed repeatedly while the loop condition evaluates
TRUE or until the BREAK command is executed. The end of the loop is
marked by the ENDLOOP command.
Text substitution is performed on the expression before it is evaluated
and the expression must evaluate to a boolean value. A NULL value for
the expression is treated equivalent to FALSE.
Unlike the REPEAT command the loop may be executed zero times if
the loop condition immediately evaluates FALSE.
Example
DECLARE i 1
WHILE i<10
PRINTLN i
SET i i+1
ENDLOOP
355
Appendix
Error Messages
A
Error Messages
357
Appendix
Error Messages
TQL Errors
For TQL Server errors, in addition to any TSL error message, up to three
additional error messages may be reported, a Query level error, a
Database level error and a Filer level error. These errors are reported in
the following format:
Query: qmessage (#qno)
Dbase: dmessage (dobject) (#dno)
Filer: fmessage (fobject) (#fno)
where qmessage, dmessage, fmessage, are the error messages for the
Query, Database and Filer levels respectively and qno, dno, fno are the
corresponding error numbers. If present, dobject and fobject give
additional information about the object (e.g. file, relation, column) to
which the error applies. For more information about these errors you
should use the error numbers to look them up in the TQL Guide &
Reference.
TSL Errors
Errors detected by the TSL interpreter itself are reported in the
following format:
TSL: (Line lineno in filename) tmessage (#tno)
where lineno is the line in the TSL script at which the error was
detected, filename is the script in which the error was detected, tmessage
is the error message and tno is the TSL error number.
The messages are printed both to the terminal from which TSL was
started and the TSL log file.
The TSL errors are all fatal, that is, when an error occurs, execution of
the script stops and the TSL interpreter exits. The only exception is for
errors occurring during execution of QUERY commands when abort
mode is disabled.
Warnings
Warnings
In addition to the fatal errors, TSL may issue warning messages. These
do not cause the TSL interpreter to exit and are simply echoed to the
terminal and the TSL log file.
Errors
#1
Failed to obtain query buffer
The TSL application could not get a query buffer of the size requested.
There may be insufficient virtual memory availabletry again with a
smaller buffer size or when the system is less heavily loaded.
Alternatively the system limit of shared memory segments may have
been reached. Use ipcs to check the current shared memory status and
ipcrm to remove any redundant segments. If this happens frequently
you may need to consider reconfiguring your UNIX kernel to allow
more shared memory segments.
#2
Insufficient memory
There was insufficient virtual memory available for the TSL interpreter.
Try running again when the system is less heavily loaded.
#3
This error number is not used in the current version of Metrica/NPR.
#4
Cant open input file <filename>
The specified TSL script file <filename> could not be opened. Check that
the file can be found on TB_TSL_SPEC_PATH or TB_SPEC_PATH and that
you have read permission for the file.
#5
Cant open output file
The file specified for text output cannot be opened. Check that you
have write permission in the directory containing the file and, if the file
exists, on the file itself. Can occur during PRINTER ON commands.
#6
This error number is not used in the current version of Metrica/NPR.
#7
End of loop with no start of loop
A FOR, FORALL, UNTIL, or ENDLOOP was encountered before a REPEAT,
WHILE statement had been executed.
#8
Bad fork in shell escape
The command specified in a SHELL statement could not be executed or
returned a non-zero exit code.
359
Appendix
Error Messages
#9
Document aborted by user
The document was aborted prematurely using the window-manager or
a user interrupt.
#10
Token or command too long
The maximum length of a token (e.g the text for a QUERY) is limited to
16384 characters.
#11
Unknown TSL command <command>
TSL was expecting a command, instead it found <command>.
#12
Unknown enhancement (@<enhancement>)
Current valid printer enhancements are @B,@U,@E,@1 and @2.
#13
Cant access terminal
TSL terminates with this error if it fails to initialise the terminal window
or if a TELL command fails.
#14
Invalid condition in IF/UNTIL
The condition evaluated as part of an IF or UNTIL statement returned
NULL or a non-boolean value.
#15
Badly formed or nested IF
An ELSE, ELIF or ENDIF was encountered with no matching IF, or the
end of a script file was reached with an IF statement still unterminated.
#16
Error in QUERY
The TQL Server detected an error during the execution of query. The
TQL errors should give further information.
#17
This error number is not used in the current version of Metrica/NPR.
#18
Unable to load user help file <filename>
The help file <filename> could not be opened. Check that the file can be
found on TB_TSL_SPEC_PATH or TB_SPEC_PATH and that you have read
permission for it.
#19
Expected quoted string
TSL expected to find an argument to a command given in double or
single quotes.
#20
Menu system is already built
A MENU, TOOL or TOOLBOX command may not be executed once an
ASKMENU has been executed.
Errors
#21
Bad menu item
The menu-id for a MENU command was invalid. Each number in the
menu-id must be in the range 120.
#22
Script nested too deeply
Scripts may be nested up to 10 levels
#23
Unrecognised dialog item type <word>
TSL expected to find a dialog item type, instead it found <word>. The
valid types of dialogs are described in the section DIALOG item on page
227.
#24
Bad dialog item
This error can occur if the length of the variable name or the name of a
bitmap file is too long. Variable names are limited to 12 characters and
the length of a label and the name of a bitmap file is limited to 60
characters.
#25
Too many dialog items (max = 128)
TSL has a limit of 128 individual elements that can be defined for any
particular dialog. If you attempt to add more than 128 elements to a
dialog definition, TSL terminates with this error.
#26
Bad size specified for dialog item
The size should be greater than 0.
#27
Incorrect data type for dialog item
The data type specified for the dialog item is incompatible with dialog
item type. Refer to the reference page for the particular dialog item type
to determine the valid data types.
#28
Cannot open PTY for terminal subwindow
The pseudo-tty for the TSL terminal window could not be opened. The
permissions on the device file for the pseudo-tty may be incorrect (the
device file must be readable and writeable by all), or the system stock
of pseudo-tty devices may be exhausted. Try again when the system is
less heavily loaded. If this happens regularly you may need to consider
reconfiguring the UNIX kernel to increase the number of pseudo-ttys
allowed.
#29
This error number is not used in the current version of Metrica/NPR
361
Appendix
Error Messages
#30
Unfinished query in included file
The end of an included file was reached with no terminating semi-colon
found on a QUERY command.
#31
End of loop not found
The end of a script file was reached with a REPEAT or WHILE loop still
unterminated.
#32
This error number is not used in the current version of Metrica/NPR.
#33
Badly formed or nested SWITCH
A CASE, OTHERWISE or ENDSWITCH was encountered with no matching
SWITCH, or the end of a script file was reached with an SWITCH
statement still unterminated.
#34
You cannot create more than <n> dialogs
A maximum of n dialogs can be created in a TSL application.
Attempting to define more dialogs gives this error message.
#35
The dialog to manipulate has not been created
An ASKDIALOG command was attempted on an undefined dialog. This
error also occurs if a CLOSEDIALOG is attempted on a dialog that has not
been displayed.
#36
Illegal number of columns for dialog (Min=1, Max=30)
The number of columns in a dialog (as set by the DIALOG LAYOUT
command) must be in the range 1 to 30 inclusive.
#37
Cannot set number of columns once dialog already built
The DIALOG LAYOUT command can only be used on a dialog for which
no dialog items have currently been defined.
#38
Bad dialog LAYOUT specification
One (or more) of the specified layout options was not recognised or
was given an invalid value.
#39
Only NOTRAP is allowed after REPEAT
An unexpected string was found after the REPEAT keyword.
#40
Expected variable name after dialog type
A TQL variable name must be specified for all dialog item types except
labels.
#41
This error number is not used in the current version of Metrica/NPR.
Errors
#42
This error number is not used in the current version of Metrica/NPR.
#43
This error number is not used in the current version of Metrica/NPR.
#44
Incorrect TQL server revision
The TQL Server you are using is too old a revision to be used with your
version of TSL. Refer to the release notes accompanying your system to
determine the supported combinations.
#45
Bad expression in SWITCH
An error occurred when trying to evaluate the expression for a SWITCH
statement. The TQL error messages should give further information.
#46
TQL server is not authorised for TSL
The TQL Server you connected to is not authorised for use with TSL. If
you have a licence entitling you to use TSL, contact your distributor to
obtain a new security code.
#47
Illegal arguments - too long or out of range
The arguments to a CANVAS or GRAPH command were out of range e.g a
graph size larger than 100% was specified.
#48
Failed to start Kingfisher or make connection
TSL was unable to start the Kingfisher display window either because
the executable could not be found or executed or because it was the
wrong version.
#49
Kingfisher display has not been started
A CANVAS or GRAPH command was executed when no display window
was connected.
#50
Connection lost or Kingfisher exited
The user has probably closed the Kingfisher display window using the
window manager.
#51
Illegal/failed operation on display/graph
TSL terminates with this error if there was an unexpected Kingfisher
error while TSL was communicating with Kingfisher to carry out a
CANVAS or GRAPH command.
#52
Graph not defined
The graph specified by TSL was not recognised by Kingfisher.
363
Appendix
Error Messages
#53
TQL error on GRAPH DRAW/TRANSFER command
The TQL command passed to Kingfisher using the GRAPH DRAW
command, or an internal command executed during a TRANSFER, failed.
This error is not reported if abort mode is disabled and instead the error
codes are set in the special variables %QERR, %DERR and %FERR and the
error messages are stored in %QMSG. %DMSG and %FMSG.
#54
Graph for DRAW command must be last created
Kingfisher only allows datasets to be added to the last graph that has
been created and not to the currently selected graph.
#55
Graph ID out of range in SETGRAPH
TSL supports graph identifiers ranging from 1 to 50.
#56
Unknown graphics command
A word following a GRAPH or CANVAS command has not been
recognised by TSL as a valid sub-command.
#57
Expected property name
TSL expected to read in an attribute name = value pair but was unable
to find an attribute name.
#58
Expected a qualifier for the property
TSL expected to read in an attribute name = value pair but was unable
to find an attribute value.
#59
Bad property-value syntax
The syntax of a GRAPH PROPERTY, CANVAS HARDCOPY or TRANSFER
PROPERTY command was incorrect.
#60
Unrecognised graphics option
An invalid mode was given in a CANVAS MODE command, or the position
and resizing values in a CANVAS RESIZE command were not specified
as integers.
#61
Unknown display mode
The mode specified in a CANVAS MODE command is not known.
#62
Property/mode value is of incorrect type
Every property has a data type, either string, integer or real. You have
specified a value of incorrect type. Check the data type in the
Kingfisher Reference.
Errors
#63
Bad TRANSFER command
The TRANSFER command is followed by an invalid sub-command. The
command must be followed by the one of the keywords PROPERTY,
LOAD or UNLOAD only.
#64
Operation not possible in NOWINDOW mode
If TSL is run in nowindow mode, any commands, such as those that
create user interface elements, are not possible.
#65
OpenLook TSL does not support TSL 1.3 functionality
The OpenLook version of TSL is now obsolescent and new user
interface functionality has not been added to it.
#66
Too many dialog buttons (max = 20)
TSL has a limit of 20 individual buttons that can be defined for any
dialog. If you try to add more than 20 buttons to a dialog definition, TSL
terminates with this error.
#67
Bad PRINT command - expected ::
The PRINT command was used with a data item, but no double colon
(::) was found after the item.
#68
BREAK used outside of a loop
While trying to execute a BREAK command, TSL found the end of the
script file before it found a relevant loop terminating command
(ENDLOOP, FORALL, FOR or UNTIL).
#69
Missing (
The CALL and DEFPROC commands require that the procedures
arguments or parameters are enclosed by parentheses.
#70
Missing )
The CALL and DEFPROC commands require that the procedures
arguments or parameters are enclosed by parentheses.
#71
Missing value for attribute in MENU
No value followed the equals.
#72
Unknown attribute in MENU
Acceptable attributes are SENSITIVE and ACTION.
#73
Expected DEFAULT, ICON or quoted string
The DIALOG BUTTON command must be followed by one of the
keywords DEFAULT or ICON, or by a quoted string.
365
Appendix
Error Messages
#74
Expected ICON or quoted string
The DIALOG BUTTON DEFAULT command must be followed by the
keyword ICON or by a quoted string.
#75
Missing ,
A comma must be used to separate arguments and parameters in CALL
and DEFPROC commands.
#76
Missing , or )
A newline was encountered before the end of the parameter list in a
procedure definition and the end of the argument list in a procedure
call. To continue the parameter/argument list onto the next line you
should escape \ the newline.
#77
Invalid or missing argument after ,
An invalid or missing argument or parameter has been specified in a
CALL or DEFPROC command.
#78
Invalid or missing argument name after VAR
An invalid or missing argument or parameter follows the keyword VAR
in a DEFPROC command.
#79
Invalid argument name or missing )
Either an invalid or missing argument or parameter has been specified
in a DEFPROC command or the close parenthesis was not found.
#80
Missing or invalid procedure name
The procedure name given in a DEFPOC or CALL command is invalid.
#81
Expected ACTION or quoted string
This error is not used in the current version of Metrica/NPR.
#82
ACTION for BUTTON is undefined
Buttons require that an action is defined for them.
#83
Couldnt find bitmap file
Check that the environment variable XBMLANGPATH has been defined
correctly.
#84
Procedure already defined
A procedure by this name has already been defined. Check that you are
not evaluating the script in which the procedure is defined more than
once.
#85
Missing ENDPROC
The ENDPROC command could not be found when exiting a procedure.
Errors
#86
Missing argument before ,
The arguments or parameters in a CALL command were specified
incorrectlyno argument was found before the first comma.
#87
Procedure undefined
The named procedure has not be defined yet. Ensure that the script in
which the procedure is defined is evaluated before the procedure is
called.
#88
Procedure called with incorrect number of arguments
Procedures must be called with the same number of arguments as the
procedure has parameters.
#89
ENDPROC without a DEFPROC
TSL encountered the ENDPROC keyword before any matching DEFPROC
keyword.
#90
RETURN used whilst not in a procedure
The keyword RETURN is only valid within a procedurethat is, between
the DEFPROC and ENDPROC keywords.
#91
Action string has already been defined
You have tried to redefine an action in the MENU or TOOL command.
#92
Sensitivity has already been defined
You have defined this attribute more than once.
#93
Unknown attribute in DIALOG
See description of specific dialog type to see what attributes the dialog
can use
#94
Missing value for attribute in DIALOG
Nothing follows the equals.
#95
Bad tool item
Either the tool group or the position in the tool group is less than 0.
#96
Unknown attribute in TOOL
Acceptable attributes are SENSITIVE and ACTION.
#97
Missing value for attribute in TOOL
Nothing follows the equals.
#98
Tool group defined to hold no tools
A tool group must contain at least one tool.
367
Appendix
Error Messages
#99
Unknown attribute in TOOLBOX
Acceptable attributes for TOOLBOX are GRAVITY, ROWCOLS, FRAME,
GROUPGAP and TOOLGAP.
#100 TOOLBOX attribute was redefined
You have tried to redefine an attribute in a TOOLBOX command.
#101 Bad value for GRAVITY in TOOLBOX
Acceptable values are NORTH, SOUTH, EAST and WEST.
#102 Bad value for ROWCOLS in TOOLBOX
You have tried to set a negative value for the ROWCOLS attribute of a
TOOLBOX command.
#103 Nothing follows TOOLBOX command
This command should be followed by one or more attribute-value pairs.
#104 TOOLBOX contains no tools
You have defined a toolbox but have not defined any tools for it.
#105 Missing value for attribute in TOOLBOX
TSL expected an attribute = value pair in a TOOLBOX command but no
value was given.
#106 Expected boolean as sensitivity condition
The sensitivity condition evaluated to a non-boolean value. Check the
types of the variables/expressions used by the SENSITIVE attribute.
#107 Expected boolean as readonly condition
The read-only condition evaluated to a non-boolean value. Check the
types of the variables/expressions used by the READONLY attribute.
#108 Expected boolean as text range condition
The range condition evaluated to a non-boolean value. Check the types
of the variables/expression used by the RANGEMIN and RANGEMAX
attributes.
#109 Expected boolean as allownull condition
The allownull condition evaluated to a non-boolean value. Check the
types of the variables/expressions used by the ALLOWNULL attribute.
#110 Read only text field out of range
Range checking on a read-only text field showed that the value for the
text field was out of range. Check the value the text field has been
initialised to and the values assigned to the RANGEMIN and RANGEMAX
attributes.
Errors
#111 Read only text field not allowed to have null value
A read-only text field has been initialised to NULL and the ALLOWNULL
attribute is being evaluated to TRUE. Check the (multiline) text fields
variable and the value of the ALLOWNULL attribute.
#113 Expected a list command
No command followed the lists variable name.
#114 Unknown list command
Current commands are INSERT, DELETE, REPLACE, APPEND and CLEAR.
#115 Variable doesnt exist in current dialog
The variable identifying the list to be edited doesnt exist in the last
dialog which was displayed by an ASKDIALOG command.
#116 Variable is not a list
The variable identifying the list is not a list.
#119 Number of columns in dialog already defined
You have tried to redefine the number of columns in a dialog. The
COLUMNS attribute in a DIALOG LAYOUT command can only be defined
once per dialog.
#120 Number of columns of buttons is already defined
You have tried to redefine the number of button columns in a dialog.
The BUTTONCOLUMNS attribute in a DIALOG LAYOUT command can only
be defined once per dialog.
#121 Alignment of columns is already defined
You have tried to redefine the alignment policy of columns in a dialog.
The ALIGNCOLUMNS attribute in a DIALOG LAYOUT command can only be
defined once per dialog.
#122 Alignment of rows is already defined
You have tried to redefine the alignment policy of rows in a dialog. The
ALIGNROWS attribute in a DIALOG LAYOUT command can only be defined
once per dialog.
#123 Alignment of items is already defined
You have tried to redefine the alignment policy of items in a dialog. The
ALIGNITEMS attribute in a DIALOG LAYOUT command can only be
defined once per dialog.
#124 Dialog mode is already defined
You have tried to redefine the mode of a dialog. The MODE attribute in a
DIALOG LAYOUT command can only be defined once per dialog.
369
Appendix
Error Messages
Errors
#138
371
Appendix
Error Messages
Errors
373
Appendix
Error Messages
#180
#181
Errors
#190
This error number is not relevant to the current version of Metrica/NPR.
#191
This error number is not relevant to the current version of Metrica/NPR.
#192
This error number is not relevant to the current version of Metrica/NPR.
#193
This error number is not relevant to the current version of Metrica/NPR.
#194
This error number is not used in the current version of Metrica/NPR.
#195 Data provided is invalid
The data provided is not valid for the operation requested.
#196
This error number is not relevant to the current version of Metrica/NPR.
#197
This error number is not relevant to the current version of Metrica/NPR.
#198
This error number is not relevant to the current version of Metrica/NPR.
#199
This error number is not relevant to the current version of Metrica/NPR.
#200
This error number is not relevant to the current version of Metrica/NPR.
#201
This error number is not relevant to the current version of Metrica/NPR.
#202
375
Appendix
Error Messages
Warnings
Warnings
Cursor not available on this graph
An attempt was made to read a cursor value from a graph which does
not support it (e.g. a three-dimensional graph).
Display was not started in requested mode
A Kingfisher display window was already running when the CANVAS ON
command was executed. However, it was started in a different mode to
that requested.
Failed to open file or pipe for transfer
The status returned by Kingfisher after performing a TRANSFER
command indicated that the specified file or pipe could not be opened.
TSL will not terminate but the TRANSFER command may not have been
successful.
IO error when writing to file or pipe
The status returned by Kingfisher after performing a TRANSFER
command indicated that the specified pipe or file could not be written
to. TSL will not terminate but the TRANSFER command may not have
been successful.
Label truncated to <label> (60 characters)
A label in a dialog was too big and has been truncated to <label>.
Motif Window Manager is not running
If the Motif version of TSL is started but the Motif window manager is
not running, this warning message is printed. The application will
377
Appendix
Error Messages
continue to run but some aspects of the user interface may not behave
as expected.
Normal and bold fonts have different heights
Normal and bold fonts have different widths
The fonts specified as the bold and normal fonts for the terminal
window must have identical height and width. If they do not the
application continues but uses the normal font for both normal and
bold text.
Overflow in text expansion for list item
When the items in a list, option menu or panel are obtained via a query
buffer expansion the total length of the expanded items is limited to
16384 characters.
Property settings and data are incompatible
Check the property name and the valid values in the Kingfisher
Reference manual.
Property value out of range
Check the property name and the valid values in the Kingfisher
Reference manual.
Query buffer is too small - use -buffersize
There is insufficient space in the query buffer for the operation. Rerun
TSL using the -buffersize command line argument to increase the
buffer size.
Timed out waiting for connection
TSL could not establish a connection to the Kingfisher display window.
Check that a Kingfisher display has been started.
UNIX command failed in transfer pipe
The status returned by Kingfisher after performing a TRANSFER
command indicated that the specified pipe could not be opened. TSL
will not terminate but the TRANSFER command may not have been
successful.
Unknown property name
Check the property name and the valid values in the Kingfisher
Reference manual.
Warnings
379
Index
Index
Symbols
#, using in comment lines 8
canvas, defined
see also display window 122
%, and variable definition 9
%BUFFERED macro 208
%BUTTONVAL variable 251
and ACTION attribute 87
and action string 19
and application defined buttons 63
and ASKDIALOG command 203
and convenience dialogs 4445
and DIALOG BUTTON command 230
and DIALOG LIST command 240
and DIALOG PANEL command 254
and DIALOG SLIDER command 258
and DIALOG TOGGLE command 264
and SELECT command 321
and SELECTFILE command 323
and sliders 56
%CONFIRMVAL variable
and CONFIRM command 224
holds confirmation dialog result 42
%DERR variable
and ABORT command 189
and GRAPH DRAW command 272
and GRAPH DRAW errors 135
and QUERY errors 310
database level error code 157
error messages 364
%DIALOGVAL variable
and application defined buttons 63
and ASKDIALOG command 203
and convenience dialogs 4446
and DIALOG BUTTON command 230
and DIALOG LIST command 240
and DIALOG OPTION command 251
381
Index
A
ABORT command
and GRAPH DRAW query errors 272
and QUERY errors 310
description of 189190
enabling/disabling abort mode 156158
383
Index
attributes (continued)
YPOS 7173, 371
B
backslash character 14
BEEP command 206
bitmap, creating bitmaps 20
BREAK command
and loops 312
description of 207
buffer
copying screen output to 208
query buffer 90
setting the current 325
BUFFER command
description of 208
error messages 376
printing reports from a buffer file 114
building, see creating
BUSYONAPPLY attribute
defines appearance of insensitive dialog
76
set in application defaults file 164, 196
set with DIALOG LAYOUT command 236
BUTTONCOLUMNS attribute
description of 68
set in application defaults file 164, 195
set with DIALOG BUTTON command 230
set with DIALOG LAYOUT command 235
BUTTONLAYOUT attribute
description of 68
set in application defaults file 164, 196
set with DIALOG LAYOUT command 236
buttons
application defined 76
changing control buttons 74
C
CALL command
calling procedures 1012
description of 209
error messages 365
canvas
description of 122
modes 122
CANVAS CLEAR command 130
and multiple graphs 144
description of 210
CANVAS COLOURMAP command
description of 211
loading a colourmap 143
CANVAS CONFIG command
description of 213
loading hardcopy configuration 130
CANVAS HARDCOPY command 364
description of 214215
override current hardcopy settings 129
CANVAS HIDE command
description of 210
hiding the canvas 131
CANVAS MODE command
and AUTORAISE mode 131
description of 216
editing graphs 134
error messages 364
CANVAS OFF command
description of 217219
destroy a canvas 124
CANVAS ON command
and error conditions 127, 135
and GRAPH CURSOR command 271
and GRAPH FORMAT command 275
and GRAPH POSITION command 276
and GRAPH PROPERTY command 278
and KFPROC command 290
creating a canvas 122125
description of 217219
CANVAS PRINT command
description of 210
printing a canvas 129130
CANVAS RAISE command
and CANVAS MODE command 216
description of 210
raising a canvas 131
385
Index
commands (continued)
ASK 201
ASKDIALOG 19, 4648, 56, 74, 75, 79, 81,
158, 202204, 230, 248, 261, 264,
343, 369
ASKMENU 19, 2628, 32, 34, 35, 158, 205,
295, 343, 345, 360
BEEP 206
BREAK 207, 312
BUFFER 208
CALL 1012, 209, 365
CANVAS CLEAR 130, 144, 210
CANVAS COLOURMAP 143, 211
CANVAS CONFIG 130, 213
CANVAS HARDCOPY 129, 214215, 364
CANVAS HIDE 131, 210
CANVAS MODE 131, 134, 216, 364
CANVAS OFF 124, 217219
CANVAS ON 122125, 127, 135, 217219,
273, 275, 276, 278, 290
CANVAS PRINT 129, 210
CANVAS RAISE 131, 210, 216
CANVAS REFRESH 130, 210
CANVAS RESIZE 130, 220
CANVAS SNAPSHOT 131, 210
CASE 35, 335336, 362
CLEAR 221
CLOSEDIALOG 63, 76, 222
CONFIRM 42, 224
DECLARE 9, 65, 225
DEFPROC 912, 226, 365
DIALOG 46, 4864, 79, 227228, 328, 367
DIALOG BUTTON 6364, 229230, 373
DIALOG CALENDAR 231
DIALOG HSLIDER 56, 257258
DIALOG LABEL 62, 233
DIALOG LAYOUT 68, 81, 163164, 195,
196, 235238, 328, 362, 370
DIALOG LIST 5759, 239243
DIALOG MULTITEXT 55, 247249
DIALOG OPTION 5759, 250251
DIALOG PANEL 5759, 253254
commands (continued)
DIALOG SKIP 70, 256, 328
DIALOG SLIDER 56, 257258
DIALOG TEXT 5255, 259261
DIALOG TIMERANGE 262
DIALOG TOGGLE 56, 264
DIALOG VSLIDER 56, 257258
EJECT 266
ELIF 29, 284285, 286, 360
ELSE 29, 284285, 286, 360
ENDIF 29, 284285, 360
ENDLOOP 355, 359
ENDPROC 912, 226, 317
ENDSWITCH 335336, 362
ENDTRY 352
ERROR 40, 267
EXPAND 268
FILL 107, 269
FIRST 90, 270
FOR 91, 312314, 359
FORALL 91, 312314, 359
GRAPH CURSOR 134, 140142, 216, 271
GRAPH DRAW 132137, 143, 216, 272
273, 276, 363
GRAPH FORMAT 132134, 138, 142, 274
275
GRAPH LOAD 135
GRAPH POSITION 133, 276
GRAPH PROPERTY 138140, 277278,
364
GRAPH SAVE 135
HELPFILE 1718, 39, 280
IF 29, 284285, 286, 360
IFOK 157158, 189, 286
INFO 40, 287
JUSTIFY 107, 288
KFPROC 125126, 216, 290
LAST 90, 291
LENGTH 106, 109, 119, 292, 300, 303
MARGIN 106, 109, 119, 293, 300, 303
MENU 25, 34, 294296, 360, 365
MENU SKIP 32, 294296
commands (continued)
MORE 159160, 297
NEXT 90, 298
OTHERWISE 335336, 362
PAGESTYLE 96, 108110, 117, 299, 373
PREV 90, 302
PRINT 96, 101105, 269, 303306
PRINTER 110119, 308309, 331, 372
PRINTER OFF 111, 118, 308
PRINTER ON 111, 117, 118, 308, 359
PRINTLN 101105, 269, 303306
PROC 125, 290
QUERY 286, 310311, 358, 360, 361
RECOVER 352
REPEAT 27, 91, 312314, 359, 362
REPORT 96, 109110, 117118, 315, 332,
373
REPORT OFF 110, 118, 315
REPORT ON 110, 117, 300, 303, 315
RETURN 317
SCREEN 318
SCRIPT 319, 361
SELECT 44, 66, 321
SELECTFILE 45, 323
SET 9, 324
SETBUFFER 325
SETCANVAS 146, 326, 371
SETDIALOG 79, 328
SETGRAPH 143, 329, 364
SETPAGESTYLE 108, 117, 330, 373
SETPRINTER 110, 117, 331, 372
SETREPORT 110, 117, 332, 372
SHELL 333, 359
STOP 334
SWITCH 3435, 335336, 362, 363
TABLE 9698, 100, 337
TELL 338
TIMEOUT 158, 343
TITLE 18, 344
TOOL 26, 345346, 360, 367
TOOLBOX 32, 34, 164, 196, 347348, 360,
367
387
Index
commands (continued)
TRANSFER LOAD 154, 349350
TRANSFER PROPERTY 154, 351, 364
TRANSFER UNLOAD 155, 349350
TRY 352
UNTIL 27, 312314, 359
using in script files 8
WHILE 28, 355, 359, 362
comments 223
using in script files 8
complex numbers, printing 104
configuring
TSL fonts 192
CONFIRM command
confirmation dialog 42
description of 224
confirmation dialog
CONFIRM command 224
description of 42
control button area 38
control buttons 63
creating
application scripts 33
dialogs 46
display window snapshots 131
graphs 132
graphs with Kingfisher procedures 149
menus 27, 33
multi-level menu system 28
multiple dialogs 79
multiple graphs 143
on-screen reports 96
printed reports 111
the display window 122
variables 9
current pagestyle 108
cursor commands 140
cutting and pasting TSL text 160
D
data coordinates
reading with GRAPH CURSOR 141
data types
and dialog items 49
list of 187
dates
finding records by 14
printing 104
select date dialog 166
DECLARE command
assigning value to variable with text substitution 65
creating variables 9
description of 225
DEFAULT attribute
and REPORT command 315
define report page style 109
error messages 373
defaults, dialog layout 68
defining
accelerator 30
mnemonics 30
DEFPROC command
defining a procedure 912
description of 226
error messages 365
DELETE list editing command 81
and DIALOG LIST command 244245
changing a lists contents 82
error messages 369, 373
dialog appearance
set with application resources 194
DIALOG BUTTON command
application defined buttons 6364
description of 229230
error messages 373
dialog buttons 38
DIALOG CALENDAR command
creating calendar items 61
description of 231
DIALOG command
and SETDIALOG command 328
creating dialog items 46
creating dialogs 4879
389
Index
dialogs (continued)
option menus 57
predefined dialogs 39, 42
presetting dialog items 6467
presetting list dialog items 66
scrolled lists 57
text fields 51
range checking 5254
testing for NULL values 53
toggle buttons 56
types, listed 49
dimension units
for dialog layout 70
valid 20
display window
clearing 130
creating 122
generating a snapshot 131
moving to front 131
printing 129
refreshing 130
setting fonts 161
setting number of columns 162
setting number of rows 162
specifying position, size and mode 122
E
EJECT command 266
ELIF command
description of 284285
error messages 360
example usage 29
with IFOK command 286
ELSE command
description of 284285
error messages 360
example usage 29
with IFOK command 286
Encrypted TSL 4, 319
ENDIF command
description of 284285
error messages 360
errors (continued)
and executing GRAPH commands 130,
135
and running procedures 126
and transferring data 155
escape
and backslash character 14
exclusive panels 49, 57
EXPAND command
description of 268
text substitution 14
F
file selection dialog 45
FILENAME attribute
and PRINTER command 111
defines output filename 308
error messages 372
FILL command
description of 269
in free format reports 107
finding
records by date 14
script files 3
FIRST attribute 373
and REPORT command 315
define page style 109
error messages 373
FIRST command
description of 270
navigating the query buffer 90
fonts
application resources 161, 192
in TSL window menus 192
FOOTER attribute 315
and PAGESTYLE command 299
error messages 373
page style attribute 108110
FOOTLINE attribute
and PAGESTYLE command 299
error messages 373
page style attribute 108, 110
FOR command
description of 312314
error messages 359
example usage 91
FORALL command
description of 312314
error messages 359
example usage 91
format characters 103, 304
formatting
type dependent 102
type independent 102
formatting on-screen reports 99
FRAME attribute
and TOOLBOX command 347
draw toolbox frame 32
error messages 367
set in application defaults file 164, 196
free format reports 106
G
generating, see creating
GRAPH CURSOR command
and EDIT mode 216
description of 271
enabling the graphics cursor 140142
implicit creation and destruction 134
GRAPH DRAW command
and AUTORAISE mode 216
and GRAPH POSITION 276
creating a graph 132137
description of 272273
error messages 363
multiple graphs 143
GRAPH FORMAT command
description of 274275
example usage 142
implicit creation and destruction 138
using predefined graph formats 132134
GRAPH LOAD command 135
GRAPH POSITION command
description of 276
391
Index
H
hardcopy configuration 130
hardcopy, see printing 129
HEADER attribute
and %PAGENUM attribute 315
and PAGESTYLE command 299
error messages 373
pagestyle attribute 108110
HEADLINE attribute
and PAGESTYLE command 299
error messages 373
pagestyle attribute 108110
HEIGHT attribute
and DIALOG LAYOUT command 237
define dialogs main area 70
help
button 39
menus 1718
HELPFILE command 39
define current help file 1718
description of 280
HPGL hardcopy format, supported by Kingfisher 129
I
iconic buttons, creating 63
icons
definition of 20
on tools 25
IF command
and IFOK command 286
description of 284285
error messages 360
example usage 29
IFOK command
and ABORT command 189
and error handling 157158
description of 286
importing/exporting data, see transferring data
INFO command
description of 287
information dialog 40
information dialog 40
initialising the graphics server 122
INSERT list editing command
and DIALOG LIST command 244245
changing a lists contents 8182
error messages 369, 373
J
JUSTIFY command
description of 288
free format reports 107
K
keysym
in accelerators 30
KF_COLOURMAP_PATH environment variable 142, 211
KF_EXEC_TIMEOUT, set Kingfisher timeout
period 123
KF_FORMAT_PATH environment variable
134135, 274
and GRAPH command errors 135
KF_PROC_PATH environment variable 126
127, 289
KFPROC command
and AUTORAISE mode 216
calling a Kingfisher procedure 125126
description of 289290
Kingfisher procedures 125129
defined 125
errors 126
executing in TSL 125
executing with KFPROC 289290
specifying variables 126
using for graphics development 149
L
labeled-iconic buttons 64
LABELGAP attribute
and DIALOG BUTTON command 230
and DIALOG LABEL command 234
define position of dialog item 71
description of 74
error messages 373
position attribute 187
labels, in dialogs 62
LAST command
description of 291
navigating the query buffer 90
LEFT attribute 315
define report layout 109
error messages 373
LENGTH attribute
and PAGESTYLE command 299300
M
macros
%BUFFERED 208
%OUTPUT 308
see also Kingfisher procedures 125
main dialog area 38
managing multiple dialogs 79
393
Index
MARGIN command
and LMARGIN/RMARGIN attributes 300
and PRINT command 303
controlling page layout 106
description of 293
sets value of RMARGIN attribute 109
MAXLEN attribute
and DIALOG MULTITEXT command 248
maximum string length for multiline text
55
MAXWIDTH attribute
and DIALOG LIST command 241
and list editing commands 181
in lists 59
MENU command
defining a menu system 2532
description of 294296
error messages 360, 365
example usage 34
menu hierarchy, defined 24
MENU SKIP command
description of 294296
skipping menu items 32
menus 24
creating a menu system 24
creating a multi-level menu system 28
MINWIDTH attribute
and DIALOG LIST command 241
and list editing commands 181
in lists 59
mnemonics
defining 30
MODE attribute 74
and DIALOG LAYOUT command 236
set in application defaults file 164, 195
MORE command
controlling the More prompt 159160
description of 297
--More-- prompt 159
multiline text fields
defining 55
N
NEXT command
description of 298
navigating the query buffer 90
NOEDIT modifier 135
and error conditions 127
prevent graph editing 124
NOMENU modifier 135
and error conditions 127
for CANVAS command 125
NOPROMPT modifier
and variables in Kingfisher procedures
150
example usage 127
for Kingfisher procedures 126
NOTRAP modifier
disable abort signal trapping 160
NULL_ERR_MSG attribute
and DIALOG MULTITEXT command 248
and DIALOG TEXT command 261
define error message for NULL values 53
O
option menu
creating 57
description of 50
DIALOG OPTION command 250
OTHERWISE command
description of 335336
error messages 362
OUTPUT attribute
and PRINTER command 111, 308
error messages 372
overlays, plotting 137
P
PAGESTYLE command
defining a reports pagestyle 108110
description of 299
ENDLINE attribute 108110, 299, 373
error messages 373
example usage 117
Q
query buffer, defined 90
QUERY command
and IFOK command 286
395
Index
R
raising the display window 131
RANGE_ERR_MSG attribute 53, 261
RANGEMAX attribute 368
and ASKDIALOG command 202
and DIALOG TEXT command 261
error messages 368
restricting acceptable values 5254
when evaluated 19
RANGEMIN attribute
and ASKDIALOG command 202
and DIALOG TEXT command 261
error messages 368
restricting acceptable values 5254
when evaluated 19
READ command
adds items to a list 245
READONLY attribute
and DIALOG MULTITEXT command 248
and DIALOG TEXT command 260
error messages 368
style guidelines 180
syntax conventions 188
when evaluated 19
RECOVER command 352
refreshing the display window 130
REPEAT command
defining a loop 27
description of 312314
error messages 359, 362
traversing the query buffer 91
REPLACE list editing command 373
and DIALOG LIST command 244245
changing a lists contents 81, 83
error messages 369
REPORT command 373
and SETREPORT command 332
REPORT command
DEFAULT attribute 109, 315, 373
defining reports 109110
description of 315
error messages 373
example usage 117118
FIRST attribute 109, 315
formatting reports 96
LEFT attribute 109, 315, 373
RIGHT attribute 109, 315, 373
REPORT OFF command
defining reports 110
description of 315
example usage 118
REPORT ON command
and PRINT command 303
creates %PAGENUM variable 300
defining reports 110
description of 315
example usage 117
reports
formatting for screen 99
free format reports 106
printing from a buffer file 114
printing to printer 111
printing to screen 96
retrieving data 90
RETURN command 317
RIGHT attribute
and REPORT command 315
defining pagestyles 109
error messages 373
RMARGIN attribute
and PAGESTYLE command 299300
defining a pagestyle 108109
error messages 373
ROWCOLS attribute 165, 347
and TOOLBOX command 347
and toolbox definition 32
error messages 367
set in application defaults file 165, 196
rows
changing dialog default layout 68
S
SAVE command
write a list to a file 245
SCREEN command 318
SCRIPT command
description of 319
error messages 361
script files
defined 8, 33
finding 3
search paths 33
scrolled lists 49, 57
SCROLLMODE attribute 241
and changing list contents 245
and DIALOG LIST command 241
setting for lists 59
style guidelines 181
searching, see finding 14
SECRET attribute
and DIALOG TEXT command 261
in text fields 55
SELECT command
creating a list selection dialog 44
description of 321
presetting list selection dialog 66
SELECTFILE command
creating a file selection dialog 45
description of 323
SELECTION_DELIM attribute 60, 242
SELECTION_MAXITEMS attribute 60, 242
SELECTION_POLICY attribute 241
SENSITIVE attribute 251
and ASKMENU command 205
and DIALOG BUTTON command 230
and DIALOG LABEL command 233
and DIALOG LIST command 240
and DIALOG MULTITEXT command 248
and DIALOG PANEL command 254
and DIALOG TOGGLE command 264
397
Index
T
TABLE command
controlling text item expansion 9698
description of 337
example usage 100
tables
loading and unloading 154
TB_SPEC_PATH environment variable
error messages 359, 360
path for help files 18, 280
path for script files 319
TB_TSL_SPEC_PATH environment variable
error messages 359, 360
path for help files 18, 280
path for script files 3, 319
tbprint script
and printCommand 163
using in PostScript mode 171
TELL command 338
TERM environment variable 333
terminal window
application resources 194
text fields
creating 51
creating multiline text fields 55
description of 49
DIALOG MULTITEXT command 247
DIALOG TEXT command 259
text items 340
and EXPAND command 14
assigning a value to 12
complex numbers 13
control expansion of with TABLE 96
dates 13
definition of 12
in script files 8
in TSL commands 14
strings 13
times 13
text lines, description of 12
text substitution 13
and EXPAND command 14, 268
399
Index
U
UNTIL command
defining a loop 27
description of 312314
error messages 359
V
variables
%BUTTONVAL 19, 44, 47, 56, 63, 87, 203,
230, 240, 251, 254, 258, 264, 321,
323
%CONFIRMVAL 42, 224
%DERR 135, 157, 189, 272, 310, 364
%DIALOGVAL 4447, 56, 63, 203, 230,
240, 251, 254, 258, 264, 321, 323
%DISPLAY 310
%DLOGCHANGED 47, 202
%DMSG 135, 158, 189, 272, 310, 364
%FERR 135, 157, 189, 272, 310, 364
%FILEVAL 45, 323
%FMSG 135, 158, 189, 272, 310, 364
%GRFOCUSSED 147
%GRSELECTED 147
%GRSTATUS 126, 130, 135, 143, 211, 213,
272, 274, 289
%LISTOK 8183, 244
%LISTPOS 61, 242
%MENUVAL 19, 2630, 3435, 205, 295,
345346
%NOWINDOW 169
%NUM_GRAPHS 147
%NUMSELECTED 60, 242
%PAGENUM 110, 300, 315
%QERR 135, 157, 189, 272, 310, 364
%QMSG 135, 158, 189, 272, 310, 364
%QOK 135, 189, 272, 310
%ROWS 90, 100, 310
variables (continued)
%SELECTED 60, 242
%SELECTVAL 44, 321
%STAT 333
%XFDISCARD 155, 350
%XFROWS 155, 350
%XFSTATUS 155, 349
%XVAL 140142, 271
%YVAL 140142, 271
%ZVAL 140, 271
creating 9
defined 9
with Kingfisher procedures 126
W
WHILE command
defining a loop 28
description of 355
error messages 359, 362
WIDTH attribute
and DIALOG LAYOUT 237
defining the position of dialog items 70
window
managers, TSL and 18
titles, changing 18
windows
positioning on the workspace 131
X
XADJUST attribute
error messages 371
position attribute 187
positioning dialog items 71
setting a dialog items offset from default
73
XBMLANGPATH environment variable
and DIALOG BUTTON command 229
error messages 366
path for bitmaps 20, 233, 345
xfontsel
application resources 193
XFontSets
application resources 192
XORIGIN attribute
defining a dialog items position 7173
position attribute 187
XPOS attribute
defining a dialog items position 7173
error messages 371
position attribute 187
xrdb and changing application resources 166
Y
YADJUST attribute
defining a dialog items position 71
error messages 371
position attribute 187
setting a dialog items offset from default
73
YORIGIN attribute
defining a dialog items position 7173
position attribute 187
YPOS attribute 7173
error messages 371
position attribute 187
401
Index