TSL

TSL Guide &
Reference
Copyright
1994-2001 ADC Software Systems UK
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
Manual reference: DEV/MAN/1998/096

Important Notice
The information in this publication is subject to change without notice.
ADC Software Systems UK shall not be liable for errors contained herein or for incidental
or consequential damages in connection with the furnishing, performance, or use of this
material.
All rights are reserved. This publication and its associated computer programs are the sole
property of ADC Software Systems UK and contain proprietary information. No part of
this publication may be photocopied, reproduced, translated into another language, or
transcribed in any way without the prior written consent of ADC Software Systems UK.
ADC SOFTWARE SYSTEMS UK MAKES NO WARRANTY OF ANY KIND WITH REGARD TO
THIS MATERIAL AND ITS ASSOCIATED COMPUTER PROGRAMS, INCLUDING BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF QUALITY, MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE.
Use, duplication, or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in
Technical Data and Computer Software clause at DFARS 252.227-7013,
and in subparagraphs (a) through (d) of the Commercial ComputerRestricted Rights clause at FAR 52.227-19, and in similar clauses in the
NASA FAR supplement, where applicable.
ADC and ADC Telecommunications are registered trademarks of ADC
Telecommunications. Inc
Metrica is a registered trademark of ADC Software Systems UK.
Motif is a trademark of the Open Software Foundation, Inc.
UNIX and OSF are registered trademarks of The Open Group.
PostScript is a trademark of Adobe Systems Incorporated
X Window System is a trademark of the Massachusetts Institute of Technology
HP, HP-GL, PCL and VUE are registered trademarks of Hewlett-Packard Company
SUN is a trademark of Sun Microsystems, Inc.
FLEXlm is a registered trademark of GLOBEtrotter Software Inc.
All other trademarks are trademarks of their respective companies.
Contents
Preface
vii
About this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Using this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
PART 1 :TSL Guide

Chapter 1
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
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Menus & Toolboxes
The menu system and toolbox

A simple menu . . . . . . . . . . .
A multi-level menu system . . .
Mnemonics and Accelerators .
2
2
4
5
5
..........
..........
..........
..........
.
.
.
.
8
8
9
9
12
12
15
15
17
18
19
20
20
23
.....
.....
.....
.....
....
....
....
....
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
24
27
28
30
Contents
Skipping menu items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

The Toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
A menu system and toolbox in a real application . . . . . . . . . 33
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 . . . . . . . . . . . . . . .
ii TSL Guide & Reference
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
The Query Buffer
89
Navigating the query buffer . . . . . . . . . . . . . . . . . . . . . . . . . 90

The query buffer and variables . . . . . . . . . . . . . . . . . . . . . . 92
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
Loading and unloading tables . . . . . . . . . . . . . . . .

Default property values . . . . . . . . . . . . . . . . .
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . .
Making TSL timeout . . . . . . . . . . . . . . . . . . . . . . .
More . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cut and Paste . . . . . . . . . . . . . . . . . . . . . . . . . . .
X Resources and the Applications defaults file . . .
Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TSL main window . . . . . . . . . . . . . . . . . . . . .
Print spooler . . . . . . . . . . . . . . . . . . . . . . . . .
Dialog layout attributes . . . . . . . . . . . . . . . . .
Toolbox attributes . . . . . . . . . . . . . . . . . . . . .
Menus and dialogs . . . . . . . . . . . . . . . . . . . . .
The Select Date dialog . . . . . . . . . . . . . . .
Setting an application resource . . . . . . . . . . . .
Command-line options . . . . . . . . . . . . . . . . . . . .
iv TSL Guide & Reference
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
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
TSL Style Guide
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
PART 2 :TSL Reference

TSL Reference
Appendix A
TQL Errors .
TSL Errors . .
Warnings
Errors . . . . .
Warnings
Index
185
Error Messages
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
357
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
358
358
359
359
377
381
Preface
Preface
TSL is an applications Scripting Language for building applications

using Metrica/NPR databases. Using TSL you will be able to produce
attractive, easy-to-use applications in a fraction of the time that would
be needed using conventional programming languages and tools.
About this guide

This guide consists of two parts:
Part 1: TSL Guide
The guide provides an introduction to TSL concepts. It then describes

how to use the key features of TSL such as building menus and dialogs,
generating reports and plotting graphs. Some hints and suggestions on
creating consistent user interfaces are included in a TSL Style Guide.
Part 2: TSL Reference
The reference describes each TSL command in a standard reference

format, together with details about X Windows resource configuration.
Using this guide

We recommend that you work through Part 1 first. This will give you a
good feel for TSL, its principal facilities and how to go about building
applications. Use Part 2 in the normal reference fashion when you are
writing your TSL scripts. As you will see, to use TSL effectively you will
need to be familiar with TQL, the Query Language used in Metrica/NPR.
In addition some knowledge of Kingfisher graph, hardcopy and transfer
properties would help you understand some parts of this book.
The TSL debugger and the TSL syntax checker are Metrica/NPR utilities
which can be used by developers to debug their TSL scripts.
TQL is covered in the companion guide: TQL Guide and Reference.
Kingfisher properties are covered in the companion guide: Kingfisher
Reference.
The TSL debugger, the TSL syntax checker and the TSL encryption
utility are described in the companion guide: Utilities.
vii
PART 1
TSL Guide
Chapter
Introduction
1
Introduction
In this introduction, we explain what TSL is. We show

you how to run the examples and briefly discuss the
Look and Feel of Motif.
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.

This guide contains a number of examples which will help you
understand TSL. These are provided on the distribution tape and should
be installed in the directory $TQL_CLIENT_DIR/demos/tsl.
TQL_CLIENT_DIR is an environment variable used to define the
directory where the TQL Servers clients can be found. If you are using
the Bourne or Korn shell, use the following syntax to set the
TQL_CLIENT_DIR environment:
2 TSL Guide & Reference
TQL_CLIENT_DIR=/users/tqlclients
export TQL_CLIENT_DIR
If you are using the C shell, use the syntax:

setenv TQL_CLIENT_DIR /users/tqlclients
(substituting, of course, the directory in which you have installed the

TQL Servers clients for /users/tqlclients).
To run TSL you must ensure that the directory $TQL_CLIENT_DIR/bin is
defined as part of your PATH environment variable.
This is a special UNIX environment variable which UNIX uses to
determine where to look for programs. If you are using the Bourne or
Korn shell, use the syntax:
PATH="$TQL_CLIENT_DIR/bin:$PATH"
export PATH

setenv PATH "$TQL_CLIENT_DIR/bin:$PATH"
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

setenv TB_TSL_SPEC_PATH $TQL_CLIENT_DIR/demos/tsl
Encrypted and normal TSL

Normal TSL scripts are plain text files which are easy to read. These
scripts can be encrypted using the tslcrypt utility to stop users
changing them. The tslcrypt utility is described fully in the Utilities
manual. Normal TSL scripts should use the suffix .tsl and files
generated by the tslcrypt utility always use the suffix .tse.
When TSL is invoked with a filename that has a .tsl suffix, TSL first
looks for this file in the directories specified by the TB_TSL_SPEC_PATH
environment variable. If it cannot find the file, it looks for the file in the
current directory.
If the file cannot be found in the current directory, the above process is
repeated. This time however, TSL searches for the encrypted version of
the filethat is, substituting the suffix .tse for .tsl.
For example, if TSL is invoked using the command:
tsl example1.tsl
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.

Before shipping an application based on TSL scripts to a customer it is
advisable that the application developer checks the syntax of the TSL
scripts. This can be done using the TSL syntax checker, tslcheck. The
tslcheck utility is described fully in the Utilities manual.
The tslcheck program can be used on individual TSL scripts or it can
be used on a directory in which case it checks all the files that have the
suffix .tsl. The tslcheck program does not check encrypted TSL
scripts.
The Look and FeelMotif

The general visual effect and behaviour of user interface elementsthat
is, buttons, sliders and windowsis called the Look and Feel. There is
only one Look and Feel available for TSL on workstations: Motif.
Chapter
TSL Basics
2
TSL Basics
In this chapter, we introduce the basic components of a

TSL script file: commands (especially QUERY), text lines,
and comments. We also describe TSL procedures which
can be used to group sequences of TSL commands
together.
We give illustrations of the main window and a help
window.
We conclude with a description of attributes, icons and
dimension units.
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
These commands allow you to declare and set multiple variables in a

single command. Multiple occurrences of DECLARE and SET commands
are collected and sent to the server in a single query wherever possible.
TSL makes use of a number of special variables. The names of these
variables begin with %, for example, %MENUVAL. Be careful not to define
variables that start with %.
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
The keyword defproc must be followed by the name of the procedure.

This must start with a letter and may be followed by a sequence of
Chapter
TSL Basics
letters or numbers. For example q2 is a valid procedure name but 2q is

not.
The procedure name must be followed by a list of parameters (private
variable names) in parentheses. A parameter name may be preceded by
the keyword var, which means that it is passed by reference (described
later). If there is more than one parameter, they are separated by
commas.
This is followed by the TSL commands which make up the body of the
procedure. You can do anything within a procedure except define
another procedure (but you can call a procedure).
The end of a procedure is marked by the endproc command, though
you can return from a procedure before the end of a procedure using
the return command.
A procedure is invoked or called through the use of the call
command, the syntax of which is:
call procname ( arglist )
where procname is the name of a previously defined TSL procedure

and arglist is a comma separated list of variables or expressions
where each argument corresponds to one of the procedures
parameters.
As mentioned above, procedures can take a number of parameters
which can be used to modify the behaviour of the procedure each time
it is called. In the definition of the procedure, these are declared in
parentheses immediately after the procedures name.
Parameters are essentially variables into which the arguments passed to
the procedure are placed when the procedure is called. These variables
are local, in other words they are private to the procedure.
There are two types of parameters: passed-by-value and passed-byreference. Parameters that are passed by value are copies of the passed
argument. Therefore, if you change the value of a parameter that was
passed-by-value, the original variable is not changed by the procedure.
However, parameters that are passed-by-reference are referring to the
passed argument and are not copies. So if you change the value of a
parameter that was passed-by-reference, the value of the variable that
was passed to the procedure is also changed. Only variables can be
passed by reference.
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
Here a procedure is defined which is called factorial and has one

parameter x which is passed by reference, because it was preceded by
the keyword var.
Parameters which are passed by value do not have the keyword var
placed before their name. In addition a procedure can have several
parameters, but they must be separated by commas
For example:
defproc proc2(x, y, var z, t)
defines a procedure proc2 which is has four parameters where x, y and

t are passed-by-value and z is passed-by-reference.
A call to a procedure must supply values (or arguments) for all of the
procedures parameters. Thus a valid call to the procedure proc2 might
look like this:
call proc2(12, "Part 1a", name, 3.2)
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
In this example, [A] is a text item. The value of A will be determined,

for example 23.4, and substituted in the line to become:
The value of A is 23.4
This line is then output as normal.

A text item gets its value in one of three ways and is evaluated in the
following order:
1.
If the item begins with the character $, it is assumed to be a UNIX

environment variable.
2.
Otherwise, the item is assumed to be a column name and is looked

up in the query buffer. The query buffer is described in Chapter 5.
3.
If the item is neither of the above, it is assumed to be a TQL

expression and is evaluated on the server.
When a text item occurs in a command it is replaced by the value which

is stripped of spaces. This process is called text substitution. When a
text item occurs in a text line it is printed according to its field length
and fraction length in the database. There are also a number of
commands that affect the expansion of text items and these are
explained in a later section.
Care must be taken when using text substitution to assign values to
variables where the type returned is not a number. In the case of
strings, dates, times and complex numbers, the result must be enclosed
by additional characters.
Strings must be enclosed by double or single quotes. For example:
declare aString "[stringValue]"
Dates, times and complex values must be enclosed by escaped square

brackets. This is done by putting a backslash character \ in front of the
open square bracket. The brackets must be escaped to ensure that text
substitution is not performed on the outer square brackets. For
example:
declare aDate \[[dateValue]]
Text substitution cannot be performed on items of type blob (binary

large objectsee the TQL Guide and Reference).
Because text items can occur in almost all script lines, you need to be
careful if you want to print a square bracket or if a QUERY command
contains a square bracket. TSL sees the bracket and tries to find a text
item following itthis may result in errors. Use the backslash character
13
Chapter
TSL Basics
to escape a square bracket or any other character to make sure it is not

read as a text item. A common problem is in QUERY commands that
search on dates, the correct format is:
query display * from results where testdate>\[24/6/90]
For some TSL commands, text substitution is performed only on

selected fields and arguments. For example, the CALL command calls a
TSL procedure and defines the parameters to be passed to the
procedure. Its syntax is:
CALL procname ([arguments])
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]
where procvar is a variable that holds the name of a TSL procedure to

be executed and argvar is a variable holding the arguments to be
passed to the procedure. The value of procvar and argvar may
change according to, for example, options selected by the user within a
menu or dialog.
The main uses of text items are:
Printing data items in a report
Modifying query commands based on data in the application
Substituting all or part of a command with the value held in a

variable
This guide gives examples of all these techniques.

It is important to understand the different roles of the TSL interpreter
and the TQL Server in running your application. The TSL interpreter
reads the script and handles all the details of the user interface, flow
control and printing. The TQL Server handles all aspects of data
retrieval and data manipulation at the request of the TSL interpreter.
For example, when the following command is executed
query display * from results ;
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.
The main window

All applications created by TSL look and behave similarly.
When TSL starts to execute your script it creates a main window. This
window consists of a menu bar at the top of the window, a central
work area and a vertical and horizontal scroll bar. In addition, some TSL
applications may have a toolbox positioned to one edge of the central
work area. The window may also have decoration such as minimise
15
Chapter
TSL Basics
and maximise buttons, but this depends on the window manager you
are using and how it is configured.
Figure 1 Main window

The windows size, position, colour, font and scroll bars are all
configurable either via a configuration file or via command line options
to TSL.
Initially the only entry on the menu bar is Help and there is no toolbox,
but you will use TSL commands to build a menu system and/or a
toolbox suited to your application. By clicking on items on the menu
bar the user can pull down a pane of menu options which drive your
application. Clicking on a menu action or a tool will initiate an action
which could produces a report or displays a dialog. These dialogs are
separate windows which are displayed on top of the window. The user
sets values in the dialog and then dismisses it to continue with the
application.
The central work window is where all text output in your script is
output by default. It is used to see reports and other data displays. The
window can be scrolled up and down and left and right using the
The Help menu
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.
The Help menu

TSL always creates a Help menu item on the right hand side of the
menu bar. Selecting the Help menu brings down a menu pane with two
entries: On Revision... and On Application.... If you select the
former, a window is displayed that gives the version of TSL, TQL and
the underlying X Toolkit that you are using. The On Application
action can be configured to display your own help information for the
application that you are writing.
When application help is requested TSL displays the contents of the
current help file if one is defined. The current help file is defined using
the HELPFILE command.
helpfile apphelp.hlp
Notice that the filename is not in quotes.

The help file is a simple ASCII file which is read and displayed in the
help window.
Help is displayed in a dialog box and is limited to 2,000 characters. The
dialog remains on the screen until the OK button is selected. The
application continues however even while the dialog box is displayed.
Figure 2 Help window in Motif
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.
TSL and Window managers

The only aspect of the window decoration that can be changed by TSL
is the window title. This can be set using the TITLE command. For
example:
title "Test System"
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
or define the environment variable XBMLANGPATH.

The XBMLANGPATH variable is a colon separated list of directories in
which to search for the bitmaps and can be defined in the C shell using
the command:
setenv XBMLANGPATH "dir1/%B:dir2/%B: :dirN/%B"
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
If no letter is given, grid units are assumed.

For example:
10c
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
Menus & Toolboxes

3
Menus & Toolboxes
In this chapter, we describe how to create menus and

toolboxes so that the end user can interact with your
application.
Starting from a very simple menu, we build a multi-level
menu system and a toolbox and show how it might be
used in a real application.
23
Chapter
Menus & Toolboxes

The TSL user interface provides three methods for interacting with the
user: menus, tools and dialogs. Menus and tools are used for indicating
actions; dialogs are used for defining properties of those actions. A
menu allows the user to select actions such as Exit, Print Report,
Setup Graph. These actions either lead directly to an operation being
performed or display a dialog with some properties of that action to be
set; for example, what data is to be printed.
A pull-down menu system consists of a number of entries on the
menubar. When the user selects one of these entries a small window or
pane appears close to it. This pane contains a number of menu entries.
Selecting one of these entries may perform the specified action or may
display a further menu pane. When a menu entry leads to a further
menu pane it is called a cascading menu.
Figure 3 Diagram of a menu system

Using the mouse, the user navigates through the menu system by
clicking on options from the pull-down and cascading menus.
Menus can also be activated using the keyboard, and TSL provides
support for this capability through the definition of mnemonics and
accelerators. A mnemonic is single character, indicated in the menu
entry by an underline, that can be used to display a menu when
pressed with the Menu key. An accelerator is a sequence of keys that
can be used to activate the action associated with a menu without
actually causing the menu to be displayed. The accelerator key
sequence is usually contained in the menu entry to the right of the
label.
A group of top level menu entries and pull-down and cascading panes
define a menu hierarchy. Each entry in the hierarchy can be identified
by a string of numbers. For example, the leftmost menu entry in the

menu bar is item 1; the second menu item in the pane which pulls
down from menu item 1 is 1-2; the first menu item on the pane which
cascades from this item is 1-2-1. Clearly each entry in the menu
hierarchy can be easily identified in this way.
By default, the size of the menu system is limited to 20 items in any
menu pane and the number of levels to which a menu may be nested is
5. However, these upper limits may be altered using the application
resources maxMenuItems and maxMenuNesting. For more information,
see X Resources and the Applications defaults file on page 161.
A menu system is defined in TSL by associating a label and an action
string with a menu identifier using the MENU command. For example:
menu 1-1 "Open Database"
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.
Figure 4 Diagram of a toolbox
25
Chapter
Menus & Toolboxes
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"
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
Menus & Toolboxes
An alternative to the REPEAT command is the WHILE command. This

command defines a loop which is executed while the specified
condition remains TRUE. Unlike the REPEAT command, the condition is
tested at the top of the loop and so if initially FALSE the loop is never
entered.
Loops can be nested and it is usual to indent the nested commands to
help indicate the program structure.
Notice how the menu system was defined outside the loop. Remember,
you can only define the menu system once. It is not possible to add
new menu items once the ASKMENU command has been executed.
A multi-level menu system

A menu system with multiple pull-down panes and cascading panes is
constructed in exactly the same manner by specifying other menu
entries. The following example defines two menu panes, the second of
which has a cascading pane.
# Multilevel Menu (example2.tsl)
#
title "Multilevel Menu"
menu 1 "Database"
menu 1-1 "Open" action = "Open"
menu 1-2 "Close" action = "Close"
menu 1-3 "Drop" action = "Drop"
menu 2 "Reports"
menu 2-1 "Setup Details" action = "Setup"
menu 2-2 "Print Report"
menu 2-2-1 "To Printer" action = "To Printer"
menu 2-2-2 "To File" action = "To File"
repeat
askmenu
Value of %menuval is [%MENUVAL]
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,
A multi-level menu system
to be displayed in the menu pane. Separators are useful for grouping

together similar actions in the menu.
In this example, we have used a text line to print out the value of the
variable %MENUVAL. Notice how the text line contains a text item, in this
case %MENUVAL, in square brackets. In a real application you will want
to perform some action based on the value returned from the menu.
One way of doing this is to use the IF command. The loop might then
look like this:
repeat
if %menuval="Open"
query open db ;
endif
if %menuval="Close"
query close ;
endif
The IF keyword is followed by a condition. This condition is evaluated

and if TRUE, the lines following the command up to the ENDIF
command are executed. If the condition evaluates to FALSE or NULL, the
lines are not executed. The IF command is used extensively to control
the logic of the application.
We can also use the ELSE command, for example:
if %menuval="To Printer"
set outdev "printer" ;
else
set outdev "file" ;
endif
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
Menus & Toolboxes
elif %menuval="Drop"
query drop database db ;
endif
Mnemonics and Accelerators

Some users may prefer to access the menu system using the keyboard,
and TSL allows you to define mnemonics and accelerators to help these
people interact efficiently with your application.
A mnemonic is defined by preceding the appropriate character in the
menu label with the character @. For example:
menu 1 "@Database"
menu 1-1 "Set @Password..." action = "Password"
menu 1-3 "@Exit" action = "Exit"
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 :
where modifier is typically Ctrl or Shift, and key is the appropriate

key. For example:
Ctrl<Key>E:
Shift<Key>1:
Ctrl<Key>Q:
When the accelerator key sequence is entered in the TSL main window,
the ASKMENU command will return as if the menu entry associated with
Skipping menu items
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"
If an accelerator label is not provided, the keysym definition itself will

be used as the label.
Accelerators should be defined for commonly used actions and should
be used consistently across all applications.
Skipping menu items

When developing TSL applications you may reach a point where you
no longer wish to provide a particular action which is initiated by
selecting a certain menu item.
menu
menu
menu
menu
1-1
1-2
1-3
1-5
"@Open Database" action = "Open"

"@Drop Database" action = "Drop"
"@Close Database" action = "Close"
"@Exit" action = "Exit"
The above code outlines the menu structure of a simple application

which allows the user to open, drop and close a database and to exit
the application. Assuming that you no longer want users to be able to
drop a database from this application, you could comment out the
second line, as follows.
#menu 1-2 "@Drop Database" action = "Drop"
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
Menus & Toolboxes
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
"@Open Database" action = "Open"

"@Drop Database" action = "Drop"
"@Close Database" action = "Close"
"@Exit" action = "Exit"
skip
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
A menu system and toolbox in a real application
TOOLGAP = 10p (ten pixels)

GROUPGAP = 10p (ten pixels)

A real application is typically organised into a number of scripts. Each
script is responsible for implementing one or perhaps a few related
actions from the menu system and toolbox. The main script defines the
menu system and toolbox and the TSL procedures used by the
application, and executes the subsidiary scripts or procedures
depending on the menu or tool item that was selected.
This is the recommended way of organising an application because it
isolates the functionality of each report, graph or analysis into a single
file or procedure. At the same time it provides a structure which easily
adapts to new functionality being added.
If several procedures are used it is recommended that the procedures
are defined in additional scripts which are executed before the ASKMENU
command is executed.
The organisation of the main script is thus:
initialisation e.g open database, create variables
define menu system
define toolbox
define procedures
repeat
askmenu
execute scripts or procedures based on item selected
until quit
tidy up
Scripts are executed using the SCRIPT command:

script report.tsl
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
Menus & Toolboxes
unless they are dropped by doing a QUERY DROP VAR command. In

addition scripts can use the variables defined in the script or procedure
which executed it.
We have seen how the IF command can be used to execute parts of a
script based on the value of %MENUVAL. More convenient and much
more efficient is the SWITCH command, an example of which is shown
below.
# Multilevel Menu and Toolbox with Switch (example3.tsl)
#
title "Switch Command"
menu 1 "@Database"
menu 1-1 "@Open" action = "Open"
menu 1-2 "@Close" action = "Close"
menu 1-4 "@Exit" "Ctrl<Key>E:" "Ctrl-E" \
action = "Exit"
menu 2 "@Reports"
menu 2-1 "@Setup Details" "Ctrl<Key>D:" "Ctrl-D" \
action = "Setup"
menu 2-2 "@Print Report"
menu 2-2-1 "To @Printer" "Ctrl<Key>P:" "Ctrl-P" \
action = "Printer"
menu 2-2-2 "To @File" "Ctrl<Key>F:" "Ctrl-F" \
action = "File"
toolbox gravity = north frame = false
tool 1 "Kingfisher"
tool 1-1 "kingfisher" action = "Kingfisher"
repeat
askmenu
switch %menuval
case "Open"
Open Database
case "Close"
Close Database
case "Setup"
Setup Details
case "Printer"
To Printer
case "File"
To File
case "Kingfisher"
Kingfisher
endswitch
The SWITCH keyword is followed by an expression. This expression is

evaluated and is compared in turn with the result of evaluating the
expression that follows the CASE keyword. If the results are the same,
the lines between the CASE command and the next CASE command or
ENDSWITCH command are executed. If the switch value does not match
any of the case values, no lines will be executed (unless OTHERWISE is
used). If the value matches more than one case value, only the
commands associated with the first such case are processed.
The SWITCH construct is a very concise and efficient way of specifying
multi-way branches and is well suited to use after an ASKMENU
command.
We have now covered nearly all there is to know about building menu
systems and toolboxes in TSL. You should be able to create quite
sophisticated menu systems and toolboxes and be able to control the
execution of various operations based on the results of the menu
system and the toolbox. Implementing such functionality in C would
take hundreds of lines of code and would require detailed knowledge
of the underlying toolkits.
35
Chapter
Dialogs
4
Dialogs
Dialogs are the third and very important way of

interacting with the end user. Some dialogs, known as
convenience dialogs, are created for you but most
dialogs must be created by you from the available
dialog items.
This chapter describes each dialog item type in detail,
gives an example of its use and shows you how to
preset a dialog with values from a database. It explains
how to enhance the layout of a dialog and define the
position of each dialog item.
The final sections describe how to manage multiple
dialogs, list editing commands and how the sensitivity of
dialog items can be used.
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.
Figure 5. A dialog window

A dialog is made up of a main area, a control button area and possibly
an application-defined button area. The main area contains a number of
dialog items, such as labels, text fields and sliders.
The control button area is positioned at the very bottom of the window
and contains a number of standard control buttons. These are OK,
Apply, Cancel, Close, Reset and Help. All dialogs have a Help button
but you can choose which other control buttons you want in a dialog
by setting the dialogs mode using the DIALOG LAYOUT command.
If you define any button dialog items that are not to be put in the main
area, TSL creates an application defined button area. This area is
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:
The error dialog
The information dialog
The progress dialog
The confirmation dialog
The list selection dialog
The file selection dialog
39
Chapter
Dialogs
The error dialog

An error dialog is used to display an error message. The dialog is
displayed and can be dismissed by pressing the OK button. The
application does not continue until the dialog is dismissed.
Figure 6 An error dialog

The error dialog is displayed using the ERROR command:
error "No data selected"
The information dialog

The information dialog conveys information to the user. Unlike an error
dialog, the application continues to run while the information dialog is
displayed. The dialog is dismissed by clicking the OK button.
Figure 7 An information dialog
The information dialog is displayed using the INFO command:

info "Selecting data to plot"
Because the application continues to run when the information dialog is

displayed, other INFO commands can be executed. In this case the new
message is displayed in the currently displayed window, resizing it if
necessary.
The progress dialog
An information dialog may be used to display status information or

work-in-progress messages. However, the information dialog does not
offer the user the opportunity to stop the operation.
If an INFO command is executed with no message specified and an
information dialog is displayed, the dialog is dismissed. When using
INFO commands you should ensure that the dialog is dismissed at the
end of your busy sequence so that if the user does not dismiss it
explicitly it does not clutter the display.
The progress dialog

A progress dialog displays status information or work-in-progress
messages. It is particularly useful when the user has selected an
operation that takes a long time to complete. Displaying a progress
dialog helps the user to understand why the application is busy.
The dialog displays two buttonsthe Close button dismisses the dialog
but allows the operation to continue while the Stop button interrupts
the process. If the user dismisses the dialog with the Stop button, the
special variable %STOPPED is set to TRUE.
Figure 8 A progress dialog

The dialog is displayed using the PROGRESS command:
progress "Retrieving data"
Note that this command must appear within a TRY/RECOVER/ENDTRY

block, which defines the operations that the dialog provides progress
information for and the recovery steps needed if the user stops the
operation.
For example:
try
progress "Retrieving data"
query open nprdb ;
41
Chapter
Dialogs
query select * from route_wk;

recover
query close ;
endtry
if %stopped
info "The operation has been stopped"
endif
In this example, the application displays a progress dialog whilst

opening a database and retrieving data from one of its tables. If the
operation fails, the application closes the database. If the user chooses
to stop the operation, an information message is displayed.
If a PROGRESS command is executed with no message specified, the
dialog is dismissed automatically.
The confirmation dialog

A confirmation dialog is used to get a Yes or No response from the user.
It is often used to obtain confirmation for potentially dangerous or data
damaging operations, such as dropping tables in the database or
deleting rows. Like the error dialog the application stops execution
while the dialog is displayed, and only continues when the user
dismisses the dialog.
Figure 9 A confirmation dialog
The dialog is displayed using the CONFIRM command:

confirm "Do you want to Exit?" "Yes, Exit" "No"
The command keyword is followed by three strings: the message, the

label for the Yes button and the label for the No button. The result of
the dialog is returned in the variable %CONFIRMVAL. If the user presses
the leftmost button, the Yes button, the value of %CONFIRMVAL is set to
TRUE; otherwise it is set to FALSE.
The following example shows a typical use of a confirmation dialog in

protecting exit from a script:
# Confirmation (example4.tsl)
#
title "Confirm Exit"
menu 1 "Database"
declare quit false
repeat
askmenu
if %menuval="Exit"
confirm "Do you want to Exit?", "Yes, Exit", "No"
if %confirmval
set quit true
endif
endif
until quit
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.

The list selection dialog is used to obtain an input value from the user
where that value is likely to be in a known set of values. It is often used
to display a list of names or identifiers about which a report or graph is
to be produced. The user is presented with a list of options and can
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.
Figure 10 A list selection dialog

The dialog is displayed using the SELECT command:
select "Choose a Batch" "L123/45" "L343/45A" "L23/34"
The command keyword is followed by a string which is used as the

label of the text field in the dialog and then a list of strings which are
put into the scrolled list in the dialog.
When the dialog is dismissed using the OK button or by double clicking
on the list, %DIALOGVAL is set to TRUE, %BUTTONVAL is set to OK and
the value selected is returned in the variable %SELECTVAL. If the dialog
is dismissed using the OK button but no value was selected,
%SELECTVAL is set to the empty string ("").
If the dialog is dismissed using the Cancel button, %DIALOGVAL is set to
FALSE, %BUTTONVAL is set to Cancel and %SELECTVAL is set to NULL.
The list can also be populated from the database using the same
technique as used for list dialog items, which is described later in this
chapter.

The file selection dialog is used to obtain the name of a file from the
user. This is often used to enter the name of a data file that is to be
loaded into the database or the name of a file into which a report is to
be generated. The dialog allows the user to browse through directories
to find the appropriate file and also provides facilities for searching
using wildcards (for example *.data). The application only continues
when the dialog is dismissed.
Figure 11 A file selection dialog

The dialog is displayed using the SELECTFILE command:
selectfile "Choose a File" "*.data" "/usr/local/data"
The command keyword is followed by three strings: the first specifies a

label to use for the text field in the dialog; the second, which is
optional, specifies a wildcard pattern to use when searching for files;
and the third, which is also optional, defines the initial working
directory. If the wildcard is omitted, all files are displayed and, if the
working directory is omitted, the current working directory is used.
When the dialog is dismissed using the OK button the variable
%FILEVAL is set to the full pathname of the selected file, %DIALOGVAL is
set to TRUE and %BUTTONVAL is set to OK. If the dialog is dismissed
45
Chapter
Dialogs
using the Cancel button, %FILEVAL is set to NULL, %DIALOGVAL is set to

FALSE and %BUTTONVAL is set to Cancel.
Text substitution in convenience dialogs

In many situations, particularly when displaying errors, it is important
to be able to include data in a message. For example, suppose you
want to display an error message indicating that no data could be found
in the database for a particular test number. This can be achieved by
putting a text item in the message string.
error "No data found for test [testno]"
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
While the dialog is displayed, the %DLOGCHANGED system variable

indicates whether the user has changed the value of any of its items
by selecting a toggle, for example, or typing text in a field. Initially, the
variables value is FALSE. As soon as the user changes the value of a
dialog item, %DLOGCHANGED is set to TRUE. Whenever an ASKDIALOG
command is executed, the value of %DLOGCHANGED is set to FALSE.
Note that time range bars, calendars and user-defined or standard

buttons do not affect the value of %DLOGCHANGED. Using these
items in a dialog may give unexpected results when used in
conjunction with %DLOGCHANGED.
When the user presses one of the control buttons or an application
defined button, or changes the value of an active dialog item, the dialog
is deactivated and the special variables %DIALOGVAL and %BUTTONVAL
are set to indicate to the application what action occurred.
%BUTTONVAL is set to the action string of the dialog action that occurred.
For control buttons, this is the string containing the buttons label, for
example, OK or Cancel. Dialog items and application defined buttons
use their ACTION attributes value.
%DIALOGVAL is set TRUE if the user presses a button that causes the
dialog to be applied (that is, causes its variables to be set), for example
the OK or Apply buttons; %DIALOGVAL is set FALSE if the values are not
to be used, for example if the Cancel button was pressed.
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"
47
Chapter
Dialogs
repeat
askmenu
if %menuval="Popup"
dialog text(12) s "Enter a string"
askdialog "Dialog"
if %dialogval
OK Pressed. String is [s]

else
Cancel Pressed.
endif
endif
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"
Dialog item types
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
Text field [s]

Slider [h]
Toggle [t]
Option [o]
endif
endif
Dialog item types

The last example introduced three new dialog items: a slider, toggle
button and option menu. There are twelve different dialog types all of
which can be used freely in a dialog. Each dialog item type has
characteristics that make it particularly useful for certain types of data.
Some dialog items only return data of a certain type (for example, string
or boolean). The table below shows all the available types with some
brief comments on their usage.
Data
Types
Comments
TEXT
All
data
types
Allows simple keyboard

entry. Data is checked to be
the correct type.
Multiline
Text field
MULTITEXT
string
Allows entry of longer strings

or notes
Slider
SLIDER
short/
long/
byte
Allows quick input of a

number within a range
Dialog Item
Keyword
Text field
49
Chapter
Dialogs
Dialog Item
Keyword
Data
Types
Comments
Toggle
button
TOGGLE
bool
A simple on/off item.
Option
menu
OPTION
string
Allows one of a set of values

to be selected.
Scrolled list
LIST
string
Allows one or more values to

be selected from a list.
Exclusive
panel
PANEL
string
Allows one of a set of values

to be selected.
Calendar
CALENDAR
date
Allows a date to be selected.
Time range
bar
TIMERANGE
time
Allows one or more time

ranges to be defined.
Label
LABEL
none
Creates a subtitle within a

dialog.
Button
BUTTON
none
Initiates dialog actions.
Skip
SKIP
none
Skips one or more columns.
The following example contains DIALOG commands for each of these

types:
dialog
dialog
dialog
dialog
dialog
label "A Label"

skip
text(8,12) txtvar "Text"
slider(100) svar "Slider" 0 100
option optvar "Option" \
"Choice 1" "Choice 2" "Choice 3"
dialog toggle toglvar "Toggle"
dialog list(4) listvar "List" \
"Choice1" "Choice2" "Choice3" "Choice4" \
"Choice5" "Choice6" "Choice7" "Choice8"
dialog panel panlvar "Panel" \
"Choice1" "Choice2" "Choice3" "Choice4"
dialog multitext(40,4) notes "Notes"
dialog button "aButton" action = "Button1"
Text fields
The above sequence of DIALOG commands builds a dialog whose

appearance is shown below.
Figure 12 Motif dialog

As you can see, all dialog item commands have roughly the same
syntax. The DIALOG keyword is followed by a keyword that identifies
the dialog item type (TEXT, MULTITEXT, SLIDER, TOGGLE, OPTION,
LIST, PANEL, LABEL, BUTTON or the pseudo-item SKIP). SKIP just tells
TSL to leave a gap when it is positioning the items in a dialog. In all
other cases, there then follows:
1.
The name of the variable associated with the data item (except for
buttons and labels)
2.
The item label (which has a maximum length of 60 characters)
3.
Any item specific values
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
When a text field is displayed in a dialog it has a display length (how

many characters can be seen in the field), and a maximum length (how
many characters can be entered in the field). If the maximum length is
bigger than the display length, the text scrolls horizontally as more
characters are entered. The display length and maximum length are
specified in brackets after the keyword TEXT. So for example:
dialog text(8,30) fname "Filename"
specifies a display length of 8 and a maximum length of 30. If the

maximum length is not specified, it defaults to the display length, so:
dialog text(10) testname "Test name"
has a maximum length equal to the display length of 10 characters.

By default, a text field returns a string value to its associated variable.
However, a text field can be set to return data in any of TQLs data
types by preceding the keyword TEXT by one of the types BYTE,
SHORT, LONG, SHORTREAL, REAL, COMPLEX, STRING, DATE, TIME,
CHAR or BOOL. For example:
dialog real text(12) volts "Voltage"
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.
Figure 13. Range error message dialog.

Range checking does not catch users submitting NULL valuesthis can
be done by setting the ALLOWNULL attribute. Then, when a dialog is
submitted, if the ALLOWNULL attribute for a text field evaluates to FALSE,
TSL generates an error dialog. The message in the error dialog may be
set by you by defining a value for the NULL_ERR_MSG attribute, or TSL
generates its own message:
Figure 14. NULL error message dialog.

Range checking and testing for NULL values is performed when the
dialog is submitted, either by pressing 2., $SSO\ or one of the userdefined buttons or by changing the value of an active dialog item.
ASKDIALOG does not return until acceptable values have been entered
in all the dialogs text fields.
53
Chapter
Dialogs
Occasionally you might want to create a read-only text field, by setting

the READONLY attribute to a value (or expression) which evaluates to
TRUE. This means that the user cannot modify the contents of the text
field, but is different to an insensitive text field in that it is displayed
clearly and can be selected. This could be useful as a dynamic label.
If you use the DIALOG LABEL command to create a label, the label is
fixed unless you destroy and recreate the dialog. However, if you create
a read-only text field you can change the text field before the dialog
opens using ASKDIALOG, by changing the value of the variable
associated with the text field.
You should be aware that, if you use the READONLY attribute in
conjunction with RANGEMIN, RANGEMAX, and/or the ALLOWNULL attribute,
TSL will abort rather than displaying an error dialog if the value in the
text field is not acceptable.
# Range Checking in Text Fields and Read-Only
# Text Fields (example7.tsl)
#
title "Range Checking Text Fields"
menu 1 "Dialog"
declare mindate adate(1,1,70), maxdate adate(31,12,99)
dialog date text(8) mindate "Minimum date" \
readonly = true
dialog date text(8) maxdate "Maximum date" \
readonly = true
dialog date text(8) val "Text date" \
rangemin = mindate, rangemax = maxdate, \
allownull = false, \
null_err_msg = "Please enter a test date"
repeat
askmenu
if %menuval="Popup"
askdialog
if %dialogval
Test date is [val]
endif
endif
0XOWLOLQH7H[WILHOGV
You can set the sensitivity of a text field by defining a SENSITIVE

attribute. An insensitive text field does not perform range checking or
test for NULL values. Insensitive text fields have their label and contents
greyed out and can not be selected.
Finally, you can define whether text entered in a text field is visible or
not using the SECRET attribute. Setting this to TRUE results in text
entered in this field not being displayed. Thus users could enter a
password without it being seen by other users. The default value for
this attribute is FALSE.
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
Multiline text fields can also use the READONLY, ALLOWNULL,

NULL_ERR_MSG and SENSITIVE attributes described in the section Text
fields on page 51.
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
This creates a horizontal slider whose value can be modified. If the

sliders value changes ASKDIALOG returns putting Slider in %BUTTONVAL
and TRUE in %DIALOGVAL. The dialog is not dismissed and the dialogs
variables are updated to take into account any changes that were made.
This happens when the value of an active dialog item changes and is
the equivalent to pressing the $SSO\ button.
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
might create a toggle button on a dialog that is displayed before a

graph is drawn. If users enable the toggle they are indicating that they
would like the mean value overlaid on the plot. Toggles are convenient
and easy to use for end users.
Toggle dialog items can have their sensitivity defined using the
SENSITIVE attribute and may be defined as an active dialog item using
the ACTION attribute.
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"
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
Notice that the LIST keyword is followed by the number of visible

elements in the list. If the list contains more than this number of
elements, scroll bars are automatically added and the user can scroll the
list up and down to select an item.
As you can see if you run the script, these three choice items provide
the same sort of functionalitypicking an item from a specified set.
Which dialog item you use depends on the exact circumstances and is
discussed in the style section later in this guide.
As with all dialog items, when the dialog first opens TSL creates any
variables associated with the dialog that do not yet exist. In the case of
lists and panels, the variable is set to NULL. For an option menu, the
variable is set to the first valid item. For example:
dialog option o "Option" "Option a" "Option b" \
"Option c"
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
declare t "Choice 1"

dialog list(3) t "List" "Choice 1" "Choice 2" \
"Choice 3" "Choice 4" "Choice 5" "Choice 6"
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
A vertical scroll bar is only created if the list contains

more than the number of items the list can display at
one time.
A vertical scroll bar is created even if the list does not

contain more than the number of items the list can
display at one time.
A vertical scroll bar and a horizontal scroll bar are

created when the list is initially created, whether they
are needed or not.
The default behaviour is to set SCROLLMODE to 0, where a vertical scroll

bar is created when it is needed.
Lists that use SCROLLMODE 0 and 1 always resize to fit the widest item in
the list. Therefore, if you have several narrow items and one wide item
the list resizes to accommodate the wide item. If you set the lists
scrollmode to 2, a horizontal scroll bar is created and the user is forced
to use the scroll bar to read the wide item.
The width of a list can be set using the MINWIDTH and MAXWIDTH
attributes. The values assigned to these attributes are the minimum
number of characters displayed in a row of a list and the maximum
number of characters displayed in a row of a list respectively.
59
Chapter
Dialogs
If the SCROLLMODE attribute is set to 0 or 1, the width of the list can

fluctuate between the minimum and maximum width of the list.
However, if the SCROLLMODE attribute is set to 2, the width is fixed to
the maximum width if it was defined and to the minimum width if the
maximum width was not defined.
The type of selection permitted for a list can be set using the
SELECTION_POLICY attribute which may take the following values:
Value
Meaning
SINGLE
Allows single selection. An item is selected by

clicking on it. This is the default.
BROWSE
Allows single selection. Clicking and dragging the

cursor through the list highlights each item in
turn. The highlighted item is selected when the
mouse button is released. An item may also be
selected in the same way as for SINGLE selection.
MULTIPLE
Allows multi-selection. An item is selected by

clicking on it.
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
Allows multi-selection. Similar to RANGE but several ranges

may be selected by pressing the &WUO key while selecting
ranges.
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:
%SELECTED holds a delimited list of the items that were selected
%NUMSELECTED records the number of items that were selected
&DOHQGDUV
%LISTPOS records the list position of each selected item in a

numeric array
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"
The calendar can be displayed with a preselected date by setting a

value in the items variable. For example:
DECLARE start_date \[5/1/98]
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
DIALOG TIMERANGE work_hours "Working Hours"
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
defines a time range bar that allows time selection to an accuracy of 5

minutes.
In addition, the number of ranges that can be defined can be set with
the MAXRANGES attribute. The default number is 50.
A time range bar may be an active dialog itemthat is, a dialog action
may occur if the value of the time range bar is changed. This is done
using the ACTION attribute. A time range bar may also use the
SENSITIVE attribute to determine whether the bar should be enabled
for the user.
/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
Place button in the application defined button area.
Place items in the main area.
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
dialog button "Next Customer" action = "Next"

dialog button icon "print.bm" action = "Print"
The second command creates an iconic button in the application

defined button area which uses the bitmap file print.bm.
Labelled and iconic buttons can also be created in the dialogs main
area using the above syntax, but also setting the AREA attribute to 1. In
addition labelled-iconic buttons can also be put in the main area.
dialog button "Define Printer..." icon "print.bm" \
area = 1, action = "Print"
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"
This defines a default labelled button in the application defined button

area. A dialog can only have one application defined button defined as
default.
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
Leakage Current. Given a parameter number, we wish to preset a text

field with the corresponding parameter name. The following example
uses an AS clause in the TQL DISPLAY command to assign a value to the
variable that is associated with the dialog.
query display paramname as pname from parameters
where param#=pno ;
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 ;
It is essential that you re-enable data display as soon as you have

finished the DISPLAY command. If you do not do this, the TSL
interpreter will fail later.
Another way of performing this operation is shown below.
query display paramname from params
where param#=pno ;
declare pname "[paramname]"
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:
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:
select "Parameter" paramname
The following example script demonstrates these techniques. The

example uses the KINGS database that should have been installed on
your system. The script creates a table in the database with a unique list
of Royal Houses, presets a scrolled list with the names and prints details
on the house when selected.
# Preset List (example9.tsl)

#
title "Preset List"
menu 1 "Report"
menu 1-1 "On Royal House..." action = "House"
# Construct a table with one row for each house
# and general information on their performance
#
query open kings ;
query sequence kings by house ;
query group kings by house
count kingno as numkings,
total until-accessn as reign ;
# Retrieve a list of all houses and put in dialog
#
query display house from rslt ;
dialog list(5) h "Royal House" house
repeat
askmenu
if %menuval="House"
askdialog
if %dialogval
query display * from rslt where house=h ;
The royal house of [norm(h)] had [numkings] monarchs
and reigned for a total of [reign] years
endif
endif
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 number of columnsCOLUMNS. This must be in the range 1 to

30.
Whether items are aligned within a columnALIGNITEMS.
Whether columns are fixed width down the rowsALIGNCOLUMNS.
Whether rows are fixed height across the columnsALIGNROWS.
The number of columns of user-defined buttonsBUTTONCOLUMNS.

This must be in the range 1 to 30.
Whether buttons positioned in the user-defined button area should

be centred in each column (the number of columns is set using the
BUTTONCOLUMNS attribute) or packed tightly together in the centre of
the dialogBUTTONLAYOUT. This can be set to either COLUMNCENTRE
or DIALOGCENTRE.
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"
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
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)
results in two positions in the dialog being skipped.
'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
Here the dialogs main area is defined to be fifteen centimetres wide

and nine centimetres tall. If either or both attributes are undefined, TSL
calculates the default value for the missing attribute. This is calculated
by assuming that all dialog items are in their normal positions.
Dialog items can also be positioned on a grid. The default size of the
grid is 100 grid units across the top and 100 grid units down the side of
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"
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 \
xpos = 1i, ypos = 0.6i, \

xorigin = centre, yorigin
dialog button "Next Part" \
action = "Next", area = 1
xpos = 1i, ypos = 1.1i, \
dialog multitext(10,5) descr
xpos = 3.5i, ypos = 0i, \
= top
\
= top
"Description" \
= top
repeat
askmenu
if %menuval = "Popup"
askdialog "Edit machine parts"
endif
until %menuval = "Exit"
The above generates a dialog which looks like this:
Figure 16. Dialog where the position of dialog items is defined.

Once TSL determines where it should place an item in a dialog it checks
to see if values have been assigned to the XADJUST and YADJUST
attributes. These are given dimension unit values and grid units may be
given. Both default to 0p, or 0 pixels. TSL determines the final position
of a dialog item by adding the XADJUST attribute to the x-position and
adding the YADJUST attribute to the y-position. The XADJUST and
YADJUST attributes are primarily used for setting the position of a dialog
item as an offset from its default position.
73
Chapter
Dialogs
The final attribute, LABELGAP, is only appropriate for complex dialog

items and it specifies the gap between the items label and main
component.
&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
The default configuration of 2. and &DQFHO.
2., $SSO\ and &DQFHO.
$SSO\ and 5HVHW.
&ORVH.
$SSO\, 5HVHW and &ORVH.
$SSO\ and &ORVH.
All configurations also have a +HOS button.

For example:
dialog layout mode=2
sets the dialog to use $SSO\ and 5HVHW buttons.
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
dialog not dismissed.
&ORVH
"Close"
FALSE
dialog dismissed.
Notes
Closing a dialog using the window manager menu or an accelerator

such as $OW) is identical to pressing the &DQFHO button.
When a button is pressed that does not dismiss the dialog, the dialog
remains displayed on the screen but all the control buttons, application
defined buttons and dialog items are made insensitivethat is, they
cannot be pressed. The dialog only becomes active again when the next
ASKDIALOG command is executed. At this point the control buttons are
made sensitive and the user can again interact with the dialog.
75
Chapter
Dialogs
The appearance of the dialog while it is insensitive is controlled by the

DIALOG LAYOUT attribute BUSYONAPPLY. The default value of this
attribute is set by the resource Tsl.busyOnApply, but if this resource is
not defined, the internal default value is TRUE.
If BUSYONAPPLY is set to TRUE, the cursor changes to a busy-hourglass
and the dialog is desensitized (but not greyed out). If BUSYONAPPLY is
set to FALSE, the cursor remains the same but all the dialog items and
buttons are greyed out.
For good interactive performance you need to try to minimise the time
the application spends not processing an ASKDIALOG command for
these types of dialog. This gives the impression to the user that the
dialog is constantly active. If you need to close a dialog from TSL, you
can use the CLOSEDIALOG command. This command closes the current
dialog and does not change any of the associated variables.
Figure 17. Simple Editor dialog.

You should be familiar, now, with most of the features of dialog
including how to define dialog items, create and display the dialog and
dismiss the dialog. This example shows how a dialog might be used to
build a simple data editor using the TQL FETCH commands and also
demonstrates how the application defined buttons are used.
# Simple Editor - Demonstrates buttons (example12.tsl)

# A simple data entry application.
#
# Disable automatic abort on query error
#
abort off
# Create a simple table to browse
#
query open kings ;
query select fullname, house, accessn from kings ;
# Create the dialog preset with the first row

#
query fetch first from rslt ;
declare vfullname "[fullname]", vhouse "[house]",\
vaccessn [accessn]
dialog
dialog
dialog
dialog
layout columns=1 mode=3 buttoncolumns=2

string text(20) vfullname "Monarch"
string text(12) vhouse "House"
long text(6) vaccessn "Accession"
dialog
dialog
dialog
dialog
dialog
dialog
button
button
button
button
button
button
"First Row" action = "First"

"Last Row" action = "Last"
"Next Row" action = "Next"
"Prev Row" action = "Prev"
"Delete Row" action = "Delete"
"Add Row" action = "Add"
# Now build the menu system

#
menu 1 "Database"
menu 1-1 "Editor..." action = "Editor"
repeat
askmenu
if %menuval="Editor"
repeat
askdialog
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
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"
or, when naming dialogs:

askdialog print_options "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"
1..." action = "Popup 1"

action = "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
case "Popup 3"

askdialog 3
endswitch
&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
The identifier for this list would be cust.

There are five list manipulation commands: INSERT, DELETE, REPLACE,
APPEND and CLEAR.
The commands INSERT, DELETE and REPLACE must be told the position
in the list that is to be modified. The position can either be a number
representing the row in the list or the name of an item in the list. The
command INSERT accepts any row number greater than or equal to 0
but the DELETE and REPLACE commands only accept row numbers
between 1 and the size of the list. In addition, the INSERT, DELETE and
REPLACE commands do not accept as positions the name of an item that
does not exist in the list.
The special variable %LISTOK is returned and is set to TRUE if the list
command was given a valid position and FALSE if an invalid position
was given. The contents of the list are not modified if an invalid
position is given to the list command. For example:
81
Chapter
Dialogs
dialog list cust insert 4 "Customer 4"

dialog list cust delete "Customer 5"
if not %listok
error "Customer 5 does not exist in list"
endif
In addition to specifying the position in the list the INSERT, REPLACE

and APPEND commands need to be given a list of values. This is
specified in the same way that the initial values of lists, option menus
and panels are defined.
Finally the DELETE and REPLACE commands can be given an optional
number which specifies how many items in the list are to be effected by
the command.
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
dialog list cust delete 2
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"
The first command replaces the first occurrence of Customer 2 in a list

with new Customer 2.
The second command replaces values starting at the first position with
as many values as can be found in the query buffer for the column
fullname.
The last command replaces the first occurrence of the string Customer
5 and the value following this (the number of items to be replaced was
specified as 2) with the values new Customer 5, Customer 6 and
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
dialog list cust append "Customer 1" "Customer 2"
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
dialog list(10) dellist "Kings to delete" "" \

action = "MoveToSave", \
scrollmode = 2, minwidth = 15
dialog button "Delete Kings" action = "DelKings"
# Create menu system

menu 1 "Database"
menu 1-1 "Delete Kings " action = "Delete Kings"
repeat
askmenu
if %menuval = "Delete Kings"
# Create temporary table.
query create tmp as fullname primary ;
repeat
askdialog "Delete Kings"
switch %buttonval
case "MoveToDelete"
dialog list origlist delete "[origlist]"
dialog list dellist insert 0 "[origlist]"
query insert "[origlist]" as fullname
to tmp ;
case "MoveToSave"
dialog list origlist insert 0 "[dellist]"
dialog list dellist delete "[dellist]"
query delete from tmp
where fullname = "[dellist]" ;
case "DelKings"
confirm "Delete kings?" "Yes, Delete" "No"
if %confirmval
query display * from tmp ;
if %rows <> 0
info "Please wait... deleting kings"
# Disable abort on query error.
abort off
85
Chapter
Dialogs
query fetch first from tmp ;

repeat
query delete from rslt
where fullname="[fullname]" ;
query fetch next from tmp ;
until not %qok
# Clear the list of deleted kings.
dialog list dellist clear
# Delete the info dialog.
info
endif
endif
endswitch
until %buttonval = "Close"
# Drop temporary table.
query drop tmp ;
endif
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"
When the toggle is pressed, ASKDIALOG finishes and %DIALOGVAL is set

to TRUE and %BUTTONVAL is set to OutputChanged. Since %DIALOGVAL
is not FALSE the repeat loop is re-entered and the ASKDIALOG command
is repeated.
87
Chapter
The Query Buffer

5
The Query Buffer
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
The Query Buffer
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:
repeat
' Experiment [exp#] Voltage [volts]
next
forall
The REPEAT FORALL construct is used to traverse a query buffer. The

command keeps looping until the buffer position is past the end of the
bufferthat is, NEXT has been executed on the last row of the buffer
or before the start of the bufferthat is, PREV has been executed on the
first row of the buffer. So the loop above iterates until all the rows in
the buffer have been printed. The example below prints the same data
in the reverse order:
last
repeat
prev
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:
repeat
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
The Query Buffer
The query buffer and variables

When using the query buffer you should be careful of the names you
use for variables and for the columns in the query buffer.
When a DISPLAY query command is used, the data returned is stored in
the query buffer. Text substitution of a columns name can then be used
to access the data in the query buffer. For example:
query display fullname from kings ;
first
' [fullname]
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 ;
puts the following in the query buffer:

Edmund I
Athelstan
Edward
Alfred
Ethelred I
Ethelbert
Ethelbald
Ethelwulf
Egbert
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.
The query buffer and variables
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 ;
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 ;
first
repeat
set x "[names]"
' [x]
93
Chapter
The Query Buffer
next
forall
# A more efficient report
query open kings ;
first
repeat
' [names]
next
forall
The difference between example16.tsl and example17.tsl is easier

to see if you run TSL using the -debug command line argument to see
which queries are being evaluated.
Chapter
Reports
6
Reports
A common requirement is to produce reports derived

from the data in your database. In this chapter we show
you how to produce both tabular and free-style reports,
and how to send them to either the screen, the printer
or a file.
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.
Text expansion in reports

One area that requires careful control is that of the layout of text on a
line, and in particular how text items are expanded. The most useful
command that you can use to control the expansion of text items is the
TABLE command. This command is used to either enable or disable
table expansion mode and is followed by either ON or OFF. (If neither
is specified, ON is assumed.) Table expansion is best illustrated by an
example:
' Experiment Voltage

repeat
' [exp#]
[volts]
next
forall
This code fragment might produce a report such as:

Experiment
1
3
6
7
9
10
11
13
Voltage
23.45
25.42
22.12
22.15
25.45
24.62
23.84
24.28
This report is presumably not what is required and exhibits a number of

problems:
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
The Experiment column is left-justified
All of these problems are solved by enabling table expansion.

table on
' Experiment Voltage
repeat
' [exp#]
[volts]
next
forall
table off
This code fragment might produce a report such as:

Experiment Voltage
1
23.45
3
25.42
6
22.12
7
22.15
9
25.45
10
24.62
11
23.84
13
24.28
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:
' [descript] [result]
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]
TSL also provides a means of setting display and printer enhancements,

such as bold and underlining. An enhancement is specified by an
enhancement designator in the input file. Such a designator is a
character sequence beginning with @for example, @B. When a
designator is first encountered it enables the enhancements, the next
designator of the same type disables the enhancement. For example:
' This is @Bbold@B
The following enhancements are provided:

@B
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"
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
Notice how we have used an IF command to test whether the query

returned any rows. As mentioned earlier, TSL defines a variable %ROWS
which contains the number of rows retrieved by a query. You will
almost always need to check this variable before entering the REPEAT
loop that prints the report. This is because the code in the REPEAT loop
is always executed at least once even if the condition would have
evaluated false at the start of the loop.
Because a report is just another example of TSL code you can use IF
statements and other commands to produce quite complex reports. For
example you can arrange for special text to be printed when values
exceed ranges and so on. In the example above we might print a line of
text if the monarch survived more than 40 years.
table on
repeat
' [fullname] [title] [accessn] [until]
if [until]-[accessn] > 40
'
*** Monarch reigned more than 40 years
The PRINT and PRINTLN commands
endif
next
forall
table off
The PRINT and PRINTLN commands

The PRINT and PRINTLN commands provide a much more controllable
way of printing data in reports. However, using these commands
requires a little more work and can be more cumbersome for titles and
other annotation. But for standard fixed format columnar reports this is
the better way of approaching the task. You can if you wish mix both
techniques as you see fit.
The PRINTLN command prints either a single string or a series of data
items to the logical printerthat is, the screen or output file. The
characters are automatically terminated by a newline. The PRINT
command is the same except no newline is output and for the rest of
the section we will describe the PRINTLN command only.
The first form of the command simply takes a quoted string and prints it
on the output (the string can contain text variables). For example:
println "Daily Batch Quality Report"
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:
The name of a column that has been retrieved by a query
The name of a variable
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
designator which is introduced by a % character. If the data item is a

date, a time or a complex number, the format string could contain more
than one format designator.
The format designator uses the same syntax as the printf functions in
the standard C library. The designator is introduced by a %; there then
follows optional flags, a field length and fraction length and then the
format character. Examples of valid format strings are %8.2v kPa,
%10v, %H:%M.
The format string can specify either type dependent or type
independent formatting. Type independent formatting is specified by
using the v format character and allows data of any type to be printed
without prior knowledge of the data type. This allows your TSL script to
remain more independent of the database thus making it more resilient
to change. The v format character also handles NULL data properly by
filling the field with spaces. You can specify optional flags and field and
fraction lengths with this format character and they will be used as
appropriate to the data type.
Type dependent formatting is specified using any of the format
characters described below. As TSL uses the C library to implement this
functionality you can use other format characters that may be supported
by your system. However, characters not listed below do not operate
correctly with null data.
Format string syntax

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:
Zero or more flags, which modify the meaning of the format

specification.
An optional minus sign, which specifies left adjustment of the data

item in the field.
An optional digit string that specifies a field width. If the converted

value has fewer characters than the field width, the value is padded
with blanks. By default, the value is padded on the left. If the left
justification flag was given, the value is padded on the right. If the
field width begins with a zero the value is padded with zeroes.
instead of blanks.
An optional decimal point which separates the field width from the
next digit string.
An optional digit string specifying a fraction length. The fraction

length controls the number of digits that appear after the decimal
point.
A character, the format character, which indicates the type of

conversion to be applied.
The flag characters and their meanings are as follows:

-
Print the value left justified.
If the value is signed and numeric, print a sign

(+ or -) before it.
The format characters and their meanings are as follows:

d
Decimal integer. The data type should be byte, short

or long. The format character u can be used for
unsigned numbers.
Octal number. The data type should be byte, short or

long.
Hexadecimal number. The data type should be byte,

short or long.
Print the data item as a real decimal number in the

style ###.### where the number of digits following
the decimal point is the fraction length. If the fraction length is 0, no decimal point is produced. The
data type should be shortreal or real.
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
Print a percent sign.
If the data item is a complex number, the following characters can be

used:
x
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
The abbreviated weekday name for the current local

(for example, Mon).
The full weekday name for the current locale (for

example, Monday).
The abbreviated month name for the current locale

(for example, Jan).
The full month name for the current locale (for

example, January).
Country specific date and time format., defined in a

file given by strftime (4). The default is %a %b %e
%T %Z %Y, for example, Mon Feb 1 14:30:59 EST
1993.
Day of the month, in the format 01 to 31.
The date in the form %m/%d/%y.
Day of the month, in the format 1 to 31. Single digits

are preceded by a blank.

(for example, Jan).
Hour of the day, in the format 00 to 23.
Day of the year, in the format 001 to 366.
Month, in the format 01 to 12.
Minute of the hour, in the format 00 to 59.
Newline (\n) character.
String to denote a.m or p.m., in the format AM or PM.
Time in the form %I:%M:%S:%p.
The time in the form %H:%M.
Second, in the format 00 to 61 (61 permits leap

seconds).
Tab (\t) character.
Time in the form %H:%M:%S.
Week number in the year, in the format 00 to 53;

weeks start on a Sunday.
The weekday number, in the format 0 to 6, where 0

corresponds to Sunday.
Week number in the year, in the format 00 to 53;

weeks start on a Monday.
Country-specific date format, defined in a file given

by strftime (4).
Country-specific time format, defined in a file given

by strftime (4).
Year, in the format 00 to 99.
Year, in the format 1995.
Time zone name.
Format strings may also contain the enhancements @B, @U, @E, @1 and
@2. For example:
println mnth::"@UVariance Report for month %2v@U"
This underlines the given string.
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.
Simple page control

There are a number of other commands that control page layout, such
as margins and page length. TSL provides only basic control of these
attributes since the UNIX print spooler normally controls them for you.
They can be set in a PAGESTYLE command (described later in this
chapter), or the default page length can be set using the LENGTH
command:
length 60
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.
Free format reports

The reports we have described above are all quite structured and aim to
produce columnar printouts where the data is aligned and largely
regular. However, using the text handling features of TSL you can also
create free format reportsthat is, reports that do not have repeated
rows or fixed layouts. Just as we have used text lines to print simple
Free format reports
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]
Normally when a text line is encountered, the line is copied to the

output (after evaluating any text items), including the end-of-line
character. This means that end-of-lines in the input are preserved in the
output. Using the FILL command you can change this processing so
that TSL reads characters from the input file until it fills an output line.
This sort of processing is very useful when printing paragraphs of text,
and is enabled by:
fill on
For example, consider the following input with filling disabled:
In the last [numdays]

days there have been a total of [numdefects] defects
in the process. The mean
flow rate was [mrate] m3/hr.
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.
With filling enabled the script 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
The output from the previous example would be:
107
Chapter
Reports
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.
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
This sets the current pagestyle to be pagestyle 12 and defines a page

which uses this pagestyle to be forty lines long.
A pagestyle is simply a means of collecting all the information about
how a page is laid out together. It uses attributes to define certain
aspects of a page. The pagestyle attributes are; STARTLINE, ENDLINE,
HEADER, HEADLINE, FOOTER, FOOTLINE, LENGTH, LMARGIN and RMARGIN.
The STARTLINE, ENDLINE, HEADLINE and FOOTLINE must be given a
numerical value. The STARTLINE attribute defines at which line TSL
should start printing the pages text (that is, the output generated by the
PRINT, PRINTLN and ' commands) and the ENDLINE attribute defines the
last line on which text is printed. If a HEADER attribute has been
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.
The SETREPORT command is used to change the current report. For

example:
setreport 10
report default = 12
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.
Printing reports to a file or a printer

TSL supports up to 30 logical printers at any time. A logical printer can
either be a file, a printer or a pipe. The current printer is defined using
the SETPRINTER command and the details of the current printer are
defined using the PRINTER command, for example:
setprinter 10
printer output = file, filename = "/tmp/report1"
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
declare outto "to Screen"

dialog text(10) h "Royal House" allownull = false
dialog skip
dialog panel outto "Output" \
"to Screen" "to File" "to Printer" \
action = "Destination Changed"
dialog text(15) fname "File Name/Command" \
sensitive = outto <> "to Screen"'
menu 1 "Report"
# Procedure for printing the report to the
# current printer
defproc report_on_house( family )
@BReport on Royal House of [norm(family)]@B

from kings where upc(house)=upc(family) ;
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
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
that can be sent to the printer if it is chosen as the destination. This

removes the need for a potentially lengthy regeneration. However, the
user may change some of the values to report on before printing, so a
check must be made for this and the report regenerated if necessary.
The SETBUFFER and BUFFER commands enable you to define up to 30
logical buffers and switch output to the current buffer on and off. Use
the SETBUFFER command to define the current logical buffer. The
BUFFER command switches output to the current buffer on and off and
can be used to define its attributesthat is, the filename with which it
is associated and, optionally, whether TSL appends to the file rather
than overwriting on the first write. For example:
SETBUFFER 12
BUFFER filename = "/tmp/buff12"
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.

Like the previous example, the following script reports on royal families
by house. However, this example uses the BUFFER commands in
combination with %DLOGCHANGED so the report is only regenerated
when the house on which to report is changed.
# Turn the paging facilty off
more off
# Set a variable to indicate if a report has been
# generated
declare rep_to_prn FALSE
# Set a variable for the temporary buffer file
declare BFILE "/tmp/buffile1"

# Define the buffer to use
setbuffer 1
buffer filename = "[BFILE]" append = false
# open the kings database
query open kings ;
# Define the dialog box for the user query
dialog
dialog
dialog
dialog
layout buttoncolumns = 2 mode = 3

text(10) h "Royal House" allownull = false
button "To Screen" Action = "Screen"
button "To Printer" Action = "Printer"
# Define the menu structure

menu 1 "Report"
# Procedure for producing the report about the royal
# family given.
defproc report_on_house( family )
# Remove any buffer file that may exist
shell rm -rf [BFILE]
buffer on
'
'@BReport on Royal House of [norm(family)]@B
'
from kings where upc(house)=upc(family) ;
'Name
'
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
Printing reports: example
# Close the kings database after use

query close kings ;

# Printing to different files/printer devices
# using a report formats. (example17.tsl)
#
# Define the pagestyle used by reports.
setpagestyle 10
pagestyle \
length = 24,\
headline = 1,\
header = "Status of Kings"',\
footline = 23, \
footer = %pagenum::"Page %20d"',\
startline = 3, endline = 21, \
lmargin = 0, rmargin = 55
setreport 10
report default = 10
setprinter 10
printer output=file, filename="/tmp/[loc(sysuser())]"
setprinter 11
printer output = printer, command = "lp -dps"
# do_report() prints the report to the given printer
# number or to the screen.
defproc do_report( printon, printnum )
if printon
setprinter [printnum]
printer on
endif
report on
query display str(fullname,1,10) as vfullname,\
born, children
from kings ;
first
repeat
[vfullname] ([born]AD) had [children] children.
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"
to @file" action = "File"

to @printer" action = "Printer"
to @screen" action = "Screen"
action = "Exit"
query open kings ;

repeat
askmenu
switch %menuval
case "File"
call do_report( true, 10 )
case "Printer"
call do_report( true, 11 )
case "Screen"
call do_report( false, null )
endswitch
query close kings ;
In this example, the procedure do_report() shows how a typical

report might be sent to either a file or a printer. Doing the REPORT OFF
before the PRINTER OFF ensures that the footer of the last page of the
report is sent to the selected logical printer and not the screen.
When the printer is enabled (using the PRINTER ON command) and
reporting has not been enabled, the printer inherits the same page
length and margins as the main window. This is normally adequate for
most types of report and printer. However, if you wish to print a report
on 132-column paper you need to reset the margins using code such as:
if to_print
printer on
margin 2,130
length 60
endif
<Print the Report>
if to_print
printer off
margin 4,76
length 65
endif
119
Chapter
Graphics
7
Graphics
Presenting graphs is likely to be an integral part of most

TSL applications. TSL provides a range of commands
which provide access to the powerful graphics
capabilities of Kingfisher. Procedures can be executed
from TSL or graphs can be individually created and
formatted as required.
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:
Creating and sizing one or more display windows
Executing Kingfisher procedures
Creating, positioning and sizing individual graphs
Loading graph formats into graphs
Setting over 100 different attributes for any graph
Loading colourmaps into the display window
Executing queries and displaying the results in a graph
Printing the display window
Enabling a cursor in a graph
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:
A canvas can be explicitly created using the CANVAS ON command.
A canvas can be implicitly created by executing any graphics

command when no canvas exists. This causes TSL to create a
default canvas.
A canvas can be created by running Kingfisher from the shell in TSL

mode.
The canvas
Figure 18. A TSL application with canvas

In most cases, the first approach is recommended as it provides control
over the position, size and mode of the canvas. The CANVAS ON
command allows you to specify the pixel position and size of the
display window on the screen. The example below creates a canvas
positioned at 100,100 with a width of 500 pixels and a height of 400
pixels.
canvas on 100 100 500 400
If the position and size information is not provided, a canvas window is

created at the same position and with the same size as the normal
Kingfisher display window. Furthermore, any or all of the geometry
fields can be replaced by an asteriskthis represents the default value.
The example below creates a canvas at the default position but with a
size of 200 by 200 pixels.
canvas on * * 200 200
If there is no TQL Server running when the canvas is created, Kingfisher

waits for a response from the server before closing with an error
message. By default, Kingfisher closes after 120 seconds but you can
change this period using the environment variable KF_EXEC_TIMEOUT.
123
Chapter
Graphics
This specifies the time, in seconds, after which Kingfisher closes if it

receives no response from the server. For example:
KF_EXEC_TIMEOUT 15
specifies that Kingfisher will fail if it receives no response from the

server after 15 seconds.
When your TSL script finishes, the canvasses created by the TSL script
are normally left on the screen. You can continue to use the canvasses
and must use the window manager to remove them. If you want to
destroy a canvas from your TSL script, use the following command:
canvas off
If you want to delete all the canvasses created by your TSL script, use
the command:
canvas off all=TRUE
See Creating and managing multiple canvasses on page 146 for a

complete description of how multiple canvasses are created and
destroyed.
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
This is the recommended canvas type to use in a completed application

as it provides the end user with some useful capabilities (such as
zooming) but does not allow them to change your carefully designed
graphs.
Kingfisher Procedures
Finally, a canvas can be created as a raw windowwith no menu bar,

scroll bars or other decoration. The only decoration will be the usual
window manager borders. However, the window is inactiveno cursor,
zooming or other operations are provided. The following example
creates a canvas of this type:
canvas on nomenu
If a canvas has already been created by explicitly running Kingfisher

from the command line, the CANVAS ON command automatically adopts
that canvas. (If the SETCANVAS command is used, the situation may be
more complicatedsee Creating and managing multiple canvasses on
page 146 for more details). However, Kingfisher cannot honour either
the mode, position or size of the canvas requested in the command.
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
The KFPROC command is equivalent to the PROC command which users

of previous releases of TSL may be familiar with. The PROC command
may still be used but users may desire to use KFPROC to avoid possible
confusion between Kingfisher and TSL procedures.
Kingfisher procedures are executed in the current canvas. If you are
using only one canvas, the current canvas is this canvas. However, if
multiple canvasses are being used, the current canvas is defined using
the SETCANVAS command (see Creating and managing multiple
canvasses on page 146).
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
successfully. Other values indicate various error conditions as described

below:
Value
Description
The named procedure could not be found by the Kingfisher

server. This can happen if the procedure does not actually
exist or if it cannot be found in the set of procedures associated with the current database and user name, or on
KF_PROC_PATH. In particular, this error appears if you have
not opened the database associated with the procedure
before trying to execute it.
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)
#
#
#
#
Runs the procedure PLOT_CHILDREN on database KINGS

The procedure plots a line chart of
number of children vs birthdate for the monarchs
in the house specified by the variable ROYAL_HOUSE.
# Enable the canvas

canvas on
127
Chapter
Graphics
# We must open the database before running a procedure

#
query open kings ;
# Initialise variable from first row in the relation
#
query fetch first from kings ;
declare royal_house "[house]"
menu 1 "Procedures"
menu 1-1 "Run Procedure" action = "Run"
menu 2 "Options"
menu 2-1 "Procedure options.." action = "Options"
setdialog 1
declare no_prompt false
dialog toggle no_prompt "No prompt"
setdialog 2
dialog text(14) royal_house "Royal House"
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
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
Controlling hardcopy details

Kingfisher can produce graphical output in a range of formats
(PostScript, HP-GL, PCL) and to a range of different devices. It also
provides facilities for setting up margins and borders on printed output.
By default, the CANVAS PRINT command uses the same hardcopy
settings as last set in Kingfisher, however you can override the current
canvass hardcopy settings by using the CANVAS HARDCOPY command.
The example below sets the output format to PostScript and sets the
page width to 8 inches.
canvas hardcopy set graphformat=1 pagewidth=8
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
printer)each property corresponds to a dialog item on the Kingfisher

hardcopy dialog. The hardcopy properties, along with all other defined
Kingfisher properties, are documented in Chapter 8 of the Kingfisher
Reference manual.
Loading hardcopy configuration

Kingfisher also provides the capability to save an entire hardcopy
configuration in a configuration file. Using this facility you can save
configurations for different printers or paper sizes and then load the
entire configuration in one go.
The CANVAS CONFIG LOAD command is used to load a configuration
from TSL for the current canvas, for example:
canvas config load print_room1
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
The named configuration file could not be found by the

Kingfisher server.
10
The configuration file was not in the correct format.
Other canvas commands

As well as CANVAS PRINT, a number of other commands are available
that operate on an entire canvas.
The CANVAS CLEAR command clears the current canvas. All graphs
on the canvas are destroyed.
The CANVAS REFRESH command refreshes the current canvas. All

the graphs are redrawn in the order they were created.
The CANVAS RESIZE command allows you to resize the current

canvas after it has been created from your TSL script.
Raising and hiding the canvas window
The CANVAS SNAPSHOT command generates a snapshot of the

current canvas window. A new window is created which contains a
copy of the contents of the canvas window. This can then be used
for reference or comparison with other results. These snapshot
windows must be explicitly destroyed using the window manager.
Raising and hiding the canvas window

On most workspaces it works best to have the TSL window in the top
left corner and the canvas window in the bottom right. These windows
often overlap and the contents of the canvas window are sometimes
obscured. In this case, it can be useful to raise the canvas window after
a graph is drawn in itthis saves the user having to do it with the
window manager and it helps to bring the new graphs to the users
attention. The command below raises the canvas window:
canvas raise
If the window has been iconified or unmapped, it is automatically

deiconified and brought to the top of the stack of windows on the
display. This capability can be performed automatically by executing
the following command:
canvas mode autoraise=on
Now whenever a procedure is executed or a graph is drawn in the

current canvas, the current canvas is automatically raised to show the
new data to the user.
In some circumstances it may be appropriate to completely remove the
canvas window from the screen. Although you could simply execute a
CANVAS OFF command, the overhead in restarting Kingfisher the next
time you want to produce a graph is substantial. Instead execute the
following command:
canvas hide
This causes the current canvas window to be unmappedit is not

visible but still exists, and is made visible again when it is raised. You
can continue to draw to the canvas and the results will become visible
when the canvas is remapped.
To start a display window hidden you must use the HIDE attribute to
CANVAS ON.
canvas on hide = true
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 ;
This command creates a graph in the current canvas (assuming one

does not already exist), position it to fit the entire canvas (less some
small border) and then execute the query and plot the resulting data.
The graph format will be a default line chart with no titles or other
annotation. The GRAPH DRAW command is followed by any query that
can return datalike the QUERY command it may span multiple lines
and so must be terminated by a semi-colon.
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
where test#=23 ;
Positioning and sizing a graph
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.
Positioning and sizing a graph

By default, a graph is sized to fit the entire canvasbut allowing a
small margin. You can explicitly position a graph by using the GRAPH
POSITION command. This command allows you to specify the position
of the top left corner of the graph and its width and height. The
geometry is specified as a percentage of the canvasthat is, 0,0 is the
top left of the canvas and 100,100 is the bottom right. Consider the
example below:
graph position 50 0 50 100
where test#=23 ;
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.
Implicit creation and destruction

Consider the sequence of commands below:
where test#=23 ;
graph format load xyscat
where test#=26 ;
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:
Optionally position and size the graph
133
Chapter
Graphics
Load the appropriate graph format
Execute the required query
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.
Changing the format of an existing graph

By default, it is not possible to change the format of a graph once data
has been plotted in it. This is because the subsequent GRAPH FORMAT
command destroys the existing graph and creates a new one as just
described. If for some reason you need to do this in your application,
you can switch on the canvas graph editing mode, as follows:
canvas mode edit=on
where test#=23 ;
graph format load xyscat
canvas mode edit=off
This sequence of commands draws a graph as a line chart and

immediately changes its format to a scatter chart. The graph
automatically redraws itself when its format changes.
Accessing graph formats

Graph formats are created in Kingfisher by using the Save Format As
command from the Graph menu. A graph format may be specified as
shared, in which case it is available to all users, or private in which case
it is visible only to the user who created it. To access a private graph
format you must be running TSL with the same TQL user name as when
the format was created.
Once you have completed your application you may wish to collect
together all the formats you use to make it easier to distribute or
manage your application. In this case you should put all the format files
in a directory and set the environment variable KF_FORMAT_PATH
accordingly. This variable is set to a colon separated list of directories.
Kingfisher looks for formats in all the directories on this path before
searching the usual private and shared directories.
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
The query could not be executed at present as Kingfisher

was executing on behalf of another TSL application.
The named format could not be found by the Kingfisher

server. This can happen if the format does not actually
exist or if it cannot be found in the set of formats associated with the current user name, or on KF_FORMAT_PATH.
The graph format file was not in the correct format.
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.
Query Errors in GRAPH DRAW

The query that you pass to the GRAPH DRAW command is executed on
the server by Kingfisher. If any errors occur the error codes are passed
back to TSL and the special variables %QOK, %QERR, %DERR, %FERR,
%QMSG, %DMSG and %FMSG are set in the same way as after a QUERY
command. Similarly, you can use the ABORT command to control
whether the script terminates on these errors.
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
# Using the GRAPH command (example19.tsl)

# Plots a scatter chart of number of children
# or a bar chart of the number of spouses.
#
# Enable the canvas
#
canvas on noedit
canvas mode autoraise=on
query open kings ;
menu 1
menu
menu
menu
"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
endswitch
query close ;
canvas off
More graphics features

So far you have seen how you can create graphs in TSL by loading
graph formats and executing queries in the graph. This section
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
format load xyline

draw print a ;
draw print mode(a) ;
draw print median(a) ;
This example assumes that we have an array in the variable A. First we

plot the arraynote how we use the TQL PRINT command to retrieve
the value of the variable; then we overlay the plot with the mode and
median values. Assuming that we are plotting a line chart, the mode
and median will be plotted as horizontal lines across the graph.
Notice that the GRAPH DRAW command does not cause the current graph
to be destroyed and a new graph createdany number of GRAPH DRAW
commands can be executed to overlay data on a 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
In most applications you will probably not need to set individual

properties of a graph and are generally well advised to use graph
formats wherever possible. Some reasons why you may want to set
properties are:
To avoid having to create a very large number of graph formats.

Sometimes you may want to create graphs that differ only slightly
perhaps in the number of secondary Y axes, or in the automatic
overlays that are available. In this case, you would define a base
graph format and change the properties as needed.
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.
To build some graphics formatting capabilities into your own

application. You may wish to allow your end users to change some
aspects of the graph formats by editing dialogs you have created in
TSL.
Properties are set using the GRAPH PROPERTY command:

graph property set graphtype=1
The SET keyword is followed by a list of property/value pairs. In this

example, the graph is set to a scatter chart. The Kingfisher Reference
describes the valid values for each property.
Note that the GRAPH PROPERTY command, like the GRAPH FORMAT
command, implicitly destroys the current graph and creates a new one.
So if you are changing the properties of a graph after you have drawn
it, you must enable the canvas graph edit mode.
If the property takes multiple values, you must qualify the property
name to indicate which value you are setting. For example:
graph property set colour/0=2 colour/1=3
This command sets the colour of the primary dataset (qualified by 0) to

the third colour on the colour palette, and the colour of the first
secondary dataset (qualified by 1) to the fourth colour on the colour
palette. (Qualifiers and most property values are 0 based.)
You can also use the GRAPH PROPERTY command to get the current
values of any properties of a graph. This is useful if you want to preset
a dialog with the current value of particular property before allowing
the user to change it. For example:
Example
graph property get colour/0=pcolour
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 2 "Edit"
menu 2-1 "Legend..." action = "Legend"
repeat
askmenu
switch %menuval
case "Graph"
graph format load legend
from kings
139
Chapter
Graphics
case "Legend"
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
query close ;
canvas off
The graph cursor

Unless you are running in NOMENU mode, the menu system in the
display window always contains the cursor, measure and zoom
commands that you may have used in Kingfisher. You can use these as
normal on any graphs that you create from TSL. In addition TSL has a
command that allows you to read off a point from a graph and have the
data stored in variables for further processing in the TSL script.
The GRAPH CURSOR command enables the graphics cursor in the canvas.
The cursor becomes a small crosshair when it is over the canvas. When
the user clicks the left mouse button the X, Y and Z values are recorded
and are stored in the TQL variables %XVAL, %YVAL and %ZVAL.
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 2 "Cursor"
menu 2-1 "Select range" action = "Range"
repeat
askmenu
141
Chapter
Graphics
switch %menuval
case "Graph"
from kings
case "Range"
info "Select left edge of range to zoom on"
graph cursor
set minx %xval
info "Select right edge of range to zoom on"
graph cursor
set maxx %xval
from kings
where kingno>=minx and kingno<=maxx
endif
endif
info
endswitch
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
The CANVAS COLOURMAP LOAD command is used to load a colourmap

from TSL, for example:
canvas colourmap load mymap
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
The named colourmap could not be found by the Kingfisher server.
The colourmap file was not in the correct format.
Creating multiple graphs

In many applications you only need to have a single graph in the
canvas at any one time. That graph may, of course, show many datasets
as overlays or perhaps on secondary Y axes but as far as TSL is
concerned it is only a single graph. However, often you may wish to
produce a display that contains more than one graphperhaps
showing the same data in different views or perhaps one graph
showing complementary informationfor example, phase and
magnitude. In this case, you need to understand more about how
graphs are created and managed by TSL.
TSL has a notion of the current graph. All GRAPH commands apply to this
graphthat is, they position it or change its layout and format. When a
GRAPH DRAW command is executed it adds data to the graph and the
graph actually becomes visible on the canvas. Subsequently any GRAPH
commands, other than GRAPH DRAW, still refer to this graph and, by
default, cause the graph to be destroyed and a new one created.
In order to create multiple graphs a way is needed to make GRAPH
commands apply to a new graphthat is, to change the current graph
number. The SETGRAPH command does just that and supports up to 50
graphs on the canvas. The command is followed by the graph number
from 1 to 50. For example:
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
where test#=23 ;
setgraph 2
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.
When a graph is destroyed either by the CANVAS CLEAR command,

or implicitly, by executing a GRAPH command on a graph with data
when not in canvas edit mode, all the graphs on the canvas are
destroyed. This is actually not normally a problem as it is unusual
to make use of implicit destruction when handling multiple graphs.
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
# Enable the canvas

#
canvas on noedit
canvas mode edit=on autoraise=on
query open kings ;
declare numgraphs 0
declare h "Anjou"
menu 1 "Plot"
menu 1-1 "Royal House" action = "House"
repeat
askmenu
switch %menuval
case "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
145
Chapter
Graphics
from kings
where upc(house)=upc(h) ;
endif
endswitch
query close ;
canvas off
Creating and managing multiple canvasses

There are occasions where even being able to create and control
multiple graphs does not satisfy the needs of an application. An
example might be an application that requires several large graphs
displayed simultaneously without taking up the entire display. In this
case the solution is to use multiple canvasses.
The use of multiple canvasses has several advantages:
A number of graphs can be displayed simultaneously whilst

keeping the size of the graphs large enough to study closely.
Screen space can be limited and controlled using window stacking

and iconisation as for other windows.
Graphs that have no direct relation to each other can be displayed

in separate windows.
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
The number of graphs in the canvas.
%GRFOCUSSED
The graph with the data focus.
%GRSELECTED
The graph properties apply to.
In an application where you want to control multiple windows all with

multiple graphs in them, it is important to use these variables to avoid
graphs being destroyed implicitly when moving between canvasses. In
this case, the correct approach is to set canvas editing on with:
CANVAS MODE EDIT=ON
and set the current graph identifier after setting the canvas identifier, for
example:
SETCANVAS 2
SETGRAPH [%GRFOCUSSED]
To delete all canvasses controlled by the application use the ALL

modifier to CANVAS OFF.
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
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"
147
Chapter
Graphics
repeat
askmenu
switch %menuval
case "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
from kings
where upc(house)=upc(h) ;
endif
case "CreateCanvas"
set canvasses canvasses + 1
setcanvas [canvasses]
canvas on nomenu
set numgraphs %num_graphs
set samec FALSE
case "ChangeCanvas"
if canvasses <> 1
Approaches to developing graphics in TSL
dialog slider acanvas "Draw to canvas number:" 1

[canvasses]
askdialog "Change Canvas"
if %dialogval
setcanvas [acanvas]
set numgraphs %num_graphs
setgraph [%grfocussed]
endif
else
info "Only one canvas exists"
endif
endswitch
query close ;
canvas off all = TRUE
Approaches to developing graphics in TSL

TSL is designed to encourage fast prototyping of applications. This
section discusses techniques for quickly incorporating graphics into a
TSL application.
The first decision that must be made is whether you should attempt to
develop your graphs by using Kingfisher procedures from TSL.
Using Kingfisher procedures

If you have used procedures in Kingfisher you will be aware that a
procedure may contain a significant number of queries of different
typessome of these may create variables, others may manipulate
temporary tables whilst others are responsible for retrieving the data
which appears in the display window. A typical TSL application may
also contain similar queries for creating variables and temporary tables,
perhaps as a prelude to producing a report or a graph. Clearly some
queries could equally well be performed as part of the procedure or as
part of the TSL application so you have to determine the best balance
between the two. As a general rule, the aim should be to minimise the
number of queries performed as part of the procedure so that the
procedure is responsible only for those queries which are directly
concerned with producing the graph. This approach confers several
practical advantages:
TSL scripts are designed to be human-readable (and editable).

Procedures, although stored in a human-readable format, should
149
Chapter
Graphics
not normally be edited by hand. Thus queries in the TSL script may
more easily be modified than those in procedures.
TSL allows the results of each query to be tested individually and

for queries to be executed conditionally based upon the results of
earlier queries. Procedures have no control flow structure and abort
on the first error.
Queries in TSL may be varied at run-time by substitution of text

items. Queries within a procedure are static.
Further, it is recommended that, if a procedure uses variables, you

should set these variables from TSL and execute the procedure in
NOPROMPT mode rather than rely on the prompting mechanism of
Kingfisher. This allows you to design custom dialogs for input of these
values. So, for example, multiple values may be set in a single dialog,
you can use more appropriate dialog item types than simple text fields
and you can provide context sensitive help to indicate what sort of
input is expected.
Instead of producing graphical output, Kingfisher procedures may also
be designed to produce output in tabular form. It is not recommended
that this feature is used from TSL. Instead you should use the report
writing features of TSL to send the output to the TSL work window as
described elsewhere in this manual.
So, in conclusion, use procedures if:
The amount of query processing is smallfor example, just directly

retrieving data to plot
There is no need to vary or modify the procedure significantly

other than is supported through Kingfisher variables
You do not need to change the format or position of graphs

dynamically
Using GRAPH commands

If your requirements are not well met by procedures, you need to use
the GRAPH commands in TSL and develop a set of graph formats in
Kingfisher. This certainly provides the most flexibility and control over
the graphics capabilities of the system.
The best approach to developing a particular graph is to concentrate
first on the TSL side of the process, and in particular on the queries that
you must execute to retrieve the appropriate data. It may be that you
Using GRAPH commands
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:
If you need to perform significant statistical analysis on the data, it

may be worthwhile collecting the data into an array (using the TQL
COLLECT command) and applying functions to the array directly.
Consider what sort of additional annotation you may want on the

graphfor example, the results of some analysis, or some statistic.
Again retrieving the data into an array and setting variables based
on functions of the array may be the best way of achieving this
annotation.
Consider whether you should check for your queries returning no

data and issue an error message.
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.
When you have completed the application, start the canvas in

NOEDIT mode so that your users cannot change your graph format.
151
Chapter
8
This chapter describes a number of miscellaneous

features of TSL that you may need to use when
constructing applications. In particular, the commands
available for loading and unloading data into database
tables and query error handling are described here.
In addition, the topics of X Resources and commandline options are covered here.
153
Chapter
Loading and unloading tables

An important part of many applications is the capability of loading data
into the database tables from external files, instruments or other
systems. Sometimes it is most appropriate to write a program in C
which loads the database using the appropriate Metrica programmatic
interface; sometimes the data can be loaded once and for all using the
Transfer Tool in Kingfisher. TSL also provides commands to load and
unload data into and from tables.
The TRANSFER command provides exactly the same functionality as the
Kingfisher Transfer Tool. It is suitable for the following types of
operation:
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
Unloading a database table in one of the formats described above
Because the command exactly emulates the equivalent functions in

Kingfisher, you should refer to the Kingfisher Reference manual for
details of the exact functionality of the data transfer mechanism.
The TRANSFER command uses the same concept of properties as you
encountered with the CANVAS and GRAPH commands. The details of the
transfer, such as the basic format, the delimiter, and so on, are set by
setting properties using the TRANSFER PROPERTY command:
transfer property set delimiter=";"
This command sets the transfer delimiter to a semi-colon. All the

transfer properties are described in Chapter 8 of the Kingfisher
Reference manual.
The TRANSFER LOAD command is used to load data into a table. The
command specifies the table and the name of the file or pipe from
which to read datanote that the file or pipe are not specified in
quotes.
transfer load spectra /tmp/specta_file
Default property values
transfer load spectra cat /tmp/spectrafile | myfilter
The TRANSFER UNLOAD command is used to unload data from a table

into a file or pipe.
After a TRANSFER LOAD or TRANSFER UNLOAD command the number of
rows successfully written is stored in the special variable %XFROWS. The
number of rows discarded, either because they contained null values in
columns that do not allow null or because there were duplicates of
rows in the table, is stored in the variable %XFDISCARD. For example:
transfer property set delimiter=";"
transfer load spectra /tmp/data
info "[%xfrows] written; [%xfdiscard] discarded"
Default property values

When TSL starts it sets the transfer properties to the following default
values:
media
Transfer to/from file.
format
Delimited ASCII data.
delimiter
" "
Space as field delimiter.
terminator 0
Linefeed as row terminator.
overwrite
TQL %OVERWRITE mode disabled.
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
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
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
Making TSL timeout

The TIMEOUT command is used to define the period of time that a TSL
application waits for a user to initiate an action when an ASKMENU or
ASKDIALOG command is being performed. If either of these commands
timeout, TSL assumes that the user is no longer using the TSL
application and TSL quits.
If several users want to use the application at the same time but there
are only a limited number of TQL licences, it is advisable to make TSL
quit if the user is not actively using the TSL application thus freeing a
TQL licence.
The command:
TIMEOUT MENU 10
sets the timeout for the ASKMENU command to be ten seconds and the
command:
TIMEOUT DIALOG 10
sets the timeout for the ASKDIALOG command to be ten seconds. If

neither MENU or DIALOG are specified, MENU is assumed. The timeout can
More
be disabled by executing the command without specifying the duration

of the timeout. For example:
TIMEOUT DIALOG
cancels the timeout on the ASKDIALOG command.
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:
By pressing the Spacebar, in which case another page of output can

appear before the next --More-- prompt.
By pressing the Return key, in which case only a single line of

output appears, followed immediately by another --More-- prompt.
By pressing Q or q in which case an abort signal is generated

(described below).
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
repeat
' [exp#] [volts]
next
forall
159
Chapter
Since the prompt is enabled by the MORE command, a --More--

prompt will be displayed when a screen full of output is generated. If
the user presses Q or q, a signal will occur which will be trapped by
the repeat loop. This trap causes the loop to be broken and processing
to continue after the FORALL statementthat is, it quits the loop.
This trapping is almost always the behaviour you will want in handling
these events. However, you can disable trapping using the NOTRAP
keyword as in the example below:
more on
repeat notrap
' [exp#] [volts]
next
forall
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.
Cut and Paste

Text in the TSL work window may be pasted to other windows in the
same TSL application or to other applications sharing your workstation
display.
Before text can be pasted to another application it must be selected.
Text is selected by pressing and dragging the left mouse button (mouse
button 1). As the text is selected it is highlighted and shown in reverse
video. As the mouse is moved the selected area expands or shrinks
accordingly. To end the selection, release the mouse button. The
selected text remains highlighted.
The TSL window also supports double clicking to select a word and
triple clicking to select a line.
In X-windows, the selected text may now be pasted directly to another
window by clicking the Paste button (button 2) in that window.
An existing selection may be adjusted (enlarged or shrunk) by pressing
then dragging the Extend mouse action. The Extend action corresponds
to pressing the left mouse button whilst holding down the Shift key.
X Resources and the Applications defaults file
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.
X Resources and the Applications defaults file

TSL is an X application written using the OSF/Motif toolkit. This is built
on the X programming interface and uses the concept of resources to
control various aspects of appearance and behaviour. In addition,
because the Motif toolkit uses the X Intrinsics, a large amount of
configurability is available for TSL widgets.
The application defaults file Tsl is placed in the directory
$TQL_CLIENT_DIR/appdefs. The class name for TSL is Tsl. This file
contains application resource values for TSL and some Motif widget
resource settings to obtain a basic appearance. The application
resources are described completely in the reference section. The more
important ones are described below.
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
The font to use for labels in dialogs (normally

set to a proportional font such as New Century
Schoolbook or Helvetica).
Tsl.dataFont
The font to use for data items in dialogs such as

text fields and scrolled lists (normally set to a
fixed font such as Courier).
Tsl.buttonFont
The font to use for all push-button in dialogs i.e

the OK and Cancel buttons.
161
Chapter
Font type
Usage
Tsl.menuFont
The font to use for all menu entries in the pulldown menu system.
Tsl.toolboxFont
The font to use for all toolbox labels.
Tsl.normalFont
The font to use in the main TSL window for normal, non-enhanced text.
Tsl.boldFont
The font to use in the main TSL window for bold

text enabled via the @B symbol in TSL.
Tsl.useVueFonts
If TRUE, HP VUE system and user fonts will be

used by the application as appropriate.
TSL main window

TSL also uses a number of resources to control the size of the TSL main
window:
Resource
Description
Tsl.rows
The number of rows that fit in the terminal window i.e not including the menu bar.
Tsl.columns
The number of columns in the terminal window.
Tsl.bufrows
The number of lines in the scroll buffer. This

determines how much of the output is saved in
memory and can be scrolled back through.
Print spooler
Print spooler
The definition of the print spooler is defined using an application
resource:
Resource
Description
Tsl.printCommand The operating system command used to spool

output to the system printer. By default, TSL runs
the script tbprint, supplied with your TSL system. This script runs a default spooling command suitable for your operating system. By
default, output is printed using the portrait page
orientation. To change the orientation to landscape, use the -landscape option. For example:
tbprint -landscape
Dialog layout attributes

The default values for many of the DIALOG LAYOUT attributes are
specified in the resource file.
Attribute
Description
Tsl.alignRows
Defines the default value for the

ALIGNROWS attribute. If this resource is
not defined, the default value for
ALIGNROWS is set to TRUE.
Tsl.alignColumns
Defines the default value for the

ALIGNCOLUMNS attribute. If this
resource is not defined, the default
value for ALIGNCOLUMNS is set to TRUE.
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
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
Defines the default value for the MODE

attribute. If this resource is not defined,
the default value for MODE is set to 0.
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
Defines the default value for the TOOLGAP

attribute. If this resource is not defined, the
default value for TOOLGAP is set to 10.
Tsl.toolboxGroupGap Defines the default value for the GROUPGAP

default value for GROUPGAP is set to 10.
Tsl.toolboxFrame
Defines the default value for the FRAME

default value for FRAME is set to TRUE.
Tsl.toolboxGravity
Defines the default value for the GRAVITY

default value for GRAVITY is set to WEST.
Menus and dialogs
Attribute
Description
Tsl.toolboxRows
Defines the default value for the ROWCOLS

attribute if the GRAVITY of the toolbox is set
to either NORTH or SOUTH. If this resource is
not defined, the default value for ROWCOLS
when the toolboxes GRAVITY attribute is
defined as either NORTH or SOUTH is 1.
Tsl.toolboxColumns
Defines the default value for the ROWCOLS

attribute if the GRAVITY of the toolbox is set
to either EAST or WEST. If this resource is not
defined, the default value for ROWCOLS when
the toolboxes GRAVITY attribute is defined as
either EAST or WEST is 2.
Menus and dialogs

The maximum number of dialogs and menu items and the maximum
number of submenus within a menu may be defined in the resource
file.
Attribute
Description
Tsl.maxDialogs
Defines the maximum number of dialogs that

can be defined. The default value is 200.
Tsl.maxMenuItems
Defines the maximum number of items that

can be defined in a menu pane. The default
value is 20.
Tsl.maxMenuNesting
Defines the maximum number of levels to

which a menu may be nested. The default
value is 5.
165
Chapter
The Select Date dialog

The following environment variables enable you to specify the local
language used for displaying the months and days in the Select Date
dialog.
Attribute
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>
Substitute month with the month in your

chosen language, for example:
Tsl*monday: <day>
Tsl*tuesday: <day>
Tsl*wednesday: <day>
Tsl*thursday: <day>
Tsl*friday: <day>
Tsl*saturday: <day>
Tsl*sunday: <day>
Substitute day with the day in your chosen

language, for example:
Tsl*january: <janvier>
displays the French translation of January.
Tsl*monday: <lundi>
displays the French translation of Monday.
Setting an application resource

There are a number of methods for changing specific resources for TSL:
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 add resource lines to your own .Xdefaults file or

.Xresources file. This allows you to specify changes for all
applications that you run.
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
Another useful technique relates to creating resource files for specific

applications that you have created using TSL.
When you create a complete application you may change a number of
resources specifically to suit the applicationfor example, default
layouts, screen size or colours. Rather than risking other people or
yourself changing these settings in the future, create a resource file
specifically for your application.
Suppose you wish your application to be called ictest. Create a
resource file with lines such as:
ictest.rows:40
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
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
[-printerModel <model>] [-rawPrintCommand <command>]

[-dateInputFormat <dateformat>]
[-dateOutputFormat <dateformat>]
[-timeOutputFormat <timeformat>]
[-complexOutputFormat <complexformat>]
<script-file> [<args>]
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
This argument is followed by an integer number

which specifies the size of the TQL query buffer in
bytes. The results of any query in a TSL script must
fit in a single query buffer. If your application generates very long reports or deals with large arrays,
you may need to increase the buffer size.
-debug
These argument causes the TSL interpreter to print

to the standard error every query that it is executing. The audit trail includes user queries and queries generated to set and query TQL variables.
-host
This argument is followed by the network hostname

of the system on which to run the TQL Serverthat
is, the system on which the database physically
resides. If this argument is missing, the hostname is
obtained from the environment variable QYHOST. If
this variable is not defined, the TQL Server is started
on the local machine.
-nomap
This argument stops TSL from mapping the main

window. Using this mode you can create dialogs
and display them without having an underlying
menu system. This can be useful when incorporating TSL in other applications that already have a primary user interface.
-nowindow
This argument stops TSL creating a user interface.

The program does not make a connection with the
X server and output goes directly to the standard
output. When TSL is running in this mode, the
%NOWINDOW system variable is set to TRUE. In all
other modes, the variable is FALSE. This mode is
useful when running TSL to generate batch reports
or performing database administration tasks.
-old
This argument enables compatibility mode with a

previous incarnation of TSL known as the Document Processor.
-outfile
This argument is followed by a filename. Specifying

this argument defines the specified file as the logical
printer for the TSL applicationthat is, any printed
output is sent to this file.
-printer
This argument specifies that the logical printer is the

configured system printerthat is, any printed output is sent to the printer.
-raw
This argument specifies that the logical printer is a

graphics printer i.e is in raw mode. This causes TSL
to generate linefeed characters internally and to use
the spooling command specified as the raw printer
command in the application resources. This is only
used on HP or SUN systems and is ignored by other
systems.
-server
as for -host
-term
The argument defines the terminal that should be

used when executing SHELL commandsfor example,
- term xterm
-user
This argument is followed by the username in the

database or database that the application will
access. If this argument is missing, the username is
obtained from the environment variable QYUSER. If
this variable is not defined, the username defaults to
GUEST.
169
Chapter
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
This argument specifies the format that

TSL will use to display complex numbers. This corresponds to the X
resource Tsl.complexOutputFormat.
For example:
-complexOutputFormat "%x+j%Y"
-dateInputFormat

TSL will use to read in dates. This corresponds to the X resource Tsl.dateInputFormat. For example:
-dateInputFormat "%d%m%y"
-dateOutputFormat

TSL will use to display dates. This corresponds to the X resource Tsl.dateOutputFormat. For example:
-dateOutputFormat "%d/%m/%y"
-logFile
This argument is followed by a

filename. Specifying this argument
defines the TSL log file which defaults
to $HOME/tsl.log. This corresponds to
the X resource Tsl.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
-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
This argument specifies the command

used to spool printer output for a
graphics printer. This is only used on
HP and SUN systems and is ignored on
other systems. This corresponds to the
X resource Tsl.rawPrintCommand.
-timeOutputFormat

TSL will use to display times. This corresponds to the X resource Tsl.timeOutputFormat. For example:
-timeOutputFormat"%H:%M:%S"
These arguments are followed on the command line by a single

filename which is the name of the script file to execute. If the filename
contains a / character, it is assumed to be the full pathname of the
script file. If not, TSL first searches in directories specified in the path
environment variable TB_TSL_SPEC_PATH. If this variable is not defined,
TSL uses the variable TB_SPEC_PATH. Finally, if this variable is not
defined, the file is assumed to be in the current working directory.
So, for example, to make TSL search in directories
/users/ssw/scripts and /usr/local/scripts you would enter
commands such as:
TB_TSL_SPEC_PATH=/users/ssw/scripts:/usr/local/scripts
export TB_TSL_SPEC_PATH
or:
setenv TB_TSL_SPEC_PATH \
/users/ssw/scripts:/usr/local/scripts
The script file may optionally be followed by a list of parameters to the

script. Each argument is associated with the symbols %0, %1 and so on
in the script using the DEFINE macro definition command in TQL.
171
Chapter
For example, if a parameter is passed using the following command

line:
tsl script.tsl 24
then it could be assigned to a TQL variable using a line such as:

declare parm %0
Notice that if you wish to interpret a parameter as a string, you have to

enclose the %n formal parameter in quotes.
Chapter
TSL Style Guide

9
TSL Style Guide
This chapter consists of a set of rules, notes and

suggestions that aim to describe a suitable style for the
user interfaces of TSL applications.
The purpose of this style guide is to try to make your
application easier to use.
173
Chapter
TSL Style Guide
General principles
When designing an interface for a TSL application the most important
points to be aware of are:
Your application should be consistent with existing Motif and TSL

applications
Your application should be robust. In other words your application

should be able to defend itself against users accidentally deleting or
corrupting your data.
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
Icons must be simple and their action should be easily

recognisable.
If you want to internationalise your application, you must not use

text in your icons as this will have to be translated. Similarly, ensure
that the picture used is recognised internationally.
Menus
Remember that menus specify actions so use verbs or verbal

phrases in menu labels if possible. For example, the label Plot is
better than Graphics.
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.
Always put an ellipsis after labels that cause a dialog to open.
Menu items which are not currently available should be made

insensitive using the menu items SENSITIVE attribute.
175
Chapter
TSL Style Guide
Define mnemonics for all menu entries if possible. You may prefer
to use the mouse but your users may not!
Define accelerators for the most important menu entriesthat is,

the ones that are used the most.
Try to keep the number of entries in a pane to less than 12.
Avoid putting frequently used actions in cascading menu panes.

Try to organise the menu system so that menus do not cascade
more than two levels.
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 the menu system so that the most important or most

frequently used actions are on the left. Try to make sure that the
top-level menu labels are significantly different and clearly suggest
what lies in the menu panes below.
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.
Toolboxes and tools
Actions which occur infrequently should not be put in the toolbox.
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.
Tools that are not currently available should be made insensitive

using the tools SENSITIVE attribute.
Confirmation dialogs
Always use confirmation dialogs to confirm any action that might

cause the loss of data or any other dangerous actions.
Error dialogs
The confirmation message must clearly describe the consequences

of confirming the action. A message such as Confirm? is likely to
receive a cursory click, whereas Do you want to delete ALL the
data? may cause some pause for thought.
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.
Do not use confirmation dialogs for simply asking questions of the

userfor example, Plot to screen?. When the user sees a
confirmation dialog, it should be associated with a possibly
dangerous situation.
Avoid using multiple confirmations of the Are you really sure?

variety. The user may start to expect this behaviour and will be
disappointed when, one day, his request to destroy the database
was accepted on the first click.
Error dialogs
Decide what events constitute errors in your application. Use this

rule consistently throughout the application. For example, is not
having data to plot on a graph an error, or not.
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.
In a large application consider using error codes in messages and

cross reference them with written documentation.
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.
Use progress dialogs to show work in progress. If the action is

lengthy and can be split into parts that are recognisable to the user,
use progress messages to show that the action is progressing.
177
Chapter
TSL Style Guide
Be careful not to use progress dialogs for short actions as there is a

danger that displaying the dialog will take more time than the
action.
Information dialogs
Use an information message to convey facts to the user.
You may use information dialogs to show work in progress where

the user is not offered the opportunity to stop the action.
File selection dialog
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.
If possible set a suitable pattern in the dialog so that unsuitable files

are not displayed in the dialog.
Selection dialog
Use the selection dialog when a single identifying item is to be

entered by the user. The dialog allows for selection from a list or for
text entry.
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.
Consider using the workspace to display data to be cut and pasted

into dialogs. Scrolled lists become difficult to use with large
amounts of data, and the main window may be an acceptable
alternative.
Never use the workspace to display confirmation messages or

serious errors.
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
Use bold and underlining to emphasise titles or important data.

Overuse of highlighting can become irritating.
Dialogs
Use dialogs for changing properties of objects or attributes of

actions. Do not use them to specify actions.
Try to minimise the amount of interaction needed with your

application. For example, if there is an action such as Plot Trend
Chart... which displays a dialog to set the chart parameters, and the
user seldom changes the parameters, split the actions to Setup
Trend Chart and Plot Trend Chart.
Always perform the action or changes when the OK button is

pressed. Always make sure that nothing happens when Cancel is
pressed.
Use sensible presets for dialog items and, if appropriate, leave

previous values set in the dialog so that the user can just make
changes rather than re-input values.
Dialog items which are currently inappropriate should be made

insensitive using the dialog items SENSITIVE attribute.
Consider creating context sensitive help files for each dialog in your
application.
If the user is likely to want to repeat the operation controlled by the

dialog again almost immediatelyfor example, if the dialog allows
one of many parameters to be plottedset the control buttons to
allow a non-dismissing mode, such as the Apply button.
Remember that users, especially those who prefer to use the

keyboard, may dismiss dialogs using the window manager and its
supported accelerators. In this case you must process the Cancel
button even if it is not defined in the dialog.
Use application defined buttons to specify a set of actions that can

be taken from this dialog. A good example is a data entry
application.
Do not use application defined buttons in place of the normal

control buttons. If the dialog simply allows the user to set and edit
a number of controls, use the standard buttons.
179
Chapter
TSL Style Guide
If you use application defined buttons, consider carefully what is

the meaning of the standard control buttons. Consider using just the
Close button (mode = 3)if no sensible interpretation can be made.
The iconic buttons in a dialog should all be the same size.
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.
If the contents of a text field or multiline text field cannot be

changed, the field should be made readonly using the dialog items
READONLY attribute.
If a value is expected in a text field or multiline text field, the dialog

items ALLOWNULL attribute should be set.
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.
Use sliders for numeric input of data that is constrained to be in a

small range.
Use sliders if they mimic some real front panel or instrumentation

that the user is familiar withfor example, filter sliders.
Avoid using sliders if the range is large or the user needs to be

accurate in the selection of a value. If the range is large, the slider is
too sensitive.
If you have a large range, increase the size of the slider to reduce
its sensitivity.
Use toggle buttons for Yes/No, Allow/Disallow, On/Off type data.
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, option menus and panels in preference to all

other dialog items whenever the input data is constrained to be in a
small set. These items are the easiest for users as they display the
choices available and only require one mouse click to interact with.
If you can enumerate sets of choices to use in these items do so
even if it means some additional operations are required in the
database.
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 you know the maximum width of the listfor example, if the

values in the list come from a table of strings that have a
maximum field lengthset the lists MINWIDTH attribute to the
maximum width of the list. To avoid resizing as a result of a
vertical scroll bar being created or deleted you should also
consider setting the lists SCROLLMODE attribute to 1.
If the maximum width is not known or the maximum width is

particularly large, set the lists MAXWIDTH to a sensible maximum
value and set the SCROLLMODE attribute to 2.
See Option, List and Panel on page 57 for a complete description of

the MINWIDTH, MAXWIDTH and SCROLLMODE list attributes.
If the set of values has obviously come from the database, use a
scrolled list.
Use option menus for 2 to 10 choices.
If the choices are simply application functions or similar, use an

option menu. For example, a report dialog that allows the user to
select a statistic to calculate is best done with an option menu
rather than a scrolled list.
Use panels for 2 to 6 choices.
181
Chapter
TSL Style Guide
Use a panel when it is important to emphasise the either/or nature

of a selection.
Use label items to separate logical groups of dialog items. Do not

use for simply titling the dialog unless it is unclear from the context.
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.
Try to use the default layout policy of TSL wherever it is acceptable.
Place the most important dialog items at the top of columns

drawing the eye down the columns, or at the left of a row drawing
the eye across the rows.
Use multiple columns to keep the dialog height reasonable and to

group logically related entries. In OpenLook, a single column
layout is preferable.
PART 2
TSL Reference
TSL Reference
TSL Reference
In this section, all of the TSL commands are defined.

Commands are presented in alphabetical order and
examples of their use are given where appropriate.
185
TSL Reference
Notation
In the following reference section, the syntax of commands is described

using a notation known as Backus-Naur Form (BNF).
In this notation, the following symbols are used:
[]
Indicates that the sequence within the brackets is

optional.
{}
Indicates that the sequence within the braces may be

repeated any number of times (including zero).
Is used to separate alternative sequences.
|
()
Are used for grouping.
name
Indicates the name of a syntactic construct defined

elsewhere.
Other characters are treated as literals.

So, for example, given the simple syntax description:
cmd = CONFIRM msg [yes_label [no_label]]
where msg, yes_label, no_label = quoted_string
each of the following is a valid cmd
CONFIRM "Do you want to delete everything?"
CONFIRM "Quit Application?" "Yes, Quit"
CONFIRM "Print to file?" "Yes" "No, to screen"
The following predefined constructs are assumed in the reference

section:
Construct
Description
TQL_expression
Indicates any valid TQL expression.
quoted_TQL_bool_expr
Indicates any valid TQL boolean expression

between quotes.
TQL_variable_name
Indicates any valid TQL variable name.
TQL_bool_var
Indicates any valid TQL boolean variable

name.
integer
Indicates any sequence of characters which

form a valid integer.
Construct
Description
data_type
Indicates the name of a valid TQL data

type, thus data_type = STRING | BYTE |
SHORT | LONG | SHORTREAL | REAL | COMPLEX | BOOL | DATE | TIME | CHAR.
quoted_string
Indicates any sequence of characters

enclosed by double or single quotation
marks.
filename

represents a valid file name on the underlying operating system.
bitmap_file

represent a valid bitmap file name which
can be found by searching the directories in
the system variable XBMLANGPATH.
commands
Indicates any sequence of valid TSL commands (possibly empty).
system_command

are to be executed by a UNIX shell.
dimension_unit
Indicates any sequence of numbers optionally followed by the letter c, m, i, p l

or g, for example 13p or 15i.
dimension_unit_no_grid Indicates any sequence of numbers followed by the letter c, m i, p or l.

procedure_name
A sequence of alphabetic or numerical

characters. The first letter must be alphabetic.
In addition, the dialog items have several attributes in common which

are used for positioning.
position_attribute = XPOS = dimension_unit
| YPOS = dimension_unit
| XORIGIN = ( LEFT | CENTRE | CENTER | RIGHT )
| YORIGIN = ( TOP | CENTRE | CENTER | BOTTOM )
| XADJUST = 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
Enables or disables abort mode for some or all query

errors
Syntax
ABORT [ ON [ ( EXCEPT | ONLY ) errlist ] | OFF ]
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.
Initially, abort mode is enabled.

Text substitution is not performed on errlist.
189
TSL Reference
Example
ABORT OFF
Disables abort mode for all TQL errors.

ABORT ON
Enables abort mode for all TQL errors.

ABORT ON ONLY q-113, d52, q-114, f51
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
Adjusts the applications notion of the current line

number
Syntax
ADJUST nlines
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
A number of aspects of the behaviour or appearance of TSL

applications may be configured by changing the values of application
resources.
The following sections list the resource names that are recognised by
TSL.
Fonts
Resource
Description
labelFont
The font used for messages and titles and for

labels within a dialog. May be fixed or proportional.
dataFont
The font used for data values within a dialog.

Should be a fixed-width font.
buttonFont
The font used for button labels in dialogs. May be

fixed or proportional.
menuFont
The font used for menu entries. May be fixed or

proportional.
toolboxFont
The font used for toolbox labels. May be fixed or

proportional.
normalFont
The font used for displaying text in the TSL terminal window. Should be a fixed-width font.
boldFont
The font used for displaying bold text in the TSL

terminal window. Should be a fixed font width the
same width and height as normalFont.
useVueFonts
If TRUE, HP VUE system and user fonts are used

by the application as appropriate.
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
with FontSets. A FontSet contains all the necessary fonts required to

display the text for a particular language. The following FontSets must
be configured in order for TSL to support local language fonts:
Resource
Description
labelFontset
The font used for messages and titles and for

labels within a dialog. May be fixed or proportional.
dataFontset
The font used for data values within a dialog.

Should be a fixed-width font.
buttonFontset
The font used for button labels in dialogs. May be

fixed or proportional.
menuFontset
The font used for menu entries. May be fixed or

proportional.
toolboxFontset
The font used for toolbox labels. May be fixed or

proportional.
normalFontset
The font used for displaying text in the TSL terminal window. Should be a fixed-width font.
boldFontset
The font used for displaying bold text in the TSL

terminal window. Should be a fixed font width the
same width and height as normalFont.
useVueFontset
If TRUE, HP VUE system and user fonts are used

by the application as appropriate.
Note the xfontsel application provides a useful method of displaying

all the fonts currently recognised by your X-server.
193
TSL Reference
Terminal Window
Resource
Description
rows
Integer. Number of rows in the TSL terminal window
columns
Integer. Number of columns in the TSL terminal

window
bufrows
Integer. Number of rows in the vertical scroll buffer

for the TSL terminal window.
bufcols
Integer. Number of columns in the horizontal scroll

buffer for the TSL terminal window.
halfBright
Colour to use for representing half-bright text in

the TSL terminal window. Can be specified symbolically by using the name of any colour known to
the X windows server or using the notation #aabbcc where aa, bb, cc are hexadecimal values in
the range 0-ff giving the red, green and blue
components respectively of the colour.
disableWMClose Specifies whether the window managers close

function is available in the TSL application. By
default, the close function is enabled. If this
resource is TRUE, the close function is disabled.
Dialog Appearance
Resource
Description
columnGap
Integer. Gap in pixels between columns in a multicolumn dialog.
rowGap
Integer. Gap in pixels between rows in a dialog.
horizMargin
Integer. Gap in pixels between left and right borders of dialog and nearest dialog element.
vertMargin
Integer. Gap in pixels between top and bottom

borders of dialog and nearest dialog element.
Resource
Description
labelGap
Integer. Gap in pixels between a dialog items label

and the dialog item itself.
buttonGap
Integer. Gap in pixels between application defined

buttons.
buttonRowGap
Integer. Gap in pixels between rows of application

defined buttons.
buttonExtra
Integer. Pixels added either side of the largest

application defined button label to define the size
of all buttons.
separatorGap
Integer. Gap in pixels between the dialog items

and the separator and the separator and application defined buttons.
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
Integer. Default value for COLUMNS attribute.

This should be in the range 1 30.
defaultButtonColumns Integer. Default value for BUTTONCOLUMNS

attribute. This should be in the range 1
30.
alignRows
Boolean. Default value for ALIGNROWS

attribute.
alignColumns
Boolean. Default value for ALIGNCOLUMNS

attribute.
alignItems
Boolean. Default value for ALIGNITEMS

attribute.
defaultMode
Integer. Default value for MODE attribute.

This should be in the range 0 5.
195
TSL Reference
Resource
Description
buttonLayout
String. Default value for BUTTONLAYOUT

attribute. This should be either COLUMNCENTRE or DIALOGCENTRE.
busyOnApply
Boolean. Default value for BUSYONAPPLY

attribute.
Scroll bar display

Resource
Description
horizontalscroll
Used to indicate if a horizontal scroll bar

should be displayed in the terminal output
window. The default setting for this
resource is FALSE.
verticalscroll
Used to indicate if a vertical scroll bar

should be displayed in the terminal output
window. The default setting for this
resource is TRUE.
Toolbox Appearance
The following resources set the default values for toolbox attributes.
They may be overridden using the TOOLBOX command.
Resource
Description
toolboxToolGap
Integer. Default value for TOOLGAP attribute.
toolboxGroupGap
Integer. Default value for GROUPGAP

attribute.
toolboxFrame
Boolean. Default value for FRAME attribute.
toolboxGravity
String. Default value for GRAVITY attribute.

This should be one of NORTH, EAST, SOUTH,
WEST.
toolboxRows
Integer. Default value for ROWCOLS attribute

if the GRAVITY attribute is either NORTH or
SOUTH.
Resource
Description
toolboxColumns
Integer. Default value for ROWCOLS attribute

if the GRAVITY attribute is either EAST or
WEST.
197
TSL Reference
Dates and times

Resource
Description
dateInputFormat
String. Determines the order of the day,

month and year fields when interpreting
dates. Valid values are any combination of
%d, %m and %y (representing day, month and
year respectively) in any order. For example, in the UK the usual format would be
%d%m%y. If not set, TSL determines the
default from the users local language environment.
dateOutputFormat
String. Determines the format used when

performing text substitution on date values.
The format is given by a template string
which contains conversion specifications
possibly separated by characters. Valid
specifications are %m for month number, %d
for day number, %y or %Y for year number
(%Y gives year in the form 19xx, %y simply
gives xx), %h or %b for the abbreviated
month name and %B for the full month
name. If not set, the default format used is
a numeric representation of day, month and
year, separated by slashes, in the order
determined by dateInputFormat.
timeOutputFormat

performing text substitution on time values
and for input/output of times in dialogs.
Valid formats are %H:%M:%S and %H:%M
where the colon may be substituted by any
non-alphanumeric separator and %H, %M, %S
represent hours, minutes and seconds
respectively.
Printing
Resource
Description
printCommand
String. The operating system command that

TSL uses to spool output to the system
printer.
rawPrintCommand
String. The operating system command

which TSL uses to spool output to the
graphics printer. Only useful on those systems which support graphics via the PLOT
query.
printerModel
String. The name of a printer model which

is used to determine the character
sequences to use to produce highlighting
for output to the printer. For a list of the
supported printer models refer to the
release notes for your system.
Menus and dialogs

Resource
Description
maxDialogs
Defines the maximum number of dialogs that

can be defined. The default value is 200.
maxMenuItems
Defines the maximum number of items that

can be defined in a menu pane. The default
value is 20.
maxMenuNesting
Defines the maximum number of levels to

which a menu may be nested. The default
value is 5.
199
TSL Reference
Miscellaneous
Resource
Description
logFile
String. The name of a file to use for logging

error and warning messages. If blank, logging is disabled. If not specified, the file
tsl.log in the users home directory is
used. Note that if TSL is started from a terminal, all messages are also logged to that
terminal regardless of the setting of this
resource.
queryBufferSize
Integer. The size of the query buffer in

bytes.
complexOutputFormat

performing text substitution on complex
values. The format is given by a template
string which contains conversion specifications possibly separated by characters. Valid
specifications are %x, %y, %X, %Y where
%x, %y stand for the real and imaginary
parts respectively of the complex number,
right justified within their field, %X represents the real part, left justified and %Y represents the imaginary part, left justified. The
default format is %x,%y.
displayErrors
Boolean. Controls whether an error dialog is

displayed if a TSL error occurs that will
result in TSL terminating. If set to TRUE, an
error dialog is displayed whenever a TSL
error occurs. The default setting is FALSE.
killCanvasOnError
Boolean. Determines whether the Kingfisher

canvas windows are killed off whenever a
TSL error occurs. The default setting is
FALSE.
ASK
Assigns a TQL variable from user input

Syntax
ASK varname
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.
This command is provided for backwards compatibility only and

should not be used in new applications. The recommended
method of obtaining user input is to use a dialog containing a
single text input field.
Example
ASK cust_name
QUERY DISPLAY * FROM results WHERE cust = cust_name ;
performs a DISPLAY query based upon a value for cust_name read from
the terminal.
201
TSL Reference
ASKDIALOG
Opens and processes a previously defined dialog

Syntax
ASKDIALOG [ dialog_number / dialog_name]
[ dialog_title ]
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
reports, the %DLOGCHANGED variable can be used to determine if a

previously generated and saved report can be used or whether the
report needs to be re-generated.

The dialog is dismissed if the user clicks on the OK, Cancel or Close
button or dismisses the dialog using window manager controls. If any
other actions occur, the dialog remains displayed but insensitive until it
is closed (using CLOSEDIALOG) or reactivated using ASKDIALOG.
The special query variable %DIALOGVAL is set to TRUE or FALSE
depending on whether the dialog variables should be processedthat
is, the dialog was submitted. If the dialog is submitted then, for each
item in the dialog, the value of the associated query variable is set from
the current state of the dialog item. If the query variable does not
already exist, it is created. If the value of the dialog item does not
correspond to a valid value for the variable, the variable is set to NULL.
If the dialog is cancelled, the value of any query variables associated
with the dialog elements remain unchanged.
The special query variable %BUTTONVAL is set to the string representing
the selected dialog action. If a standard control button was pressed, the
value is one of OK, Cancel, Apply, Reset or Close. If an
application defined button is pressed or the value of an active dialog
item is changed, the variable is set to the value of the ACTION attribute
associated with the button or dialog item.
If a dialog is not closed as part of processing a button, it can be
reactivated by calling ASKDIALOG again with the appropriate dialog
name or number. The sensitivity of the buttons and dialog items and the
readonly status of text and multitext items will be evaluated again and
processing is repeated.
Dialogs can be explicitly closed using the CLOSEDIALOG command.
Text substitution is performed on dialog_number, dialog_name and
dialog_title.
203
TSL Reference
Examples
ASKDIALOG
simply processes the current dialog. The dialog window is untitled.

ASKDIALOG 2 "Graph Setup"
processes dialog 2, labelling it Graph Setup.

ASKDIALOG dbase_open "Open Database"
processes the dialog named dbase_open, labelling it Open Database.
ASKMENU
Activates the application menu system

Syntax
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
Causes processing to break out of a REPEAT or

WHILE loop
Syntax
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
Defines the attributes of the current buffer and turns

text buffering on or off
Syntax
BUFFER [ ON | OFF | attributes ]
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
Calls a TSL procedure and defines parameter values

for the procedure call
Syntax
CALL procname ( [arguments] )
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 )
Calls the procedure do_report passing as parameters the variables

v_cust and v_date.
CALL do_report( "[v_cust]", \[1/1/95] )
Calls the procedure do_report passing as parameters the string formed

by performing text substitution on the variable v_cust and the date
[1/1/95]. Note how the backslash character (\) is used to stop TSL
performing text substitution.
209
TSL Reference
CANVAS
Commands
Performs various operations on the graphics canvas

Syntax
CANVAS
CANVAS
CANVAS
CANVAS
CANVAS
CANVAS
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
Loads a colourmap into the canvas

Syntax
CANVAS COLOURMAP [ LOAD ] 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:
The command was executed successfully.
3:
Kingfisher was busy executing on behalf of another client.
7:
The colourmap could not be found.
8:
The colourmap file was not in the correct format.
Colourmap names are not case-dependent and are limited to 14

characters in length. Text substitution is performed on colourmap.
If no graphics canvas exists, a CANVAS ON command is executed
automatically.
211
TSL Reference
Example
CANVAS COLOURMAP LOAD myramp
loads the colourmap MYRAMP into the canvas.
CANVAS
CONFIG
Loads a hardcopy configuration into the canvas

Syntax
CANVAS CONFIG [ LOAD ] 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
Value
Description
0:
3:
9:
The configuration file could not be found.
10 :
The configuration file was not in the correct format.
Configuration filenames are not case-dependent and are limited to 14

characters in length. Text substitution is performed on config.
If no graphics canvas exists a CANVAS ON command is executed
automatically.
Example
CANVAS CONFIG LOAD printroom1
loads the hardcopy configuration PRINTROOM1 onto the canvas.
213
TSL Reference
CANVAS
HARDCOPY
Sets or gets the values of the Kingfisher hardcopy

properties
Syntax
CANVAS HARDCOPY [ SET ] property_value_list
CANVAS HARDCOPY GET property_var_list
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.
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
Gets the value of the orientation property, which indicates landscape

or portrait mode, and stores it in the TQL variable ovar.
215
TSL Reference
CANVAS
MODE
Sets various modes on the graphics canvas

Syntax
CANVAS MODE mode_value_list
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.
Initially both EDIT and AUTORAISE mode are disabled.

Text substitution is performed on mode_value_list.
automatically.
Example
CANVAS MODE autoraise=on
enables AUTORAISE mode.
CANVAS
ON,
CANVAS
OFF
Creates or destroys the graphics canvas

Syntax
CANVAS ON [ canvas_mode ] [ geometry ] [ attributes ]
CANVAS OFF [ off_attributes ]
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:
If no mode is specified, Kingfisher is executed using the

-tsledit argument. The display window contains the full menu
bar and other decorations. Graphs in the display window can be
edited and changed by the user.
If NOEDIT mode is specified, Kingfisher is executed using the

-tsl argument. The display window contains only those menu
items that are not concerned with editing graphsthat is, it
contains the cursor, zoom, measure, print and snapshot commands.
Graphs cannot be edited by the user.
If NOMENU mode is specified, Kingfisher is executed using the

-tslnomenu argument. The display window does not contain any
menu bar nor any other decorationit is basically a raw X window.
Graphs cannot be edited and no interactive operations are available
on the graph.
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
If the class attribute is set to Netstats, the same resource would be

specified as:
Netstats*foreground: White
The main resource file for the default Kingfisher class is

$TQL_CLIENT_DIR/appdefs/Kingfisher. If you change the application
class you should also supply the bulk of resources set in this file. The
most important of these are the font resources, the size resources for
widgets and resources which set relative positioning of widgets.
As for the default class, resources can be set for all users by creating a
resource file for the application class in the Kingfisher appdefs
directory. For the example above, the file would be

$TQL_CLIENT_DIR/appdefs/Netstats. The file can, however, be
placed anywhere and the X environment variable XFILESEARCHPATH set
to include its location.
Text substitution is performed on the class name.
The CANVAS OFF command terminates the connection with the
Kingfisher canvas and, if this is the only connection, destroys the
window and terminates Kingfisher. Setting the attribute all to TRUE
terminates all canvasses in a multi-canvas application.
Examples
CANVAS ON
creates a Kingfisher canvas in the default mode with the default

position and size.
CANVAS ON NOMENU 0 0 600 500
creates a Kingfisher canvas of 600x500 pixels as a raw X window

positioned at the top left of the display.
CANVAS OFF
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
Resizes the graphics canvas

Syntax
CANVAS RESIZE geometry
Arguments
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.
Examples
CANVAS RESIZE 0 0 600 500
Resizes the Kingfisher canvas to 600x500 pixels and positions it at the

top left of the display.
CLEAR
Clears the TSL terminal window

Syntax
CLEAR
Description
Clears the TSL terminal window and resets the output position to the
top of the window.
221
TSL Reference
CLOSEDIALOG
Closes the specified dialog

Syntax
CLOSEDIALOG [ dialog_number | dialog_name]
Arguments
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
closes dialog number 3.

CLOSEDIALOG print_options
closes the dialog named print_options.
Comment
Annotates a script file

Syntax
# 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
If the # is not the first non-space character on a line, the text is

processed as usual, for example:
DECLARE exp#
creates a TQL variable named exp#, and:

'###### PARAMETRIC TEST REPORT ######
outputs a title containing several # characters.
223
TSL Reference
CONFIRM
Displays a confirmation dialog

Syntax
CONFIRM msg [ [,] yes_label ] [ [,] no_label ]
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
Declares TQL variables and optionally sets an initial

value
Syntax
DECLARE TQL_variable_name [ TQL_expression ] ,
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
Defines a TSL procedure and its parameters

Syntax
DEFPROC procname ( [parameters] )
commands
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
This defines a procedure power which uses two parameters. The

parameter X is passed by reference and the parameter N is passed by
value.
DIALOG
item
Defines a dialog item and adds it to the current dialog

Syntax
The syntax is different for each dialog item. In addition, DIALOG
LAYOUT, DIALOG SKIP and the DIALOG LIST editing commands are
covered separately.
DIALOG [ data_type ] dialog_type [ (parameters) ] \
[ varname ] label extra attributes
Arguments
dialog_type = LABEL | TEXT | MULTITEXT |
SLIDER | HSLIDER | VSLIDER |
LIST | OPTION | PANEL |
TOGGLE | BUTTON | CALENDAR | TIMERANGE
parametersdepend upon dialog_type
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)
Multi-line text field
(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)
Time range bar
(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
Creates an application defined button in the dialog

Syntax
DIALOG BUTTON [DEFAULT] button_label attributes
DIALOG BUTTON [DEFAULT] [button_label] ICON primary_bitmap \
[active_bitmap] attributes
Arguments
button_label = quoted_string
button_action = quoted_string
primary_bitmap = bitmap_file
active_bitmap = bitmap_file
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
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
Defines a calendar item and adds it to the current

dialog
Syntax
DIALOG [DATE] CALENDAR datevar label [attributes]
Arguments
datevar= TQL_variable_name
label= quoted_string
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
Creates a text or iconic label item and adds it to the

current dialog
Syntax
DIALOG LABEL label [attributes]
DIALOG LABEL ICON bitmap [attributes]
Arguments
bitmap = bitmap_file
attribute = SENSITIVE = boolean_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.
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
Sets the layout parameters for the current dialog

Syntax
DIALOG LAYOUT attributes
Arguments
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
This must be set to an integer in the range 1 30. It

defines the number of columns in the dialog.
BUTTONCOLUMNS This must be set to an integer in the range 1 30. It

defines the number of columns that will be used in
laying out application defined buttons.
235
TSL Reference
Parameter
Description
BUTTONLAYOUT
This defines whether buttons placed in the dialogs

button area should be centred in each button column (COLUMNCENTRE, the default) or whether they
should be tightly packed in the centre of the dialog
(DIALOGCENTRE).
ALIGNCOLUMNS
If this is true, the x-position of the start of the nth

column in the dialog is set according to the widest
element in the n-1th column. If it is false, each element is positioned immediately to the right of the
element in the same row of the n-1th column.
ALIGNROWS
If true, the y-position of the elements in the nth row

are set according to the tallest element in the n-1th
row. If false, each element is positioned immediately
below the item in the same column of the n-1th
row.
ALIGNITEMS
If true, within each column the labels of the dialog

elements are right-aligned.
BUSYONAPPLY
If this is set to TRUE and an action is initiated that

does not dismiss the dialog, the mouse pointer
changes to a busy-hourglass. If this is set to FALSE,
all the items in the dialog are greyed-out. In both
cases, the dialog is desensitised until it is displayed
again using another ASKDIALOG command.
MODE
If 0, OK and Cancel buttons are enabled; if 1, OK,

Apply and Cancel buttons are enabled; if 2, Apply
and Reset buttons are enabled; if 3, a Close button
is enabled; if 4, Apply, Reset and Close buttons are
enabled; if 5, Apply and Close buttons are enabled.
The default button for modes 0 and 1 is the OK button and it is the Apply button for modes 2, 4 and 5.
Mode 3 has no default button.
Parameter
Description
WIDTH
Defines the width of the dialogs main area in either

inches, centimetres, millimetres, pixels or characters.
The default value is the width needed to accommodate all of the dialog items if their positions are
determined by TSL.
HEIGHT
Defines the height of the dialogs main area in either

inches, centimetres, millimetres, pixels or characters.
The default value is the height needed to accommodate all of the dialog items if their positions are
determined by TSL.
GRID
Defines the number of grid units there are across the

top and down the side of the dialogs main area.
This is used for positioning dialog items using grid
units. The default is 100x100.
The values for the BUTTONCOLUMNS, BUTTONLAYOUT, COLUMNS,

ALIGNCOLUMNS, ALIGNROWS, ALIGNITEMS, BUSYONAPPLY and MODE
attributes are obtained from the X defaults database if they are not
defined. See X Resources and the Applications defaults file on page 161
for a complete description of how these default values can be modified.
Attribute
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
If the resource corresponding to one of these attributes is not defined in

the application default file, the attributes internal default is used.
The DIALOG LAYOUT command must be executed before the first item in
the dialog is created.
Text substitution is performed on the values given with all of these
attributes.
Examples
DIALOG
DIALOG
DIALOG
DIALOG
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
Defines a selection list and adds it to the current

dialog
Syntax
DIALOG [ STRING ] LIST [(size)] stringvar label choice_items \
[list_attributes]
Arguments
size = integer
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
| MINWIDTH = integer
| MAXWIDTH = integer
| SCROLLMODE = 0 2
| SELECTION_POLICY = SINGLE | BROWSE
| MULTIPLE | RANGE | DISCONTIGUOUS
| SELECTION_DELIM = quoted_string
| SELECTION_MAXITEMS = integer
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:
By specifying a list of strings. Text substitution is performed on

each of these strings.
239
TSL Reference
Using a query buffer expansion. In this case, column_name must be

the name of one of the columns in the query buffer. The choices
are obtained by expanding the value of column_name as a string for
each row in the query buffer. If the optional count modifier is
present, only the first count rows in the buffer is used. Note that
this query buffer expansion is performed once only at the time that
the dialog item is defined, not when the dialog is processed. (The
expansion is held internally in TSL. Only the first 256 KB characters
are retained, so if you have a very long list you may find that it has
been truncated).
Using a filename. In this case, the contents of the file is displayed in

the selection field.
When the dialog is processed, the selection defaults to stringvar. If

stringvar is not defined or does not have a valid value, a LIST item is
shown with no item currently selected.
If the user selects an item from the list or changes the list selection, 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, 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 a list item is selected. Scrolling lists are also made active
when the current list item is deselected. 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.
If an item in a list is double-clicked, the dialogs default button (if one
exists) is made active.
Sensitivity
LIST dialog items can use the SENSITIVE attribute. An insensitive LIST
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.
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
Allows single selection. An item is selected by

clicking on it. This is the default.
BROWSE
Allows single selection. Clicking and dragging the

cursor through the list highlights each item in turn.
The highlighted item is selected when the mouse
button is released. An item may also be selected in
the same way as for SINGLE selection.
241
TSL Reference
Attribute
Meaning
MULTIPLE
Allows multi-selection. An item is selected by clicking on it.
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
Allows multi-selection. Similar to RANGE but several

ranges may be selected by pressing the Ctrl key
while selecting ranges.
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:
%SELECTED holds a delimited list of the items that were selected
%NUMSELECTED records the number of items that were selected
%LISTPOS records the list position of each selected item in a

numeric array
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
WHERE batch = [batch_no] ;

DIALOG LIST(4) parmchosen "Parameter to Plot" pname/10
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= ";"
creates a scrolling list that allows multiple selection up to a maximum of

5 items. The selected items will be stored in the TQL variable
parmchosen and the system variable %SELECTED. Items will be stored as
a semi-colon delimited list. The number of items that were selected will
be recorded in %NUMSELECTED while %LISTPOS will record the list
position of each of the selected items.
243
TSL Reference
DIALOG
LIST
(list
commands)
Change the contents of a list

Syntax
DIALOG LIST varname command
Arguments
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 }
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"
inserts the given values at position 10 of the list identified by the

variable town_value.
DIALOG LIST ingredient DELETE "[ingred1]"
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.
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
Creates a multiline text item and adds it to the current

dialog
Syntax
DIALOG [ STRING ] MULTITEXT(size_spec) textvar label \
[attributes]
Arguments
size_spec = columns [, rows ]
columns = integer
rows = integer
textvar = TQL_variable_name
| READONLY = boolean_attribute
| ALLOWNULL = boolean_attribute
| NULL_ERR_MSG = quoted_string
| MAXLEN = integer
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
Defines an option menu and adds it to the current

dialog
Syntax
DIALOG [ STRING ] OPTION stringvar label choice_items \
[option_attributes]
Arguments
count = integer
option_attributes = option_attribute { , option_attribute }
option_attributes = ACTION = quoted_string
Description
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.
Simply by specifying a list of strings. Text substitution is performed

on each of these strings.

present, only the first count rows in the buffer are used. Note that
expansion is held internally in TSL. Only the first 256k characters
been truncated.)
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
or preselected value does not affect the value of %DLOGCHANGED.
Text substitution is performed on label, choice_items and the values
Activation
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.
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
validates any text dialog items. If this is successful, ASKDIALOG returns

and puts Parm Selected in %BUTTONVAL and TRUE in %DIALOGVAL.
DIALOG
PANEL
Defines a selection panel and adds it to the current

dialog
Syntax
DIALOG [ STRING ] PANEL stringvar label choice_items \
[panel_attributes]
Arguments
count = integer
panel_attributes = panel_attribute { , panel_attribute }
panel_attributes = ACTION = quoted_string
Description
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.


been truncated.)
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
Text substitution is performed on label, choice_items and the values
Activation
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 selection panel with three items.

DIALOG PANEL parmchosen "Parameter to Plot" pname/10
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
Allows columns to be skipped when determining the

layout of a dialog
Syntax
DIALOG SKIP [ (nskip) ]
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)
Defines a slider item and adds it to the current dialog

Syntax
DIALOG int_type slider_type [(size)] var label min max \
[attributes]
Arguments
int_type = BYTE | SHORT | LONG
slider_type = SLIDER | HSLIDER | VSLIDER
size = integer
var = TQL_variable_name
min = integer
max = integer
SENSITIVE = boolean_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
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
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
Creates a text item and adds it to the current dialog

Syntax
DIALOG [ data_type | AUTO] TEXT(length_spec) textvar label \
[ attributes ]
Arguments
length_spec = display_length [, max_length ]
display_length = integer
max_length = integer
textvar = TQL_variable_name
| 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
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
max_length respectively. If max_length is omitted, it is assumed to be

the same as display_length. If the maximum length is greater than the
display length, the field scrolls to allow for the extra width characters.
When data_type is complex, two text fields are created, one for the real
part and one for the imaginary part. In this case the display and
maximum lengths apply to each field individually.
If data_type is omitted, string data is assumed.
If, when the dialog is processed, textvar is not defined or its value is not
valid for data_type, the field contents are initialised to an empty string.
Since the text field allows entry of arbitrary text it is possible that the
value entered by the user is not a valid value for textvar. In this case,
textvar is set to NULL when the dialog is submitted. The recognised
formats for data of each type are the same as for TQL expressions. The
format used for output is the same as that used when substituting for
text items (q.v).
If the user changes the content of the text field, the system variable
or preselected value does not affect the value of %DLOGCHANGED. In
addition, if, after editing a text field the user returns to the original
value, %DLOGCHANGED is not updated.
Text substitution is performed on size, label and the values given with
the SENSITIVE, SECRET, READONLY, RANGEMIN, RANGEMAX,
RANGE_ERR_MSG, ALLOWNULL, NULL_ERR_MSG, XPOS, YPOS, XADJUST,
Activation
Text items cannot be made active, although pressing Return activates
the default button (if there is one).
Sensitivity
An insensitive text field cannot be selected or edited.
The READONLY attribute determines whether the text field is only
readablethat is, it cannot be edited. Unlike insensitive text items, a
readonly text item can be selected. By default, text items are not
readonly.
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
Defines a time range item and adds it to the current

dialog
Syntax
DIALOG [TIME ARRAY] TIMERANGE rangevar label [attributes]
Arguments
rangevar = TQL_variable_name
| 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.
ACTION, SENSITIVE, GRANULARITY, MAXRANGES, XPOS, YPOS, XADJUST,
Activation
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
creates an hour slide bar labelled Opening Hours. It allows users to

enter a maximum of 2 time ranges to an accuracy of 5 minutes.
263
TSL Reference
DIALOG
TOGGLE
Defines a toggle item and adds it to the current dialog

Syntax
DIALOG [ BOOL ] TOGGLE boolvar label [attributes]
Arguments
boolvar = TQL_variable_name
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
Sends a page-break to the output device

Syntax
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
Displays an error message

Syntax
ERROR error_message
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
Performs text expansion of the passed TSL command

line before executing the line
Syntax
EXPAND TSL_command
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
Enables or disables fill mode

Syntax
FILL [ ON | OFF ]
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.
produces output similar to:

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
Sets the query buffer cursor position to the first row

in the query buffer
Syntax
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
Enables a graphics cursor on the current graph

Syntax
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.
automatically. If no graph exists, a default graph is created
automatically.
271
TSL Reference
GRAPH
DRAW
Executes a query command and plots the resulting

data in the current graph
Syntax
GRAPH DRAW query ;
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
The query did not or could not return any data.

automatically.
Examples
GRAPH DRAW display spectrum from spectra ;
passes the specified query to Kingfisher where it is executed. The

dataset that is retrieved is plotted on the current graphwhich must be
the last created.
GRAPH DRAW print mean(a) ;
plots the results of a PRINT command, which is useful for evaluating

expressions for overlays.
273
TSL Reference
GRAPH
FORMAT
Loads a graph format into the current graph or saves

the format of the current graph
Syntax
GRAPH FORMAT [ LOAD ] format
GRAPH FORMAT SAVE 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
Value
0
Description
Value
Description
The graph format could not be found.
The graph format file was not in the correct format.
The graph format could not be saved. Check the permission

of the appropriate directories in $TQL_CLIENT_DIR.
Format names are not case dependent and are limited to 14 characters
in length. Text substitution is performed on format.
automatically.
Example
GRAPH FORMAT LOAD spectra
loads the format SPECTRA into the current graph.
275
TSL Reference
GRAPH
POSITION
Sets the position and size of a graph on the canvas

Syntax
GRAPH POSITION geometry
Arguments
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.
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.
automatically.
Example
GRAPH POSITION 0 0 50 100
positions the graph in the right hand half of the canvas.
GRAPH
PROPERTY
Sets or gets the values of the properties of the current

graph
Syntax
GRAPH PROPERTY [ SET ] property_value_list
GRAPH PROPERTY GET property_var_list
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.
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.
names of all graph properties, are described in Chapter 9 of the
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.
277
TSL Reference

automatically. If no graph exists and a SET command is executed, a
default graph is created automatically.
Examples
GRAPH PROPERTY SET xtitle="X Axis"
Sets the xtitle property, the title on the X axis.

GRAPH PROPERTY title/0="Main title" title/1="Subtitle"
Sets the first and second titles for the graph.

GRAPH PROPERTY GET linestyle/3=lvar
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
Designates the text file to be used as on-line help for

the application
Syntax
HELPFILE filename
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
results in the following being displayed in the help dialog.

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:
If the environment variable TB_TSL_SPEC_PATH is defined, each

directory on this path is searched in turn.
Otherwise:
If the environment variable TB_SPEC_PATH is defined, each

Otherwise:
The current directory is searched.
Note that only one of the three alternatives is searched. Thus if

TB_TSL_SPEC_PATH is set but the help file is not found in any of the
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
Text output from the TSL application may be highlighted using

combinations of five attributes: Bold, Underline, Emphasis, User1,
User2. The attribute used for text output depends upon the current
settings of the attribute flags. Initially all attributes are disabled. The
current state of any attribute flag may be toggled by including the
associated highlighting indicator in the text.
Attribute
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
Printed in font specified by boldFont

resource
Underline
Underlined
Emphasis
Simulation of Half-bright using the colour specified by the halfBright resource
User1, User2
Ignored
Note that highlighting indicators are recognised only in text output

lines. In particular, they cannot be used in messages for INFO or ERROR
dialogs nor in the text of help files.
Example
'@BThis text is bold. @UThis text is underlined and
'bold. @BThis text is underlined only. @UThis text is
'not highlighted.
would produce output similar to:

This text is bold. This text is underlined and bold.
This text is underlined only. This text is not
highlighted.
283
TSL Reference
IF,
ELIF,
ELSE,
ENDIF
Allows TSL commands to be executed conditionally

Syntax
IF if_expression
commands
{ elif_clause }
[ else_clause ]
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,
it is not permissible for the IF statement to appear in an included file

with the matching ENDIF in the including file.
Examples
IF doexit
STOP
ENDIF
IF real_val >= 0
QUERY SET VAR sqrt_val SQRT(real_val) ;
ELSE
ERROR "Can't take square root of negative number"
ENDIF
IF %menuval = "Open"
SCRIPT open.tsl
ELIF %menuval = "Close"
SCRIPT close.tsl
ELIF %menuval = "Exit"
SCRIPT exit.tsl
ELSE
INFO "Not yet implemented"
ENDIF
285
TSL Reference
IFOK
Allows TSL commands to be executed conditional upon

the success of the last Query command
Syntax
IFOK
commands
{ elif_clause }
[ else_clause ]
ENDIF
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
Displays or clears information messages

Syntax
INFO [ info_message ]
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
Enables or disables justification

Syntax
JUSTIFY [ ON | OFF ]
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.
Initially justification is disabled.

Note that when table mode is enabled (see TABLE), justification is
temporarily disabled until table mode is turned off.
Example
FILL ON
JUSTIFY ON
'This is an example to illustrate the use of
'justification. Notice how the number of spaces
'between some words has been increased to ensure an
'even right margin. This mode is most useful for
'producing free format reports.
would produce output similar to:

This is an example to illustrate the use of
justification. Notice how the number of spaces between
some words has been increased to ensure an even right
margin. This mode is most useful for producing free
format reports.
KFPROC
Executes an analysis procedure in the graphics

canvas
Syntax
KFPROC [ NOPROMPT ] [ NOEDIT ] procname
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
The procedure was executed successfully.
The named procedure could not be found.
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.
When the canvas is created, it is normally placed in edit mode. In this

mode, once a graph has been produced, the user may use the
Kingfisher edit menu to alter details of graph format, annotation, and so
on. This feature can be disabled for a particular procedure execution by
specifying the NOEDIT modifier. If the NOPROMPT modifier is specified,
Kingfisher does not prompt the user for the value of any variables used
289
TSL Reference
in the procedure. Instead the TSL application is responsible for setting

the values of these variables prior to execution of the KFPROC
command.
automatically.
Those familiar with the command PROC may continue to use the PROC
command which behaves in the same way as the KFPROC command.
Examples
KFPROC NOPROMPT myproc
IF %grstatus <> 0
ERROR "Could not plot Spectra"
ENDIF
LAST
Sets the query buffer cursor position to the last row in

the query buffer
Syntax
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
Sets the page length for printer output

Syntax
LENGTH 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
Sets the default positions of the left and right margins

Syntax
MARGIN left_margin [, right_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
resets both the left and right margins.

MARGIN 1
resets the left margin only.
293
TSL Reference
MENU,
MENU SKIP
Defines or skips an item in the applications pulldown menu system

Syntax
MENU menu_id menu_label \
[ menu_accelerator menu_accelerator_label ] \
[ attributes ]
MENU menu_id SKIP
Arguments
menu_id see below
menu_label = quoted_string
menu_accelerator = standard Xt keysym definition
menu_accelerator_label = quoted_string
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.
The menu entry can optionally define a keyboard accelerator. The

menu_accelerator is a quoted string which contains a standard X
keysym definition of the key sequence required to activate the menu for
example, Ctrl<Key>Z or Shift<Key>Z. The menu_accelerator_label is
a quoted string that is used to label the menu entry with the key
sequence.
The menu system is not actually built until the first ASKMENU command
is executed. Once the ASKMENU command has been executed, no further
MENU commands may be executed. If, at the time that the menu is built,
a top-level item is defined with no pull-down menu, a pull-down menu
comprising a single item with the same label as that top-level item is
built. Similarly, if a pull-down menu has been defined but no
corresponding item in the parent menu is defined, the first item of the
pull-down menu is used as the label in the parent menu. If there is a
gap in the numbering system for a pull-down menu, a separator item is
inserted.
When the ASKMENU command is executed, TSL waits
or a tool is pressed. When this happens, the variable
the action string of the menu item (or tool) that was
menus action string is set using the ACTION attribute
string containing menu_id. For example:
until a menu item

%MENUVAL is set to
selected. The
but defaults to the
MENU 1-3 "Exit"
has a default action string of 1-1.

The sensitivity of a menu item us set using the SENSITIVE attribute. An
insensitive menu item is greyed out and can not be selected. If a menu
item that leads to a pull-down menu is insensitive, none of the items in
the pull-down menu can be accessed.
A menu item can be skipped using the MENU SKIP command. The
menu_id of the item being skipped must be given.
Text substitution is performed on the menu_label and on the values
given with the ACTION and SENSITIVE attributes, but not on the
menu_id.
Note that text substitution is performed when the MENU command is
evaluated and not when the ASKMENU command is evaluated.
295
TSL Reference
Examples
MENU 1 "File" ACTION = "File"
defines the first item on the menubar.

MENU 2-1 "@Open" \
ACTION = "Open", SENSITIVE = "not already_open"
MENU 2-2 "@Close" \
ACTION = "Close", SENSITIVE = already_open
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"
illustrates the use of text items in a menu-label.

MENU 2-1 SKIP
This instructs TSL to skip menu item 2-1.
MORE
Enables or disables paging mode

Syntax
MORE [ ON | OFF ]
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.
Initially paging mode is enabled.
297
TSL Reference
NEXT
Moves the query buffer cursor position forward by

one row
Syntax
NEXT
Description
Move forwards one row in the query buffer. If the cursor was already
positioned at the last row, it becomes invalid.
PAGESTYLE
Defines the attributes of the current pagestyle

Syntax
PAGESTYLE attributes
Arguments
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
The first line on which the main text is printed
ENDLINE
The last line on which the main text is printed
HEADLINE
The line on which to start printing the header
FOOTLINE
The line on which to start printing the footer
HEADER
The header string
FOOTER
The footer string
LENGTH
The length of a page
LMARGIN
The first column on which text is printed
RMARGIN
The last column on which text is printed. Note that the

maximum width of a report generated by TSL is 500
characters.
299
TSL Reference
The default values of these attributes are:

Attribute
Default value
STARTLINE
ENDLINE
Same as LENGTH attribute.
HEADLINE
No default.
FOOTLINE
No default.
HEADER
No default.
FOOTER
No default.
LENGTH
65 or the length set by the

last LENGTH command.
LMARGIN
4 or the default left margin

value set by the last MARGIN
command.
RMARGIN
1 or the default right margin

value set by the last MARGIN
command.
The special variable %PAGENUM which is created when a report is

enabled using the REPORT ON command can be used by the HEADER and
FOOTER attributes to print the number of the current page in the pages
header and/or footer.
Text substitution is performed on the values given with all PAGESTYLE
attributes.
Examples
PAGESTYLE HEADLINE=1, HEADER='"Status of Kings"'
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
Moves the query buffer cursor position back by one

row
Syntax
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
Prints data to the screen or printer

Syntax
PRINT [ print_arg { , print_arg } ]
PRINTLN [ print_arg { , print_arg } ]
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:
Zero or more flags, which modify the meaning of the format

specification.
303
TSL Reference
An optional minus sign, which specifies left adjustment of the data

item in the field.
An optional digit string that specifies a field width. If the converted

value has fewer characters than the field width, the value is padded
with blanks. By default, the value is padded on the left. If the left
justification flag was given, the value is padded on the right. If the
field width begins with a zero the value is padded with zeroes.
instead of blanks.
An optional decimal point which separates the field width from the
next digit string.
An optional digit string specifying a fraction length. The fraction

length controls the number of digits that appear after the decimal
point.
A character, the format character, which indicates the type of

conversion to be applied.
The flag characters and their meanings are as follows:

Character
Description
Print the value left justified.
If the value is signed and numeric,

print a sign (+ or -) before it.
The format characters and their meanings are as follows:

Character
Description
Decimal integer. The data type should be byte, short

or long. The format character u can be used for
unsigned numbers.
Octal number. The data type should be byte, short or

long.
Hexadecimal number. The data type should be byte,

short or long.
Character
Description
Print the data item as a real decimal number in the

style ###.### where the number of digits following
the decimal point is the fraction length. If the fraction
length is 0, no decimal point is produced. The data
type should be shortreal or real.
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.
Type independent. TSL determines the best method to

use for printing.
Print a percent sign.
If the data item is a complex number, the following characters can be

used:
Character
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
The abbreviated weekday name for the current local

(for example, Mon).
The full weekday name for the current locale (for

example, Monday).
305
TSL Reference
Character
Description

(for example, Jan).
The full month name for the current locale (for example, January).
Day of the month, in the format 01 to 31.
The date in the form %m/%d/%y.
Day of the month, in the format 1 to 31. Single digits

are preceded by a blank.

(for example, Jan).
Day of the year, in the format 001 to 366.
Month, in the format 01 to 12.
Minute of the hour, in the format 00 to 59.
Newline (\n) character.
The time in the form %H:%M.
Second, in the format 00 to 61.
Tab (\t) character.
Time in the form %H:%M:%S.
The weekday number, in the format 0 to 6, where 0

corresponds to Sunday.
Year, in the format 00 to 99.
Year, in the format 1995.
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
Defines the attributes of the current printer and turns

printer output on or off
Syntax
PRINTER [ ON | OFF | attributes ]
Arguments
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
printer is a file, %OUTPUT is defined as the name of that file, otherwise

%OUTPUT is defined as printer. This macro can be used in REPORT and
PLOT queries to direct the output from these components to the same
destination as the TSL output.
PRINTER on its own is equivalent to PRINTER ON.
Text substitution is performed on the values given with the FILENAME

and COMMAND attributes.
Examples
PRINTER ON
PRINTER OUTPUT=PIPE, COMMAND="wc -l"
defines the current logical printer to be a pipe. Output generated by

TSL is piped through the command "wc -l".
PRINTER OUTPUT=PRINTER, COMMAND="lp -dps"
defines the current logical printer to be a printer. Output generated by

TSL is printed using the command lp -dps
PRINTER OUTPUT=FILE, FILENAME="/tmp/apps.log"
APPEND=TRUE
defines the current logical printer to be the file /tmp/apps.log. When

this is opened for the first time by the application, TSL appends to the
end of the file.
309
TSL Reference
QUERY
Executes a TQL query

Syntax
QUERY 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 return data to the application (for example, DISPLAY,

FETCH)
Those that execute other TQL client applications (for example, RUN)
All other queries (for example, SELECT, OPEN, DROP)
Execution of a query in the third category has no effect on the query

buffer and the current cursor position is unchanged.
After execution of a category 2 query the query buffer is empty and the
current cursor position is invalid.
For category 1 queries the effect depends upon the setting of the TQL
system variable %DISPLAY. If %DISPLAY is FALSE, the query buffer is
unaffected and the current cursor position is unchanged. If %DISPLAY is
TRUE, any data returned by the query is placed in the query buffer and
the current cursor position is set to the first row in the buffer. If no data
is returned, the current cursor position is invalid.
In addition, category 1 queries set the special TQL variable %ROWS to the
number of rows placed in the query buffer by the query if %DISPLAY is
TRUE.
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 variable %QOK is set to FALSE to indicate that
an error has occurred and the special TQL variables %QERR, %DERR and
%FERR are set to the TQL query, database and filer error codes
respectively. In addition, the variables %QMSG, %DMSG and %FMSG are set
to contain the error messages generated.
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
Allows a sequence of commands to be repeated

Syntax
REPEAT [ NOTRAP ]
commands
FORALL
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.
When REPEAT UNTIL TQL_expression is used, the loop body is

executed until the expression TQL_expression evaluates to TRUE. 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.
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
NEXT
FOR 10
As above put prints at most 10 rows of data.

REPEAT
NEXT
UNTIL [exp_no] > 20
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
QUERY DISPLAY exp_no, exp_result \

FROM rsltdata WHERE batch = [batch_no] ;
'Batch Number: [batch_no]
REPEAT NOTRAP
NEXT
FORALL
SET batch_no batch_no + 1
UNTIL batch_no > 10
A DISPLAY query is performed for each batch_no from 1 to 10 inclusive

and in each case the entire results are printed. If the user aborts the
loop, the outermost loop is aborted.
REPORT
Defines the attributes of the current report or turns

reporting on
Syntax
REPORT [ ON | OFF | attributes ]
Arguments
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.
The pagestyle to use is determined as follows:
If the current page (%PAGENUM) is 1, use the value of the FIRST

attribute if it is defined, otherwise 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.
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
REPORT on its own is equivalent to REPORT ON.
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
Return from a TSL procedure before the procedures

end
Syntax
RETURN
Description
Causes TSL to return from a TSL procedure immediately (that is, before
reaching the ENDPROC command).
317
TSL Reference
SCREEN
Allows screen-at-a-time paging of output

Syntax
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
Switches input to another script file

Syntax
SCRIPT filename
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:
If the environment variable TB_TSL_SPEC_PATH is defined, each

Otherwise:
If the environment variable TB_SPEC_PATH is defined, each

directory on this path is searched in turn;
Note that only one of the two alternatives is searched. Thus if

TB_TSL_SPEC_PATH is set but the script file is not found in any of the
directories on that path, the application does not search the directories
on TB_SPEC_PATH.
If the file is not found by searching these paths or neither of the above
environment variables are defined, the file is looked for in the current
directory.
If filename is an unencrypted file, that is the file uses the suffix .tsl,
and the file is not found, the encrypted version of the file is searched
for. The name of the encrypted file can be found by removing the .tsl
suffix and adding the suffix .tse.
If filename does not use the suffixes .tsl or .tse, TSL first looks for
the file filename. If this file is not found, TSL looks for the file
filename.tsl. Finally if this file is not found, TSL looks for the file
filename.tse.
The TSL Encryption utility is described in the Utilities manual.
Script files may be nested to a maximum depth of 10 levels.
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
Displays a list selection dialog

Syntax
SELECT text_label choice_items
Arguments
text_label = quoted_string
choice_items = { quoted_string } | query_buffer_expansion
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.


been truncated.)
Text substitution is performed on both text_label and choice_items.
321
TSL Reference
Example
QUERY DISPLAY fullname FROM kings ;
SELECT "King" fullname
SELECTFILE
Displays a file selection dialog

Syntax
SELECTFILE file_label [ filter [ base_dir ] ]
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
Sets the values of TQL variables

Syntax
SET TQL_variable_name TQL_expression \
{ , TQL_variable_name TQL_expression }
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
increments the variable X.
SETBUFFER
Sets the current buffer file

Syntax
SETBUFFER buffernum
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
Sets the current canvas

Syntax
SETCANVAS [ canvas_number ] [ canvas_name ]
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
The number of graphs in the canvas.
%GRFOCUSSED
The graph with the data focus.
%GRSELECTED
The graph properties apply to.
In an application where you want to control multiple windows all with

multiple graphs in them, it is important to use these variables to avoid
graphs being destroyed when moving between canvasses. In this case,
the correct approach is to set canvas editing on with the following
command:
CANVAS MODE EDIT=ON
and set the current graph identifier after setting the canvas identifier, for
example:
SETCANVAS 2
SETGRAPH [%GRFOCUSSED]
To delete all canvasses controlled by the application use the ALL

modifier to CANVAS OFF.
Text substitution is performed on both canvas_number and
canvas_name.
Examples
SETCANVAS 1 "TestSystem"
CANVAS ON
SETCANVAS 2 "TestSytsem"
CANVAS ON
Creates two canvasses with the name TestSystem.
327
TSL Reference
SETDIALOG
Sets the current dialog

Syntax
SETDIALOG dialog_number / dialog_name
Arguments
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
sets dialog 3 as current. Subsequent commands apply to that dialog.

SETDIALOG setup_graph
sets the dialog named setup_graph as current.
SETGRAPH
Sets the current graph

Syntax
SETGRAPH graph_number
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
Sets the current pagestyle

Syntax
SETPAGESTYLE stylenum
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.
Text substitution is performed on stylenum.

Example
SETPAGESTYLE 5
SETPRINTER
Sets the current printer

Syntax
SETPRINTER printernum
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.
Text substitution is performed on printernum.

Examples
SETPRINTER 25
PRINTER output=file append=false filename="/tmp/log1"
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
Sets the current report

Syntax
SETREPORT reportnum
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.
Text substitution is performed on reportnum.

Example
SETREPORT 5
SHELL
Executes a command using the operating system

command shell
Syntax
SHELL system_command
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
Terminates the application

Syntax
STOP [ exitcode ]
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
Allows one of a number of different command

sequences to be executed depending upon the value of
a TQL expression
Syntax
SWITCH switch_expression
{
CASE case_expression
commands }
[
OTHERWISE
commands ]
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 a CASE statement is found then the associated case_expression is

evaluated and its value is compared with that of the
switch_expression. If the values are equal then the lines following
that CASE statement are processed until the next CASE, OTHERWISE
or ENDSWITCH is encountered, after which all lines up to the
ENDSWITCH are skipped.
If the values are not equal then the lines up to the next CASE,
OTHERWISE or ENDSWITCH are skipped.
If the OTHERWISE statement is reached with no matching CASE

statements having been found then the lines after the OTHERWISE up
to the ENDSWITCH are processed.
Note that if more than one case_expression matches the

switch_expression then only the commands associated with the first such
CASE are processed. If the switch_expression evaluates to NULL, no
case_expression will match it. Similarly a case_expression that evaluates
to NULL will never be matched.
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.
Note that the data type of each case_expression must be of comparable

type to that of the switch_expression. That is, the comparison
case_expression = switch_expression must itself be a valid TQL
expression.
Text substitution is performed on switch_expression and each
case_expression before it is evaluated.
Switch statements whose cases are all string literals are implemented
very efficiently by TSLthe case expression is not evaluated on the
TQL Server. For this reason a switch statement should be preferred to
an IF statement in these cases.
Examples
SWITCH %menuval
CASE "Open"
SCRIPT open.tsl
CASE "Close"
SCRIPT close.tsl
CASE "Exit"
STOP
ENDSWITCH
SWITCH range( x, 20, 40, 60 )
CASE 0
'
X < 20
CASE 1
'20 <= X < 40
CASE 2
'40 <= X < 60
OTHERWISE
'60 <= x
ENDSWITCH
TABLE
Enables or disables table mode

Syntax
TABLE [ ON | OFF ]
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.
Initially table mode is disabled.
337
TSL Reference
TELL
Outputs a prompt to the terminal window

Syntax
TELL prompt
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%;,
Text may be selected from the window to allow it to be pasted into

other windows-based applications (or even into text fields in TSL
dialogs) using the standard selection mechanism of the underlying
window system.
339
TSL Reference
Text Item
Replaces a variable by its value

Description
A text item is an expression or column name enclosed by square
bracketsfor example, [ watts ]. Text items may appear anywhere in
text output lines and at certain places in other TSL commands unless a
command is preceded by the EXPAND command. Preceding a command
with EXPAND means that text substitution may be used in any field and
argument of the command.
When a text item is encountered it is replaced by a textual
representation of the value of the enclosed expression. This procedure
is known as text substitution. The value is determined as follows:
If the item begins with the character $, it is assumed to be a UNIX

environment variable and the text item value is simply the current
value of that environment variable or an empty string if that
environment variable is not set.
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.
When a value is obtained, from the query buffer or by evaluating a TQL

expression, the field length and fraction length of the item are
determined from the TQL Server. (The TQL function FORMAT may be
used to alter these field and fraction lengths.) The value is converted to
a string representation using this field and fraction length. If the item
appears in a text output line and table mode is not enabled, the
resulting string is stripped of leading and trailing spaces before being
copied to the output. The format used for printing data of different
types is as follows:
Data type
Printing description
BYTE, SHORT, LONG
Right-justified within the field.
Data type
Printing description
SHORTREAL, REAL
Right-justified within the field. If fraction

length not specified or too long for field
width, number is printed in e-format.
BOOL
Output as one of the strings Yes, No (or

their equivalent in the users Local Language environment).
STRING, CHAR
Left-justified within the field.
TIME
Format can be configured by the user.

Default format is HH:MM:SS where HH, MM,
SS represent the hour, minute and second
components of the time respectively.
DATE
Format can be configured by the user.

Default format depends upon the Local
Language Environment. For example in the
UK the default format is dd/mm/yy where
dd, mm, yy are the day, month and year
components of the date respectively.
COMPLEX
Format can be configured by the user. By

default, output as r, i where r and i are the
real and imaginary parts respectively. Each
part is formatted as described for real numbers above.
341
TSL Reference
Text Output
Outputs text (to Screen or Printer)

Syntax
' 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
Sets the timeout duration for the ASKMENU or the

ASKDIALOG command
Syntax
TIMEOUT [ MENU | DIALOG ] [ duration ]
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 defines the timeout on the ASKDIALOG command to be

ten minutes.
TIMEOUT MENU
This command cancels the current time out period. Thus ASKMENU
commands will wait indefinitely until a menu item is selected.
343
TSL Reference
TITLE
Sets the title for the applications main window

Syntax
TITLE 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
Defines a tool groups label or a tool in a tool group

Syntax
TOOL groupnum label
TOOL toolid primary_bitmap [ active_bitmap ] attributes
Arguments
toolid = groupnum - position
groupnum, position = number
primary_bitmap = bitmap_file
active_bitmap = bitmap_file
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
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"
This defines the label of toolgroup 1 to be Kingfisher.

TOOL 1-2 "cond.tool" ACTION = "Condition"
This defines a tool which is located in position 2 of toolgroup 1 which

uses the bitmap cond.tool. When this tool is selected the string
Condition is put in %MENUVAL.
TOOLBOX
Defines the attributes of the toolbox

Syntax
TOOLBOX attributes
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
Defines the maximum number of rows 1 if GRAVITY is

in each tool group if GRAVITY is NORTH NORTH or SOUTH,
or SOUTH or the maximum number of
2 otherwise
columns in each tool group if GRAVITY
is EAST or WEST.
FRAME
Defines whether each tool group

should have a box drawn around it.
True
347
TSL Reference
Attribute
Description
Default value
GROUPGAP
Defines the distance that exists

10p (ten pixels)
between the last tool in the previous
tool group and the current tool groups
label.
TOOLGAP
Defines the distance that exists

between each tool in all of the tool
groups.
10p (ten pixels)
Examples
TOOLBOX GRAVITY = NORTH, ROWCOLS = 2
This command positions the toolbox on top of TSLs main scrollable

window and defines the maximum number of rows in each tool group
to be 2. In addition the default values for FRAME, GROUPGAP and
TOOLGAP are used.
TOOLBOX ROWCOLS = 3, FRAME = FALSE, TOOLGAP = 0i
This defines a toolbox which is positioned on the left of TSLs main

scrollable window (the default) and each tool group can contain a
maximum of three columns. The tool groups do not have frames around
them and there is no gap between the tools (0 inches).
TRANSFER
LOAD,
TRANSFER
UNLOAD
Loads a database table from a file or pipe, or unloads

a database table
Syntax
TRANSFER LOAD table file_or_pipe
TRANSFER UNLOAD table file_or_pipe
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
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.
The table specified in the command is not defined in the

currently open database or the database is not open.
349
TSL Reference
Value
Description
The specified file or UNIX pipe cannot be opened. Check

the permissions and that the file exists.
The query buffer is too small to load or unload a single row

of the specified table. Rerun TSL using the -buffersize
command-line argument to increase the buffersize.
The UNIX command specified as the pipe returned an error

code when the transfer completed. This can be because the
program or utility does not set an exit status.
An IO error occurred while reading or writing to the file or

pipe.
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
loads the table SPECTRA from the file /tmp/spectra.

TRANSFER LOAD spectra awk -f filter.awk /tmp/file
loads a table from a UNIX pipe.

TRANSFER UNLOAD setup /tmp/setup.file
unloads the SETUP table into the file /tmp/setup.file.
TRANSFER
PROPERTY
Sets or gets the values of the transfer properties

Syntax
TRANSFER PROPERTY [ SET ] property_value_list
TRANSFER PROPERTY GET property_var_list
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.
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.
names of all transfer properties, are described in Chapter 8 of the
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.
Example
TRANSFER PROPERTY delimiter=";" terminator=0
Sets the field delimiter to a semi-colon and the row terminator to a

linefeed.
351
TSL Reference
TRY, [PROGRESS],
RECOVER,
ENDTRY
Provides for the interruption of and recovery from a

long command sequence
Syntax
TRY
[PROGRESS [message]]
commands
RECOVER
commands
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.
TRY/RECOVER blocks may be nested within the TRY/RECOVER section but

not within the RECOVER/ENDTRY section.
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
Allows a sequence of commands to be repeated

Syntax
WHILE TQL_expresion
commands
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
This section describes the error reporting format used

by TSL and enumerates the error and warning messages
which may be produced.
357
Appendix
Error Messages
Error messages produced by TSL may relate to errors detected by the

TSL interpreter or to errors detected by the TQL Server during the
execution of queries.
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
#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
#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
#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
Errors
#42
#43
#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
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
#125 Dialog width is already defined

You have tried to redefine the width of a dialog. The WIDTH attribute in
a DIALOG LAYOUT command can only be defined once per dialog.
#126 Dialog height is already defined
You have tried to redefine the height of a dialog. The HEIGHT attribute
in a DIALOG LAYOUT command can only be defined once per dialog.
#127 Dialog grid is already defined
Values of attributes to DIALOG LAYOUT were already defined.
#128 Expected True or False
You did not supply TRUE or FALSE for an attribute that takes a boolean
value.
#129 Dialog mode (<mode>) is out of range 0 to 5
TSL expected a value in the range 0 to 5, instead it found <mode>.
#130 Licence options do not allow execution of this file
Your licence restricts you to using encrypted TSL scripts. If you have a
licence entitling you to use unencrypted TSL scripts, contact your
distributor to obtain a new security code.
#131 X-Origin should have value LEFT, CENTRE or RIGHT
You supplied an invalid value for the XORIGIN attribute of a dialog.
#132 Y-Origin should have value TOP, CENTRE or BOTTOM
You supplied an invalid value for the YORIGIN attribute of a dialog.
#133 Area should have been a value of 0 or 1
You must specify a value of 0 or 1 only when defining the AREA
attribute in a DIALOG BUTTON command
#134 Default button has already been defined
Another button in the current dialog has already being designated as
the default button.
#135 Expected a number
TSL was expecting a number but one was not supplied.
#136 Did not recognise unit
Only grid g, centimetre c, millimetre m, inches i, pixels p and
characters l are accepted as dimension units.
#137 A dialogs width should be larger than 0
This error message is not used in the current version of Metrica/NPR.
Errors
#138
A dialogs width should be smaller than the width of the

screen
#139 A dialogs height should be larger than 0
#140
A dialogs height should be smaller than the height of the

screen
#141 Grid units not allowed
Only the XPOS, YPOS, XADJUST and YADJUST attributes of dialog items in
the main dialog area recognise grid units.
#142 Expected either a X or a x
The grid size consists of two numbers separated by an X or an x
character.
#143 Encountered an unknown dialog attribute
The type of dialog specified in a DIALOG command is invalid.
#144 DIALOG attribute was redefined (<attribute>)
The attribute <attribute> that was already defined for a dialog item has
been redefined.
#145 Invalid attribute for dialog items of this type (<attribute>)
This dialog item doesnt use the attribute <attribute>- refer to the
description of the dialog item to see which attributes are allowed.
#146 The size of the LABELGAP should be greater than 0
#147 Setting too many Kingfisher displays
The SETCANVAS command takes an argument in the range 130.
#148 Expected either ON or OFF
You did not specify either ON or OFF in a JUSTIFY or ABORT command.
#149 Expected either EXCEPT or ONLY
You can only specify the keyword EXCEPT or ONLY in an ABORT ON
command.
#150 An error code should begin with a Q, D or F
The list of errors was badly specified. Query errors must be prefixed by
a Q or a q, database errors by a D or a d and filer errors by a F or
a f.
371
Appendix
Error Messages
#151 PRINTER ON or PRINTER OFF of undefined printer

The details of the current printer has not been defined.
#152 Bad number printer
The SETPRINTER command takes an argument in the range 130.
#153 Expected a PRINTER attribute
Valid attributes are OUTPUT, COMMAND, FILENAME and APPEND.
#154 COMMAND attribute already defined
You have tried to redefine an attribute of a PRINTER command. The
COMMAND attribute in a PRINTER command can only be defined once.
#155 OUTPUT attribute already defined
You have tried to redefine an attribute of a PRINTER command. The
OUTPUT attribute in a PRINTER command can only be defined once
#156 FILENAME attribute already defined
You have tried to redefine an attribute of a BUFFER or PRINTER
command. The FILENAME attribute in a BUFFER or PRINTER command
can only be defined once.
#157 APPEND attribute already defined
This attribute has already been defined for the current printer.
#158 Printer output should be FILE, PIPE or PRINTER
The value given for the OUTPUT attribute must be one of FILE, PIPE or
PRINTER.
#159 Missing value for attribute in PRINTER
Expected a value to follow the equals.
#160 Nothing should follow PRINTER ON/OFF commands
You cannot specify attribute = value pairs in a PRINTER ON or PRINTER
OFF command.
#161 Filename not defined
A value for the FILENAME attribute should be defined if the OUTPUT
attribute is defined as FILE.
#162 Printer/Pipe command not defined
A value for the COMMAND attribute should be defined if the OUTPUT
attribute is defined as PRINTER or PIPE.
#163 Bad number report
The SETREPORT command takes a value in the range 130.
Errors
#164 The first pagestyle has already been defined

You have tried to redefine an attribute of a REPORT command. The
FIRST attribute in a REPORT command can only be defined once.
#165 The left pagestyle has already been defined
You have tried to redefine an attribute of a REPORT command. The LEFT
attribute in a REPORT command can only be defined once.
#166 The right pagestyle has already been defined
You have tried to redefine an attribute of a REPORT command. The
RIGHT attribute in a REPORT command can only be defined once.
#167 The default pagestyle has already been defined
Redefinition of an attribute in REPORT command.
#168 Expected a REPORT attribute
Valid attributes are FIRST, LEFT, RIGHT and DEFAULT.
#169 Bad number pagestyle
The SETPAGESTYLE command takes a value in the range 130.
#170 Unknown attribute in PAGESTYLE
Valid attributes are STARTLINE, ENDLINE, LENGTH, LMARGIN, RMARGIN,
HEADLINE, HEADER, FOOTLINE and FOOTER.
#171 PAGESTYLE attribute already defined
Redefinition of an attribute in PAGESTYLE command.
#172 Missing value for attribute in PAGESTYLE
Expected a value to follow the equals.
#173 LABELGAP defined for non-labelled BUTTON
Only labelled-iconic buttons in the main dialog area are allowed to use
the LABELGAP attribute.
#174 This list operation requires a position
The INSERT, DELETE and REPLACE list editing commands need to be
given a position.
#175 List operation, INSERT etc., used as column name
TSL expected to read in a column name or a list of quoted string values
in a DIALOG LIST command but found a reserved list command
keyword.
#176 Expected a list of values
TSL expected to read in a list of quoted string values in a DIALOG LIST
command but none were given.
373
Appendix
Error Messages
#177 No filename supplied with SCRIPT command

The SCRIPT command must be followed by the name of a valid TSL
script file to execute.
#178 Dialog BUSYONAPPLY attribute is already defined
You have tried to redefine the BUSYONAPPLY attribute of a dialog and
this attribute can only be defined once in a DIALOGLAYOUT command.
#179
Button/dialog item sensitivity evaluates to NULL
#180
Dialog item READONLY attribute evaluates to NULL
#181
Dialog item range attributes evaluate to NULL
#182 Dialog item ALLOWNULL attribute evaluates to NULL

Error messages #179#182 refer to incorrect settings for dialog item
attributes and are displayed when a dialog item cannot be evaluated
correctly on the server. The expression used to set the attribute is
incorrect.
#183
Caught SIGSEGV signal
#184 Caught SIGBUS signal

Error messages #183 and #184 indicate that an illegal operation was
carried out that caused TSL to terminate unexpectedly. Consult your
System Administrator.
#185
No filename supplied with CANVAS COLOURMAP

command
You have tried to control the colourmap of the Kingfisher display
canvas without supplying the name of the file that holds the colourmap.
#186 No filename supplied with CANVAS CONFIG command
You have tried to control the configuration of the Kingfisher display
canvas without supplying the name of the file that holds the
configuration.
#187 Dialog BUTTONLAYOUT attribute is already defined
You have tried to redefine the BUTTONLAYOUT attribute of a dialog. This
attribute can only be defined once in a DIALOG LAYOUT command.
#188 Expected DIALOGCENTRE or COLUMNCENTRE
You have tried to define the BUTTONLAYOUT attribute of a dialog but
have specified an unknown option for the attribute.
#189
Errors
#190
This error number is not relevant to the current version of Metrica/NPR.
#191
#192
#193
#194
#195 Data provided is invalid
The data provided is not valid for the operation requested.
#196
#197
#198
#199
#200
#201
#202
List Selection Policy must be SINGLE, BROWSE, MULTIPLE,

RANGE or DISCONTIGUOUS only
An unrecognised list selection policy has been specified on a DIALOG
LIST command.
#203 Badly formed or nested TRY
A RECOVER or ENDTRY was encountered with no matching TRY, or the
end of the script file was reached with a TRY command still
unterminated.
375
Appendix
Error Messages
#204 Progress command must be within TRY-ENDTRY block

The PROGRESS command can only be used within a TRY-ENDTRY block.
#205 Dialog identifier expected in SETDIALOG command
The SETDIALOG command must specify a dialog number or name to be
treated as the current dialog.
#206 The buffer number is invalid
TSL allows a maximum of 30 logical buffers to be defined. A SETBUFFER
command has specified a buffer outside the range 130
#207 The buffer specified has not been defined
You have specified a BUFFER ON for a buffer whose filename and
append details have not been defined.
#208 Unrecognised attribute used in BUFFER command
An invalid attribute has been specified for a BUFFER command. The
FILENAME and APPEND attributes are valid for this command.
#209 Missing value for attribute in BUFFER command
A valid attribute has been specified for a BUFFER command but no value
has been given.
#210: Nothing should follow BUFFER ON/OFF commands
A BUFFER ON or BUFFER OFF command must appear on its own line.
This error indicates that other commands, attributes or keywords appear
on the same command line.
#211 Error initialising licence
An error has occurred during the initialisation of the licence.
#212 Unable to contact FLEXlm server
An error has occurred while trying to contact the licence server. Check
that the licence server is running and the LM_LICENSE_FILE
environment variable has been correctly set.
#213 Error, check licence server
An error has occured while querying information from the licence
server.
#214
Error, network size violation. Check that all NSM's are

running
One or more Network Size Monitor (NSM) daemons are not running.
Ensure that the NSM daemon has been started.
Warnings
#215 Unable to obtain licence to run

A licence could not be obtained from the specified licence server.
#216 All licences are currently in use
You have reached the maximum number of concurrent users that the
system is licenced to use.
#217 Error, licence not authorised to proceed
An operation is being carried out which cannot be sanctioned by the
current licence.
#218 Licence violation has occurred
You have lost your licence. Check that the licence server is still running.
#219 Bad licence information
Internal licence error.
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
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
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
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
Reference manual.
Warnings
Unknown table in TRANSFER command

command indicated that the table specified did not exist. TSL will not
terminate, but the TRANSFER command may not have been successful.
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 convenience dialogs 4446
and DIALOG OPTION command 251
%DIALOGVAL variable (continued)

and sliders 56
%DISPLAY system variable 310
%DLOGCHANGED variable
and calendars 231
and printing reports 114
and timerange bars 263
purpose of 47
%DMSG variable 272
and GRAPH DRAW errors 135
and QUERY command 310
database level message 158
error messages 364
%FERR variable 272, 310
error messages 364
file level error code 157
%FILEVAL variable
and file selection dialog 45
%FMSG variable
and GRAPH DRAW command 135, 272
error messages 364
filer level message 158
%GRFOCUSSED variable 147
%GRSELECTED variable 147
381
Index
%GRSTATUS variable 272

and CANVAS COLOURMAP command 211
and CANVAS CONFIG command 213
and GRAPH FORMAT command 274
and KFPROC command 289
command errors 135, 143
command errrors 130
procedure errors 126
%LISTOK variable
and APPEND command 83
and INSERT, DELETE, REPLACE commands 81
%LISTPOS variable, description of 61, 242
%MENUVAL variable 295
and ACTION attribute 19
and ASKMENU command 205
and TOOL command 345346
using in menu systems 2630
using with SWITCH command 3435
%NOWINDOW variable, description of 169
%NUM_GRAPHS variable, description of 147
%NUMSELECTED variable, description of 60,
242
%OUTPUT macro 308
%PAGENUM variable
and PAGESTYLE command 300
and REPORT command 315
%QERR variable
and query errors 157
description of 157
error messages 364
%QMSG variable
description of 158
error handling 158
%QMSG variable (continued)

error messages 364
%QOK variable 272
and abort mode 156
error handling 156
%ROWS variable
number of rows in query buffer 90
%SELECTED system variable 60, 242
%SELECTVAL variable
and list selection dialog 44
%STAT variable 333
%STOPPED
and progress dialog 41
%XFDISCARD variable 155, 350
%XFROWS variable 155, 350
%XFSTATUS variable 155, 349
%XVAL variable
and GRAPH CURSOR command 271
stores cursors X value 140142
%YVAL variable
stores cursors Y value 140142
%ZVAL variable
stores cursors Z value 140
@, and highlighting text 282, 299
\, and escape 14
, using in text lines 8
A
ABORT command
and GRAPH DRAW query errors 272
and QUERY errors 310
description of 189190
enabling/disabling abort mode 156158
ABORT command (continued)

terminate script on GRAPH DRAW errors
135
accelerator
defining 30
ACTION attribute
and %BUTTONVAL 203
and menus 295
and tools 345
description of 19
error messages 365, 366, 367
in dialogs 56
in menus and toolboxes 26
with toggles 57
action string 26
ADJUST command 191
ALIGNCOLUMNS attribute
description of 68
set in application defaults file 163, 195
set with DIALOG LAYOUT command 236
ALIGNITEMS attribute
description of 68
ALIGNROWS 163
ALIGNROWS attribute
description of 68
ALLOWNULL attribute
and DIALOG MULTITEXT command 248
and DIALOG TEXT command 261
check for NULL values in text fields 180
range checking in text fields 5355
ALLOWNULL attribute (continued)

syntax conventions 188
when evaluated 19
and PRINTER command 308
APPEND attribute
and PRINTER command 111, 308
error messages 372
APPEND command
appends items to a list 245
description of 83
error messages 369
list editing 81
application 75
application defined button area 38
application defined buttons
action of in dialogs 39, 46
changing control buttons 75
description of 6364
application resources 161167, 192
changing 166
dates and times 198
dialog appearance 194
fonts 192
miscellaneous 200
printing 199
terminal window 194
toolbox appearance 196
xfontsel 193
XFontSets 192
applications, building 33
AREA attribute
placing application defined buttons 63
ASK command 201
ASKDIALOG command 56
activating the current dialog 4648
383
Index
ASKDIALOG command (continued)

and TIMEOUT command 158, 343
attributes always evaluated when called
19
error messages 362, 369
managing multiple dialogs 79
ASKMENU command
activating a menu and toolbox 2628
and MENU command 295
and TIMEOUT command 158, 343
and tool activation 345
attributes always evaluated when called
19
description of 205
error messages 360
in example script 34
skipping menu items 32
attributes 163
ACTION 19, 26, 56, 57, 63, 203, 230, 240,
251, 254, 258, 264, 295, 345, 365,
367
ALIGNCOLUMNS 68, 163, 195, 236
ALIGNITEMS 68, 163, 195, 236
ALIGNROWS 68, 195, 236
ALLOWNULL 19, 5355, 180, 188, 202,
248, 261, 368, 369
APPEND 111, 308, 372
AREA 63, 230
BUSYONAPPLY 76, 164, 196, 236
BUTTONCOLUMNS 68, 164, 195, 230, 235
BUTTONLAYOUT 68, 164, 196, 236
COLUMNS 68, 163, 195, 235
COMMAND 111, 308, 372
DEFAULT 109, 315, 373
ENDLINE 108110, 299, 373
FILENAME 111, 308, 372
FIRST 109, 315, 373
FOOTER 108110, 299, 315, 373
FOOTLINE 108, 110, 299, 373

FRAME 32, 164, 196, 347, 367
GRAVITY 32, 164, 165, 196, 347, 367
GRID 71, 237
GROUPGAP 32, 164, 196, 347348, 367
HEADER 108110, 299, 315, 373
HEADLINE 108110, 299, 373
HEIGHT 70, 237
LABELGAP 71, 74, 230, 234, 373
LEFT 109, 315, 373
LENGTH 108, 109, 110, 299300, 373
LMARGIN 108109, 299300, 373
MAXLEN 55, 248
MAXWIDTH 59, 181, 241
MINWIDTH 59, 181, 241
MODE 74, 164, 195, 236
NULL_ERR_MSG 53, 248, 261
OUTPUT 111, 308, 372
RANGE_ERR_MSG 53, 261
RANGEMAX 19, 5254, 261, 368
RANGEMIN 19, 5254, 202, 261, 368
READONLY 19, 180, 188, 248, 260, 368
RIGHT 109, 315, 373
RMARGIN 108109, 299300, 373
ROWCOLS 32, 165, 196, 347, 367
SCROLLMODE 59, 181, 241, 245
SECRET 55, 261
SELECTION_DELIM 60, 242
SELECTION_MAXITEMS 60, 242
SELECTION_POLICY 241
SENSITIVE 19, 27, 55, 57, 59, 63, 86, 175,
176, 179, 188, 205, 230, 233, 240,
248, 251, 254, 264, 295, 345, 365,
367, 368
STARTLINE 108110, 299, 373
TOOLGAP 32, 164, 196, 347348, 367
WIDTH 70, 237
XADJUST 71, 73, 371
XORIGIN 7173
XPOS 7173, 371
YADJUST 71, 73, 371
YORIGIN 7173
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
BUTTONCOLUMNS attribute
description of 68
set with DIALOG BUTTON command 230
BUTTONLAYOUT attribute
description of 68
buttons
application defined 76
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
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
destroy a canvas 124
CANVAS ON command
and error conditions 127, 135
and GRAPH FORMAT command 275
and GRAPH POSITION command 276
and GRAPH PROPERTY command 278
and KFPROC command 290
creating a canvas 122125
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
CANVAS REFRESH command

description of 210
refreshing the current canvas 130
CANVAS RESIZE command
description of 220
resizing the current canvas 130
CANVAS SNAPSHOT command
capture the current canvas 131
description of 210
cascading menu, defined 24
CASE command
error messages 362
in SWITCH construct 35
changing application resources 166
CLEAR command, description of 221
CLEAR list editing command 81
and APPEND command 83
error messages 369
clearing the display window 130
CLOSEDIALOG command
closing a dialog 76
description of 222
colourmap
loading 142
shared colourmap directory 211
users private colourmap directory 211
columns
changing dialog default layout 68
COLUMNS attribute
description of 68
COMMAND attribute
defines printing command 308
error messages 372
commands
ABORT 135, 156158, 189190, 272, 310
ADJUST 191
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
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
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
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
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
changing a lists contents 82
dialog appearance
set with application resources 194
DIALOG BUTTON command
application defined buttons 6364
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
DIALOG command (continued)

dialog item types 4964
error messages 367
DIALOG HSLIDER command 56
DIALOG LABEL command
description of 233
labelling dialog items 62
DIALOG LAYOUT command
ALIGNCOLUMNS attribute 68, 163, 195,
236
ALIGNITEMS attribute 68, 163, 195, 236
ALIGNROWS attribute 68, 163, 195, 236
BUSYONAPPLY attribute 76, 164, 196, 236
BUTTONCOLUMNS attribute 68, 164, 195,
230, 235
BUTTONLAYOUT attribute 68, 164, 196,
236
COLUMNS attribute 68, 163, 195, 235
defining dialog layout 6874
error message 362
GRID attribute 71, 237
HEIGHT attribute 70, 237
MODE attribute 164, 195, 236
set attributes in application defaults file
163164, 195196
WIDTH attribute 70, 237
DIALOG LIST command
defining dialog list items 5759
list selection policy 60
DIALOG MULTITEXT command
defining multiline text fields 55
DIALOG OPTION command
defining option items 5759
DIALOG OPTION command (continued)

DIALOG PANEL command
defining panel items 5759
DIALOG SKIP command
description of 256
skip position in allocating items 70
DIALOG SLIDER command
defining sliders 56
DIALOG TEXT command
creating text fields 5255
DIALOG TIMERANGE command 262
defining time ranges 61
DIALOG TOGGLE command
creating toggle buttons 56
description of 264
DIALOG VSLIDER command
creating sliders 56
dialogs grid 70
dialogs
active dialog item 56
and data types 49
changing layout 68
closing from TSL 76
closing with window manager 75
confirmation dialogs 42
creating 46
creating sliders 56
default button 64, 75
dialog action 39
error dialogs 39, 40
exclusive panels 57
file selection dialog 45
information dialogs 40
list selection dialog 43
multiline text field 55
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
error messages 360
example usage 29
with IFOK command 286
ELSE command
error messages 360
example usage 29
with IFOK command 286
Encrypted TSL 4, 319
ENDIF command
error messages 360
ENDIF command (continued)

example usage 29
ENDLINE attribute
define page style 108110
error messages 373
ENDLOOP command
description of 355
error messages 359
ENDPROC command
and RETURN command 317
defining procedures 912
description of 226
ENDSWITCH command
error messages 362
ENDTRY command 352
environment variables
KF_COLOURMAP_PATH 142, 211
KF_EXEC_TIMEOUT 123
KF_FORMAT_PATH 134135, 274
KF_PROC_PATH 126127, 289
PATH 3
TB_SPEC_PATH 18, 280, 319, 359, 360
TB_TSL_SPEC_PATH 3, 18, 280, 319, 359,
360
TERM 333
TQL_CLIENT_DIR 23
TSL_13_COMPATIBILITY 321
TSL_HELP_DEFAULTPAGE 18, 281
TSL_HELP_EDITOR 18, 39, 281
XBMLANGPATH 20, 229, 233, 345, 366
ERROR command
create error dialog 40
description of 267
error dialog 40
error messages, list of 359
errors
and executing CANVAS COLOURMAP
commands 143
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
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
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
error messages 373
page style attribute 108110
FOOTLINE attribute
error messages 373
page style attribute 108, 110
FOR command
error messages 359
example usage 91
FORALL command
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
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 GRAPH POSITION 276
creating a graph 132137
error messages 363
multiple graphs 143
GRAPH FORMAT command
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
GRAPH POSITION command (continued)

position a graph 133
GRAPH PROPERTY command
error messages 364
setting graph properties 138140
GRAPH SAVE command 135
graphics cursor 140
graphs
creating 132, 143
creating with Kingfisher procedures 149
loading graph formats 132
printing 129
specifying position and size 132
GRAVITY attribute
define toolbox position 32
error messages 367
set with TOOLBOX command 347
GRID attribute
define grid size 71
grid units
change number of in grid 70
GROUPGAP attribute 32
error messages 367
set with TOOLBOX command 347348
H
hardcopy configuration 130
hardcopy, see printing 129
HEADER attribute
and %PAGENUM attribute 315
error messages 373
pagestyle attribute 108110
HEADLINE attribute
error messages 373
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
error messages 360
example usage 29
IFOK command
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
J
JUSTIFY command
description of 288
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
calling a Kingfisher procedure 125126
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 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
LEFT attribute 315
define report layout 109
error messages 373
LENGTH attribute
LENGTH attribute (continued)

description of 109
error messages 373
LENGTH command
and PRINT command 303
defining the default page length 106
description of 292
example usage 119
list editing commands
APPEND 81, 83, 369
CLEAR 81, 8384, 369
DELETE 81, 82, 369, 373
DIALOG LIST command 244246
INSERT 8182, 369, 373
REPLACE 81, 83, 369, 373
list selection dialog 43
LMARGIN attribute
changing pagestyle with 108109
error messages 373
loading a colourmap 142
loading/unloading data, see transferring data
154
Local Language Support
displaying months and days 166
Look and Feel, defined 5
loops
repeat until 27
while endloop 28
M
macros
%BUFFERED 208
%OUTPUT 308
see also Kingfisher procedures 125
main dialog area 38
393
Index
MARGIN command
and LMARGIN/RMARGIN attributes 300
controlling page layout 106
description of 293
sets value of RMARGIN attribute 109
MAXLEN attribute
maximum string length for multiline text
55
MAXWIDTH attribute
and list editing commands 181
in lists 59
MENU command
defining a menu system 2532
example usage 34
menu hierarchy, defined 24
MENU SKIP command
skipping menu items 32
menus 24
creating a menu system 24
creating a multi-level menu system 28
MINWIDTH attribute
and list editing commands 181
in lists 59
mnemonics
defining 30
MODE attribute 74
and DIALOG LAYOUT command 236
MORE command
controlling the More prompt 159160
description of 297
--More-- prompt 159
multiline text fields
defining 55
N
NEXT command
description of 298
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
define error message for NULL values 53
O
option menu
creating 57
description of 50
DIALOG OPTION command 250
OTHERWISE command
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
PAGESTYLE command (continued)

FOOTER attribute 108110, 299, 315, 373
FOOTLINE attribute 108, 110, 299, 373
formatting reports 96
HEADER attribute 108110, 299, 315, 373
HEADLINE attribute 108110, 299, 373
LENGTH attribute 109, 110, 299300, 373
LMARGIN attribute 108109, 299300, 373
RMARGIN attribute 108109, 299300
STARTLINE attribute 108110, 299, 373
PATH environment variable 3
PCL hardcopy format, supported by Kingfisher
129
performance
improving 15
multiple queries 15
plotting overlays 137
positioning dialog items 70
PostScript hardcopy format, supported by
Kingfisher 129
predefined dialogs 3946
presetting dialog items 6467
presetting list dialog items 66
PREV command
description of 302
PRINT command
print text in paragraph format 269
printing data in reports 101105
print spool
specifying with application resources 163
PRINTER command
and SETPRINTER command 331
APPEND attribute 111, 308, 372
COMMAND attribute 111, 308, 372
error messages 372
FILENAME attribute 111, 308, 372
OUTPUT attribute 111, 308, 372
printing reports 110119
printer enhancements 99, 105

PRINTER OFF command
description of 308
example usage 118
print to screen 111
PRINTER ON command
description of 308
error messages 359
example usage 117, 118
printing reports 111
printing
application resources 199
display window 129
format characters 103, 304
graphs 129
loading configuration 130
on-screen reports 96
printer formats 129
reports to printer 111
set page orientation 163
setting margins and borders 129
PRINTLN command
and formatting reports 96
print text in paragraph format 269
printing data in reports 101105
PROC command
description of 290
same as KFPROC command 125
procedures
Kingfisher 125129, 289290
TSL 912, 209, 226, 317
PROGRESS command
displaying a progress dialog 41
properties
and graph formats 137
and printing 129
Q
query buffer, defined 90
QUERY command
and IFOK command 286
395
Index
QUERY command (continued)

and TSL errors 358
R
raising the display window 131
RANGE_ERR_MSG attribute 53, 261
RANGEMAX attribute 368
error messages 368
restricting acceptable values 5254
when evaluated 19
RANGEMIN attribute
error messages 368
restricting acceptable values 5254
when evaluated 19
READ command
adds items to a list 245
READONLY attribute
error messages 368
style guidelines 180
when evaluated 19
RECOVER command 352
refreshing the display window 130
REPEAT command
defining a loop 27
traversing the query buffer 91
REPLACE list editing command 373
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
LEFT attribute 109, 315, 373
RIGHT attribute 109, 315, 373
REPORT OFF command
description of 315
example usage 118
REPORT ON command
creates %PAGENUM variable 300
description of 315
example usage 117
reports
formatting for screen 99
printing from a buffer file 114
printing to printer 111
printing to screen 96
retrieving data 90
RETURN command 317
RIGHT attribute
defining pagestyles 109
error messages 373
RMARGIN attribute
defining a pagestyle 108109
error messages 373
ROWCOLS attribute 165, 347
and toolbox definition 32
error messages 367
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
setting for lists 59
style guidelines 181
searching, see finding 14
SECRET attribute
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 LABEL command 233
SENSITIVE attribute (continued)

and MENU command 295
and option, menu, list and panel items 59
and TOOL command 345
description of 19
making menu and tool items unavailable
27
setting a buttons sensitivity 63
setting a calendars sensitivity 61
setting a sliders sensitivity 56
setting a text fields sensitivity 55
setting a time range bars sensitivity 62
setting a toggle buttons sensitivity 57
setting in a dialog 86
style guidelines for dialog items 179
style guidelines for menus 175
style guidelines for tools 176
SET command
description of 324
setting a variables value 9
SETBUFFER command 325
error messages 376
SETCANVAS command
description of 326
error messages 371
managing multiple windows with 146
SETDIALOG command
description of 328
managing multiple dialog with 79
SETGRAPH command
creating multiple graphs with 143146
description of 329
error messages 364
SETPAGESTYLE command
changing the current pagestyle 108
description of 330
error messages 373
example usage 117
SETPRINTER command
defining the current printer 110
397
Index
SETPRINTER command (continued)

description of 331
error messages 372
example usage 117
SETREPORT command
description of 332
error messages 372
example usage 117
setting the current report 110
setting
fonts 161
number of columns in display window
162
number of rows in display window 162
print spool 163
SHELL command
description of 333
error messages 359
sliders 49
creating 56
description of 49
DIALOG SLIDER command 257
vertical orientation 56
special variables
and % character 9
standard control buttons
changing 74
list of 38
STARTLINE attribute
defining a pagestyle 108110
error messages 373
STOP command 334
SWITCH command
improving applications performance with
15
using in a menu system 3435
T
TABLE command
controlling text item expansion 9698
description of 337
example usage 100
tables
loading and unloading 154
TB_SPEC_PATH environment variable
path for help files 18, 280
path for script files 319
TB_TSL_SPEC_PATH environment variable
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
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
text substitution (continued)

expanding complex numbers 13
expanding dates 13
expanding strings 13
expanding times 13
expanding TSL commands 14
text, cutting and pasting TSL scripts 160
time range bars
description of 61
DIALOG TIMERANGE command 262
TIMEOUT command
defining timeout period 158
description of 343
times
entering time ranges in an application 61
printing 104
TITLE command
changing window titles 18
description of 344
toggle buttons 56
creating 56
description of 50
DIALOG TOGGLE command 264
TOOL command
defining a tool groups label 26
tool groups 25
toolbox appearance
setting with application resources 196
TOOLBOX command
attributes in application defaults file 164,
196
creating a toolbox 32
example usage 34
FRAME attribute 32, 164, 196, 347, 367
GRAVITY attribute 32, 164, 165, 196, 347,
367
GROUPGAP attribute 32, 164, 196, 347
348, 367
TOOLBOX command (continued)

ROWCOLS attribute 32, 165, 196, 347, 367
TOOLGAP attribute 32, 164, 196, 347348
toolbox, description of 25
TOOLGAP attribute
error messages 367
set distance between tools 32
TQL_CLIENT_DIR environment variable 23
TRANSFER LOAD command
loading data into a table 154
TRANSFER PROPERTY command
defining details of a data transfer 154
description of 351
error messages 364
TRANSFER UNLOAD command
unloading data from a table 155
transferring data 154
and default property values 155
and error messages 155
TRY command 352
tsl
command 167
command line options 167
TSL procedures
arguments 11
calling 10, 209
defining 912, 226
naming 10
parameters 10
parameters, passed-by-reference 10
parameters, passed-by-value 10
parameters, VAR keyword 11, 226
return from before end 317
TSL, defined 2
TSL_HELP_DEFAULTPAGE environment variable
path for the default help files 18, 281
399
Index
TSL_HELP_EDITOR environment variable

path for the external editor 18, 281
replacing defult help dialogs 39
tslcrypt utility, encrypting TSL scripts 4
U
UNTIL command
defining a loop 27
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
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
positioning dialog items 71
setting a dialog items offset from default
73
XBMLANGPATH environment variable
error messages 366
path for bitmaps 20, 233, 345
xfontsel
XFontSets
XORIGIN attribute
defining a dialog items position 7173
XPOS attribute
error messages 371
xrdb and changing application resources 166
Y
YADJUST attribute
error messages 371
setting a dialog items offset from default
73
YORIGIN attribute
YPOS attribute 7173
error messages 371
401
Index
TSL Guide & Reference

TSL

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

TSL

Uploaded by

Copyright:

Available Formats

TSL Guide &

1994-2001 ADC Software Systems UK

Manual reference: DEV/MAN/1998/096

All other trademarks are trademarks of their respective companies.

About this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

PART 1 :TSL Guide

Menus & Toolboxes

The menu system and toolbox

Skipping menu items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

ii TSL Guide & Reference

The Query Buffer

Navigating the query buffer . . . . . . . . . . . . . . . . . . . . . . . . . 90

Loading and unloading tables . . . . . . . . . . . . . . . .

iv TSL Guide & Reference

TSL Style Guide

PART 2 :TSL Reference

TSL is an applications Scripting Language for building applications

About this guide

Part 1: TSL Guide

The guide provides an introduction to TSL concepts. It then describes

Part 2: TSL Reference

The reference describes each TSL command in a standard reference

Using this guide

In this introduction, we explain what TSL is. We show

Running the examples in this guide

2 TSL Guide & Reference

Running the examples in this guide

If you are using the C shell, use the syntax:

(substituting, of course, the directory in which you have installed the

If you are using the C shell, use the syntax:

If you are using the C shell, use the syntax:

Encrypted and normal TSL

4 TSL Guide & Reference

Checking the syntax of TSL scripts

Checking the syntax of TSL scripts

The Look and FeelMotif

In this chapter, we introduce the basic components of a

8 TSL Guide & Reference

These commands allow you to declare and set multiple variables in a

The keyword defproc must be followed by the name of the procedure.

letters or numbers. For example q2 is a valid procedure name but 2q is

where procname is the name of a previously defined TSL procedure

10 TSL Guide & Reference

Here a procedure is defined which is called factorial and has one

defines a procedure proc2 which is has four parameters where x, y and

12 TSL Guide & Reference

In this example, [A] is a text item. The value of A will be determined,

This line is then output as normal.

If the item begins with the character $, it is assumed to be a UNIX

Otherwise, the item is assumed to be a column name and is looked

If the item is neither of the above, it is assumed to be a TQL

When a text item occurs in a command it is replaced by the value which

Dates, times and complex values must be enclosed by escaped square

Text substitution cannot be performed on items of type blob (binary

to escape a square bracket or any other character to make sure it is not

For some TSL commands, text substitution is performed only on

where procvar is a variable that holds the name of a TSL procedure to

Printing data items in a report

Modifying query commands based on data in the application

14 TSL Guide & Reference

TSL and TQLwho does what?

Substituting all or part of a command with the value held in a

This guide gives examples of all these techniques.