You are on page 1of 414

Updates, limitations, and known problems Publication and product document updates, limitations, and known problems are

documented in the form of individual technotes in the Support knowledge base. These are available at the Network Performance Reporting Support web site. As updates and problems are identified and resolved, the IBM Support team updates the knowledge base. By searching the knowledge base, you can quickly find workarounds, solutions to problems, and updates for the product documentation.

TSL Guide & Reference

Document Version Information Document Release Date: May 2007 Document Version: 1.0 Product: TSL Guide and Reference Product Release Version: 3.5 Important Notice The information in this publication is subject to change without notice. Vallent 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 Vallent 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 Vallent Software Systems UK. VALLENT 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 Computer-Restricted Rights clause at FAR 52.227-19, and in similar clauses in the NASA FAR supplement, where applicable. Motif is a trademark of the Open Software Foundation, Inc. UNIX and OSF are registered trademarks of The Open Group. Acrobat and PostScript are trademarks of Adobe Systems Incorporated X Window System and X11 are trademarks of the Massachusetts Institute of Technology HP-UX and HP-GL are registered trademarks of Hewlett-Packard Company Sun-4, NFS and SPARCStation are trademarks of Sun Microsystems, Inc. Windows is a registered trademark of Microsoft Corporation in the United States and other countries All 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 1
2 2 4 5 5 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Embedded TQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Text lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Text items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 TSL and TQLwho does what? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 The main window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 The Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 TSL and Window managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Dimension Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 3

Menus & Toolboxes

23
24 27 28 30

The menu system and toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A simple menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A multi-level menu system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mnemonics and Accelerators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contents

Skipping menu items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 The Toolbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 A menu system and toolbox in a real application . . . . . . . . . . . . . . . . . 33

Chapter 4

Dialogs

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

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

Chapter 5

The Query Buffer

89

Navigating the query buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 The query buffer and variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Chapter 6

Reports

95

Formatted reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Text expansion in reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 The PRINT and PRINTLN commands . . . . . . . . . . . . . . . . . . . . . . . 101 Format string syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Simple page control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Free format reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Defining reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Pagestyles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Printing reports to a file or a printer . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Printing reports: example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Chapter 7

Graphics

121
122 122 124 125 126 126 126 127 129 129 130 130 130 131 132 132 133 133 134 134
iii

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

135 135 135 136 137 137 139 140 141 142 143 143 144 146 147 149 149 150

Chapter 8

Miscellaneous Topics

153
154 155 155 156 158 159 160 161 161 162 163 163 164 165 166 166 167

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

Chapter 9

TSL Style Guide

173
174 174 175 175 175 175 176 176 177 177 178 178 178 178 179 180 182

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

PART 2 :TSL Reference


TSL Reference Appendix A Error Messages
TQL Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TSL Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

185 357
358 358 359 359 377

Index

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.

Running the examples in this guide


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:

TSL Guide & Reference

Running the examples in this guide

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 If you are using the C shell, use the syntax: 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

If you are using the C shell, use the syntax: 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.

TSL Guide & Reference

Checking the syntax of TSL scripts

Checking the syntax of TSL scripts


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

TSL Guide & Reference

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. Do not define variables that start with %. Note that the name of the variable is case insensitive.

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.

10

TSL Guide & 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]

12

TSL Guide & Reference

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. 2. 3. If the item begins with the character $, it is assumed to be a UNIX environment variable. 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. 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

14

TSL Guide & Reference

TSL and TQLwho does what?

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

This guide gives examples of all these techniques.

TSL and TQLwho does what?


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

16

TSL Guide & Reference

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.

18

TSL Guide & Reference

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 c m i p g Unit centimetres millimetres inches pixels grids

20

TSL Guide & Reference

Dimension Units

Letter l For example: 10c

Unit characters

If no letter is given, grid units are assumed.

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 menu system and toolbox


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

24

TSL Guide & Reference

The menu system and toolbox

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.

26

TSL Guide & Reference

A simple menu

Menu and tool items are, by default, sensitive and can be selected. However, there may be situations where you want a menu or a tool item to be unavailable for selection. The SENSITIVE attribute can be used to define the items sensitivity. An insensitive menu item appears greyed-out. Insensitive tools look the same as sensitive tools. As described in the previous chapter, the SENSITIVE attribute is evaluated each time an ASKMENU command is executed. Once the ASKMENU command is executed the menu system and toolbox cannot be changed or added to. Any attempt to execute a MENU, TOOL or TOOLBOX (described later) command causes an error to occur.

A simple menu
The following example shows a simple TSL script which defines a menu system with one pull-down pane. # Simple Menu (example1.tsl) # title "Simple Menu" menu 1 "Database" menu 1-1 "Exit" action = "Exit" repeat askmenu until %menuval="Exit" This example sets the window title using the TITLE command and defines the menu system. Notice how we have indented the second MENU command to reflect its lower level in the menu hierarchy. Once the menu system is defined we enter a loop and repeatedly ask for input from the menu. When the user selects the Exit action we exit the loop and the script finishes. The loop is defined using the REPEAT and UNTIL commands. When TSL encounters a REPEAT command, it executes all the lines till it finds the matching UNTIL command. The condition after the UNTIL keyword is evaluated. If the condition evaluates to TRUE, the loop is ended and processing continues after the UNTIL command. If the condition evaluates to FALSE or NULL, processing starts again at the matching REPEAT command. The condition after the UNTIL keyword can be any TQL expression that evaluates to a boolean result. This condition is evaluated on the server and may use any functions or variables that are defined.

27

Chapter

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 1-5 "Exit" action = "Exit" 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] until %menuval="Exit" 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,

28

TSL Guide & Reference

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 until %menuval="Exit" 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

30

TSL Guide & Reference

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

32

TSL Guide & Reference

A menu system and toolbox in a real application

TOOLGAP = 10p (ten pixels) GROUPGAP = 10p (ten pixels)

A menu system and toolbox in a real application


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

34

TSL Guide & Reference

A menu system and toolbox in a real application

case "File" To File case "Kingfisher" Kingfisher endswitch until %menuval="Exit" 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

38

TSL Guide & Reference

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.

40

TSL Guide & Reference

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.

42

TSL Guide & Reference

The list selection dialog

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" menu 1-1 "Exit" action = "Exit" 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


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.

44

TSL Guide & Reference

The file selection dialog

The file selection dialog


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.

46

TSL Guide & Reference

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" menu 1-3 "Exit" action = "Exit"

47

Chapter

Dialogs

repeat askmenu if %menuval="Popup" dialog text(12) s "Enter a string" askdialog "Dialog" if %dialogval OK Pressed. String is [s] else Cancel Pressed. endif endif until %menuval="Exit" In this example, the DIALOG command occurs inside the loop and is executed each time the Popup menu action is selected. When the DIALOG command is first encountered a new dialog box is created and a text item is added to it. When the ASKDIALOG command is executed the dialog is completed, the variable associated with the text item is created and the dialog is displayed. Subsequently when the DIALOG command is executed the entire dialog is destroyed and recreated. This destruction and creation of dialogs can be quite expensive and in this example is unnecessary. The DIALOG command should be moved outside the loop (for example, to just after the MENU command). However, there are some circumstances with more complex dialogs when it is necessary to create dialogs in the main part of the script. You can create a dialog with multiple dialog items by executing more DIALOG commands before the ASKDIALOG command. By default these items are arranged in the dialog box in two columns, left to right and top to bottom. The labels are right-aligned and the items are leftaligned. TSL allows you control over the dialog layout but it is normally easiest to let it choose a layout for you. In the next example we create a dialog with four dialog items and introduce three new dialog item types. # Multiple Item Dialogs (example6.tsl) # title "Multiple Item Dialogs" menu 1 "Dialog" menu 1-1 "Popup..." action = "Popup" menu 1-3 "Exit" action = "Exit"

48

TSL Guide & Reference

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 until %menuval="Exit"

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. Dialog Item Text field Keyword TEXT Data Types All data types string short/ long/ byte Comments Allows simple keyboard entry. Data is checked to be the correct type. Allows entry of longer strings or notes Allows quick input of a number within a range

Multiline Text field Slider

MULTITEXT SLIDER

49

Chapter

Dialogs

Dialog Item Toggle button Option menu Scrolled list Exclusive panel Calendar Time range bar Label Button Skip

Keyword TOGGLE OPTION LIST PANEL CALENDAR TIMERANGE LABEL BUTTON SKIP

Data Types bool string string string date time none none none

Comments A simple on/off item. Allows one of a set of values to be selected. Allows one or more values to be selected from a list. Allows one of a set of values to be selected. Allows a date to be selected. Allows one or more time ranges to be defined. Creates a subtitle within a dialog. Initiates dialog actions. 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"

50

TSL Guide & Reference

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. 2. 3. 4. The name of the variable associated with the data item (except for buttons and labels) The item label (which has a maximum length of 60 characters) Any item specific values 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.

52

TSL Guide & Reference

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 OK, Apply 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" menu 1-1 "Popup..." action = "Popup" menu 1-3 "Exit" action = "Exit" 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

54

TSL Guide & Reference

Multiline Text fields

until %menuval="Exit" 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.

Multiline Text fields


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

Sliders
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 Apply button.

Toggle buttons
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"

56

TSL Guide & Reference

Option, List and Panel

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.

Option, List and Panel


The class of dialog items comprising OPTION, LIST and PANEL, is particularly useful when the user is constrained to input of one of a set of values. These items should be used whenever you can enumerate the allowable set of input values. Each of these three dialog items returns a string value which is guaranteed to be one of the specified set, or NULL. The main difference between these three items is their appearance and the way the user makes a selection. Another important difference is that the contents of the list dialog item can be changed while the user is interacting with the dialog. The syntax is very similar for all three. After the item label comes a list of strings. These strings are the set of valid values for this dialog item. For a list item, the scrolled list is preset with these values; for an option menu, the pop-up pane is set with these values; for a panel, the exclusive toggle buttons are labelled with these values. The example below demonstrates these three items: # Choice Items (example8.tsl) # title "Choice Items" menu 1 "Dialog" menu 1-1 "Popup..." action = "Popup" menu 1-3 "Exit" action = "Exit" dialog list(3) t "List" "Choice 1" "Choice 2" \ "Choice 3""Choice 4" "Choice 5" "Choice 6" dialog option o "Option" "Option a" "Option b" \ "Option c" dialog panel p "Panel" "Either this" "that" \ "or the other"

57

Chapter

Dialogs

repeat askmenu if %menuval="Popup" askdialog if %dialogval List value is [t] Option value is [o] Panel value is [p] endif endif until %menuval="Exit" 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 OK 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:

58

TSL Guide & Reference

Option, List and Panel

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 0 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 SINGLE BROWSE Meaning Allows single selection. An item is selected by clicking on it. This is the default. 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. Allows multi-selection. An item is selected by clicking on it. 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. Allows multi-selection. Similar to RANGE but several ranges may be selected by pressing the Ctrl key while selecting ranges.

MULTIPLE RANGE

DISCONTIGUOUS

For lists that allow multi-selection, the maximum number of items that may be chosen can be specified using the SELECTION_MAXITEMS attribute. By default, this is set to the number of items in the list. The TQL variable associated with the list holds the selected values as a comma separated list. An alternative list delimiter can be set using the SELECTION_DELIM attribute. In addition, three system variables hold information on the items chosen from a multi-select list. These are:

%SELECTED holds a delimited list of the items that were selected %NUMSELECTED records the number of items that were selected

60

TSL Guide & Reference

Calendars

%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.

Calendars
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.

Time range bars


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.

Labels
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.

62

TSL Guide & Reference

Application defined buttons

Application defined buttons


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 OK or Apply 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 0 1 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 Apply 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 OK or Apply 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.

Presetting dialog items from a database


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

64

TSL Guide & Reference

Presetting dialog items from a database

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: query display paramname from params ; dialog list(4) pname "Parameter" paramname/12 You can use the same technique to preset the list selection convenience dialog instead of having to enumerate all the list items. For example: query display paramname from params ; select "Parameter" paramname 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.

66

TSL Guide & Reference

Presetting dialog items from a database

# Preset List (example9.tsl) # title "Preset List" menu 1 "Report" menu 1-1 "On Royal House..." action = "House" menu 1-3 "Exit" action = "Exit" # 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 until %menuval="Exit" 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

Dialog layout and default positioning of dialog items


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 The values of these attributes can be changed using the DIALOG LAYOUT command. For example: dialog layout columns=3 alignrows=false

68

TSL Guide & Reference

Dialog layout and default positioning of dialog items

This command would set the number of columns to 3 and disable row alignment. In most situations the only useful one to change is the number of columns. The example script below allows you to see the effect in dialog layout of changing these parameters. # Dialog Layout (example10.tsl) # title "Dialog Layout" menu 1 "Dialog" menu 1-1 "Set Layout..." action = "Layout" menu 1-2 "Popup..." action = "Popup" menu 1-4 "Exit" action = "Exit" declare declare declare declare ncols 2 aitems true acols true arows true

repeat askmenu switch %menuval case "Layout" # Construct a dialog to set the layout # dialog layout columns=2 alignrows=true \ alignitems=true aligncolumns=true dialog slider ncols "No. of Columns" 1 4 dialog skip(1) dialog toggle aitems "Align Items" dialog toggle arows "Align Rows" dialog toggle acols "Align Columns" askdialog "Layout" if %dialogval dialog layout dialog layout dialog layout dialog layout endif

columns = [ncols] alignitems = [aitems alignrows = [arows] aligncols = [acols]

case "Popup" dialog text(12) s "Text field"

69

Chapter

Dialogs

dialog list(2) aList "List" \ "Item 1" "Item 2" "Item 3" dialog panel p "Panel" "Choice 1" "Choice 2" dialog toggle t "Toggle" askdialog "Example" endswitch until %menuval="Exit" Quite often the layout of a dialog is spoilt because of the way that items are always inserted left to right, top to bottom. You can cause TSL to skip a number of positions in its allocation of items using the DIALOG SKIP command. For example: dialog skip(2) results in two positions in the dialog being skipped.

Defining the position of dialog items


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

70

TSL Guide & Reference

Defining the position of dialog items

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 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 LEFT CENTRE RIGHT

CENTRE

Figure 15. The possible origins of a complex and simple dialog items

71

Chapter

Dialogs

Dialog items can consist of either two components or one component, depending on whether they have a label or not. The XORIGIN attribute has a different meaning for CENTRE depending on whether a dialog item has one or two components. For complex dialog itemsthose with two componentsthe centre is the left side of the component that is not a label. For simple dialog items with one componentthat is, labels and labelled or iconised buttonsthe centre is the middle of the dialog item. # Positioning dialog items (example11.tsl) # menu 1 "Database" menu 1-1 "Popup..." action = "Popup" menu 1-3 "Exit" action = "Exit" dialog layout width = 5i, height = 1.5i dialog text(7) partno "Part #" \ xpos = 1i, ypos = 0i, \ xorigin = centre, yorigin = top dialog button default "Update Part" \ action = "Update", area = 1 \ xpos = 1i, ypos = 0.6i, \ xorigin = centre, yorigin = top dialog button "Next Part" \ action = "Next", area = 1 \ xpos = 1i, ypos = 1.1i, \ xorigin = centre, yorigin = top dialog multitext(10,5) descr "Description" \ xpos = 3.5i, ypos = 0i, \ xorigin = centre, yorigin = top repeat askmenu if %menuval = "Popup" askdialog "Edit machine parts" endif until %menuval = "Exit" The above generates a dialog which looks like this: 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

72

TSL Guide & Reference

Changing the control buttons

Figure 16. Dialog where the position of dialog items is defined. 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. The final attribute, LABELGAP, is only appropriate for complex dialog items and it specifies the gap between the items label and main component.

Changing the control buttons


As you have already seen, user dialogs are by default created with the standard control buttons: OK, Cancel and Help. This configuration provides the simplest model for managing dialogs: if a button is pressed, the dialog is dismissed and if it was the OK 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

73

Chapter

Dialogs

the ASKDIALOG command. The parameter is set to one of the following values: Value 0 1 2 3 4 5 Description The default configuration of OK and Cancel.
OK, Apply and Cancel. Apply and Reset. Close. Apply, Reset and Close. Apply and Close.

All configurations also have a Help button. For example: dialog layout mode=2 sets the dialog to use Apply and Reset 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 OK button and for modes 2, 4 and 5 this is the Apply button. The special variable %BUTTONVAL shows which button has been pressed (or, more generally, the ACTION string of whichever dialog item was

74

TSL Guide & Reference

Changing the control buttons

activated). For the standard control buttons this variable is set to the name of the button as described in the table below. Button
OK

Value of %BUTTONVAL "OK" "Apply" "Cancel" "Reset" "Close"

Value of %DIALOGVAL TRUE TRUE FALSE FALSE FALSE

Notes Variables changed; dialog dismissed. Variables changed; dialog not dismissed. Variables unchanged; dialog dismissed. Variables unchanged; dialog not dismissed. Variables unchanged; dialog dismissed.

Apply

Cancel

Reset

Close

Closing a dialog using the window manager menu or an accelerator such as Alt-F4 is identical to pressing the Cancel 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. 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

75

Chapter

Dialogs

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

76

TSL Guide & Reference

Changing the control buttons

# query fetch first from rslt ; declare vfullname "[fullname]", vhouse "[house]",\ vaccessn [accessn] dialog dialog dialog dialog dialog dialog 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" 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" menu 1-3 "Exit" action = "Exit" repeat askmenu if %menuval="Editor" repeat askdialog 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 ;

77

Chapter

Dialogs

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 until %menuval="Exit" query close ; Notice how the script checks for the Cancel 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 Cancel. The ABORT command and the variable %QOK which were used in the above example are described in the section Error handling on page 156.

Managing multiple dialogs


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.

78

TSL Guide & Reference

Managing 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 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 1..." action = "Popup 1" menu 1-2 "Popup 2..." action = "Popup 2" menu 1-3 "Popup 3..." action = "Popup 3"

79

Chapter

Dialogs

menu 1-5 "Exit" 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 case "Popup 3" askdialog 3 endswitch until %menuval="Exit"

Changing the contents of a list


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.

80

TSL Guide & Reference

The INSERT list editing command

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: 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.

The INSERT list editing command


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

81

Chapter

Dialogs

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.

The DELETE list editing command


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 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.

The REPLACE list editing command


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

82

TSL Guide & Reference

The APPEND list editing command

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.

The APPEND list editing command


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 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.

The CLEAR list editing command


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.

83

Chapter

Dialogs

Example
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 Delete Kings button, 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 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" menu 1-3 "Exit" action = "Exit" repeat askmenu if %menuval = "Delete Kings" # Create temporary table. query create tmp as fullname primary ; repeat

84

TSL Guide & Reference

Example

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 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"

85

Chapter

Dialogs

# Drop temporary table. query drop tmp ; endif until %menuval = "Exit" 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.

Using the SENSITIVE attribute in a dialog


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 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.

86

TSL Guide & Reference

Using the SENSITIVE attribute in a dialog

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

Navigating the query buffer


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

90

TSL Guide & Reference

Navigating the query buffer

usages we have already seen in this guide, the latter requires the use of a special form of the REPEAT command. For example: query display exp#, volts from results ; repeat ' Experiment [exp#] Voltage [volts] next forall 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: query display exp#, volts from results ; last repeat ' Experiment [exp#] Voltage [volts] 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: query display exp#, volts from results ; repeat ' Experiment [exp#] Voltage [volts] next for 40 In this example, the loop iterates until either the end of the buffer is reached or until 40 iterations have been made. Therefore, a maximum of 40 rows will be printed. As you can see, managing the query buffer and iterating through it is straightforward. The techniques described above form the basis of report writing in TSL, which is covered in the next chapter.

91

Chapter

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.

92

TSL Guide & Reference

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 ; query display fullname as names from kings ; first repeat set x names ' [x] next forall This does not generate a report with the name of each king in the KINGS table as might be expected when you look at this code. Instead it displays the name of the last monarch 62 times (the number of rows in the query buffer) because it is using the variable NAMES instead of the column of the same name in the query buffer. Text substitution must be used to access columns in the query buffer. It always looks for a column in the query buffer first before checking for a variable of the given name. To avoid the possibility of confusion it is strongly recommended that you never create a variable with the same name as a column. The following scripts work correctly, but the second is more efficient because it avoids the use of variables altogether. # A working report declare names, x query open kings ; query display fullname as names from kings ; first repeat set x "[names]"

' [x]

93

Chapter

The Query Buffer

next forall # A more efficient report query open kings ; query display fullname as names from 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.

94

TSL Guide & Reference

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: query display exp#, volts from results ;

' Experiment Voltage repeat ' [exp#] [volts] next forall

96

TSL Guide & Reference

Text expansion in reports

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 query display exp#, volts from results ; ' 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:

98

TSL Guide & Reference

Text expansion in reports

' [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 @U @E @1 @2 Bold Underlined Emphasised User enhancement 1 User enhancement 2

The following example shows the code for a report that demonstrates a number of the features described above (you need a KINGS database to run this script). # Example Report (example15.tsl) # title "Example Report" query open kings ; menu 1 "Report" menu 1-1 "On Royal House..." action = "Royal" menu 1-3 "Exit" action = "Exit" repeat askmenu

99

Chapter

Reports

if %menuval="Royal" dialog text(10) h "Royal House" askdialog

if %dialogval ' ' @BReport on Royal House of [h]@B ' query display fullname, title, accessn, until from kings where upc(house)=upc(h) ; ' Name Title Ruled From Until if %rows=0 error "[h] is not a Royal House" else table on repeat ' [fullname] [title] [accessn] [until] next forall table off endif endif endif until %menuval="Exit" 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

100

TSL Guide & Reference

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.

102

TSL Guide & Reference

Format string syntax

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.

o x f

c s

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 A b B c 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. The abbreviated month name for the current locale (for example, Jan). Hour of the day, in the format 00 to 23. Hour of the day, in the format 01 to 12. Day of the year, in the format 001 to 366.

d D e h H I j

104

TSL Guide & Reference

Format string syntax

m M n p r R S t T U w W x X y Y Z

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

106

TSL Guide & Reference

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

108

TSL Guide & Reference

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"

110

TSL Guide & Reference

Printing reports to a file or a printer

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" menu 1-1 "On Royal House..." action = "Royal" menu 1-3 "Exit" action = "Exit" # Procedure for printing the report to the # current printer defproc report_on_house( family ) @BReport on Royal House of [norm(family)]@B query display fullname, title, accessn, until 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] [accessn] [until]

next forall table off endif endproc

112

TSL Guide & Reference

Printing reports to a file or a printer

repeat askmenu if %menuval="Royal" repeat askdialog if %buttonval = "OK" if outto <> "to Screen" setprinter 1 if outto="to File" and fname<>"" printer output = file, \ filename = "[fname]" elif outto="to Printer" and fname<>"" printer output = printer, \ command = "[fname]" endif printer on endif call report_on_house( h ) if outto <> "to Screen" printer off endif endif until not %buttonval <> "Destination Changed" endif until %menuval="Exit" query close kings ; In this example, the dialog closes once the user has selected a value to report on and a destination to print to and the report is generated. Every time the user opens the dialog and selects a value and output, a new report is generated even if the user chooses to report on the same value each time. This may be acceptable if the report is short and takes only a moment to generate. However, for long reports regeneration may take some time. In addition, if the user has only changed the output destination and not the information on which to report, regeneration may seem unnecessary. An alternative is to maintain the dialog so that the user can adjust the reports contents and destination and to copy the information that is sent to screen to a buffer file. This file then holds a copy of the report

113

Chapter

Reports

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. 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. 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

114

TSL Guide & Reference

Printing reports to a file or a printer

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" menu 1-1 "On Royal House..." action = "Royal" menu 1-3 "Exit" action = "Exit" # 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 ' query display fullname, title, accessn, until 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 until %menuval="Exit"

116

TSL Guide & Reference

Printing reports: example

# Close the kings database after use query close kings ;

Printing reports: example


# 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" query open kings ; repeat askmenu

to @file" action = "File" to @printer" action = "Printer" to @screen" action = "Screen" action = "Exit"

switch %menuval case "File" call do_report( true, 10 ) case "Printer" call do_report( true, 11 ) case "Screen" call do_report( false, null ) endswitch until %menuval = "Exit" 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

118

TSL Guide & Reference

Printing reports: example

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.

122

TSL Guide & Reference

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.

124

TSL Guide & Reference

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

126

TSL Guide & Reference

Example

successfully. Other values indicate various error conditions as described below: Value 1 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.

2 3

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 1-3 "Exit" action = "Exit" 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

128

TSL Guide & Reference

Printing a canvas

case "Options" # Let the user set the procedure option askdialog 1 "Procedure Options" endswitch until %menuval = "Exit" query close ; canvas off

Printing a canvas
You will often want to provide the user with a means of producing a hardcopy of a graph. Although the menu system on a display window normally has the print option enabled, it is sensible to provide a hardcopy option in the TSL menu system itself. Kingfisher is only able to print or plot what is currently displayed in the current canvas, so you must first generate the graph or graphs by executing a procedure or using the GRAPH command as described later in this chapter. The command below prints the contents of the current canvas to a printer or plotter: canvas print

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 9 10 Description The named configuration file could not be found by the Kingfisher server. 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.

130

TSL Guide & Reference

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 graph draw display spectrum from spectra where test#=23 ;

132

TSL Guide & Reference

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 graph format load xyline graph draw display spectrum from spectra 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: graph format load xyline graph draw display spectrum from spectra where test#=23 ; graph format load xyscat graph draw display spectrum from spectra 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 graph format load xyline graph draw display spectrum from spectra 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.

134

TSL Guide & Reference

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 3 4 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. The query in the GRAPH DRAW command did not return any data.

5 11

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 sequence by kingno ; endswitch until %menuval="Exit" 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

136

TSL Guide & Reference

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:

138

TSL Guide & Reference

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 1-3 "Exit" action = "Exit" menu 2 "Edit" menu 2-1 "Legend..." action = "Legend"

repeat askmenu switch %menuval case "Graph" graph format load legend graph draw display children, kingno from kings sequence by kingno ;

139

Chapter

Graphics

case "Legend" dialog layout columns=1 dialog option style "Legend style" \ "Coloured Text" "Text & Colour" "Text & Style" dialog text(12) entry1 "Main entry" askdialog if %dialogval switch style case "Coloured Text" declare istyle 0 case "Text & Colour" declare istyle 1 case "Text & Style" declare istyle 2 endswitch canvas mode edit=on graph property set lgstyle=[istyle] \ lgdstext/0="[entry1]" canvas mode edit=off endif endswitch until %menuval="Exit" query close ; canvas off

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.

140

TSL Guide & Reference

Example

The X, Y and Z values are in data coordinatesthat is, they are the actual data values that would be plotted at that position on the graph. The values are always real numbers. If the user does not click on the current graph, the variables will be set to NULL. The example below shows how the command might be used: graph cursor if %xval<>null and %yval<>null info "Value is [%xval] [%yval]" else error "Missed!" endif

Example
The following example demonstrates how the cursor can be used to implement range selection on a simple graph. A graph is drawn and the cursor is used to read off a range in the X domain. This range is then used to generate a condition for a query in the database and the graph is redrawn. # Using the graph cursor (example21.tsl) # Plots a graph. The cursor can be used to select # an X range from which to construct a new query. # Enable the canvas # canvas on noedit query open kings ; declare minx declare maxx menu 1 "Plot" menu 1-1 "Graph" action = "Graph" menu 1-3 "Exit" action = "Exit" menu 2 "Cursor" menu 2-1 "Select range" action = "Range" repeat askmenu

141

Chapter

Graphics

switch %menuval case "Graph" graph format load children graph draw display children, kingno from kings sequence by kingno ; case "Range" info "Select left edge of range to zoom on" graph cursor if %xval<>null and %yval<>null set minx %xval info "Select right edge of range to zoom on" graph cursor if %xval<>null and %yval<>null set maxx %xval graph format load children graph draw display children, kingno from kings where kingno>=minx and kingno<=maxx sequence by kingno ; endif endif info endswitch until %menuval="Exit" query close ; canvas off

Loading a colourmap
If you are using surface plots or maps, you may wish to load a different colourmap either from the standard Kingfisher selection or one that you have created yourself. The environment variable KF_COLOURMAP_PATH can be used to define a set of directories where user-defined colourmaps are located. These directories are searched before the standard Kingfisher directories.

142

TSL Guide & Reference

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 7 8 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 graph position 0 0 50 100 graph format load xyline graph draw display spectrum from spectra where test#=23 ; setgraph 2 graph position 50 0 50 100 graph format load xyline graph draw display spectrum from spectra where test#=24 ; There are two complications to this model which are brought about by restrictions in Kingfisher. The first concerns the GRAPH DRAW command and the second concerns what happens when a graph is destroyed.

The GRAPH DRAW command, unlike the other commands, does not draw data on the current graph but actually draws data on the last graph created in the current canvasknown as the graph with the data focus. In most situations the current graph will have the data focus and you will not encounter any problems. However, you will get an error if you execute a GRAPH DRAW command when the current graph does not have the data focus. 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

144

TSL Guide & Reference

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" menu 1-3 "Exit" action = "Exit" repeat askmenu switch %menuval case "House" dialog layout columns=1 dialog text(12) h "Royal House" dialog toggle samec "On same canvas" askdialog if %dialogval if not samec setgraph 1 canvas clear set numgraphs 1 else if numgraphs=4 error "Too many graphs - 4 is maximum" else set numgraphs numgraphs+1 declare i 1 repeat setgraph [i] graph position 0\ [(i-1)*100/numgraphs] 100 [100/numgraphs] set i i+1 until i>numgraphs endif endif graph format load house graph draw display children, kingno

145

Chapter

Graphics

from kings where upc(house)=upc(h) ; endif endswitch until %menuval="Exit" 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

146

TSL Guide & Reference

Example

(that is, the graph whose properties can be changed). This information is available from the following variables: %NUM_GRAPHS %GRFOCUSSED %GRSELECTED The number of graphs in the canvas. The graph with the data focus. 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 canvas mode edit=on autoraise=on query open kings ; declare numgraphs 0, \ canvasses 1, \ acanvas 1, \ h "Anjou" menu 1 "Plot" menu 1-1 "Royal House" action = "House" menu 1-2 "Create Canvas" action = "CreateCanvas" menu 1-3 "Change Canvas" action = "ChangeCanvas" menu 1-4 "Exit" action = "Exit"

147

Chapter

Graphics

repeat askmenu switch %menuval case "House" dialog layout columns=1 dialog text(12) h "Royal House" dialog toggle samec "On same canvas" askdialog if %dialogval if not samec setgraph 1 canvas clear set numgraphs 1 else if numgraphs=4 error "Too many graphs - 4 is maximum" else set numgraphs numgraphs+1 declare i 1 repeat setgraph [i] graph position 0\ [(i-1)*100/numgraphs] 100 [100/numgraphs] set i i+1 until i>numgraphs endif endif graph format load house graph draw display children, kingno from kings where upc(house)=upc(h) ; endif case "CreateCanvas" set canvasses canvasses + 1 setcanvas [canvasses] canvas on nomenu canvas mode edit=on autoraise=on set numgraphs %num_graphs set samec FALSE case "ChangeCanvas" if canvasses <> 1

148

TSL Guide & Reference

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 until %menuval="Exit" 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

150

TSL Guide & Reference

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

Miscellaneous Topics
8 Miscellaneous Topics

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

Miscellaneous Topics

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 Vallent 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

154

TSL Guide & Reference

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 format delimiter 0 1 " " Transfer to/from file. Delimited ASCII data. Space as field delimiter. Linefeed as row terminator. TQL %OVERWRITE mode disabled.

terminator 0 overwrite 0

Errors
After execution of the transfer, the TSL interpreter sets the special variable %XFSTATUS to indicate the success or failure of the transfer. A value of 0 indicates that the transfer completed with no errors. Other values indicate various error conditions: Value 1 Description The end of file was encountered during the processing of a row. EOF is only expected after an entire row has been read. The missing values are set to NULL and the row will probably be discarded by the TQL Server.

155

Chapter

Miscellaneous Topics

Value 2

Description The end of row terminator was encountered when not all fields had been encountered in the row. The missing fields will be set to NULL and may be discarded by the TQL Server.

Error handling
In the process of executing a TSL script the TSL interpreter executes very many commands on the TQL Server. Some of these commands result directly from QUERY commands in the script, some come from the evaluation of IF expressions and other internal functions in TSL. There are many circumstances that can cause a TQL command to return an error, so your application should be aware of where errors may occur and what it can do about them. By default when TSL encounters an error (whether it be a query error or a TSL syntax error) it prints an error message and stops execution. It may also display an error dialog depending on the value of a special X resource (see page 200 for a complete description of the displayError resource). The response of TSL to query errors can be changed using the ABORT command. Abort mode can be enabled or disabled for all errors or just for certain errors. If a query returns an error for which abort mode has been disabled, the script is not aborted but a special status variable %QOK is set to indicate that an error occurred. %QOK is a boolean variable which is set to TRUE if the last query executed successfully and FALSE otherwise. If the application needs to take special action when a query fails, it can test the value of this variable. For example: abort off query open mydb ; abort on if %qok # Execute a script to generate a report # script report.tsl else error "Failed to open database!" endif

156

TSL Guide & Reference

Error handling

Notice how we have bracketed the QUERY command with ABORT OFF and ABORT ON. We disable abort mode to allow us to test for errors and then we re-enable abort mode so that any subsequent commands fail normally. In the above example abort mode was disabled for all errors, but the ABORT command can be defined to restrict the errors for which abort mode is disabled. The ABORT ON EXCEPT command leaves abort mode enabled for all commands except the errors that follow, for example: abort on except q-85 This disables abort mode only for query error -85, thus every error except query error -85 will cause TSL to exit. The ABORT ON ONLY command leaves abort mode enabled only for the errors that follow, for example: abort on only q-85 This disables abort mode for all query, filer and database errors except query error -85, thus only query error -85 will cause TSL to exit. You can define a list of error codes by preceding the error number with a character representing the level of the error; q for query level errors, d for database level errors and f for filer level errors. For example: abort on except q-85, d22, q-86, f70 This enables abort mode for all errors except query level errors -85 and -86, database level error 22 and filer level error 70. As an alternative to testing %QOK explicitly the application can use the IFOK command. The command IFOK is equivalent to IF %QOK. Note that if a TQL error is detected during the evaluation of a condition in an IF, ELIF, UNTIL, SWITCH or CASE statement, the application always aborts, regardless of the current abort mode setting. When developing an application we would strongly recommend that you run your scripts with abort mode enabled. This ensures that you quickly catch any syntax errors in TQL commands or commands that may fail due to maths errors or lack of data errors. Only disable abort mode for those commands that you know are quite likely to fail, and only for the errors that you are prepared to write code to handle. Three further variables are set after the execution of a query: %QERR, %DERR and %FERR. These contain the query level error code, database level error code and file level error code for the last command executed. If any of these values is non-zero, an error has occurred.

157

Chapter

Miscellaneous Topics

Please refer to the TQL Guide and Reference for information on error codes. The messages generated by TSL when an error occurs and abort mode is disabled are stored in the variables %QMSG, %DMSG and %FMSG. These variables hold the query level message, the database level message and the filer level message respectively. The example below shows how you can test for a particular error, in order to print more specific error messages or recover from the error. abort on except d22 query open mydb ; abort on ifok # Execute a script to generate a report # script report.tsl else # We only handle database error number 22, # which is returned if the user is not known. error "[sysuser()] is not a known user." stop endif

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

158

TSL Guide & Reference

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 query display exp#, volts from results ; repeat ' [exp#] [volts] next forall

159

Chapter

Miscellaneous Topics

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 query display exp#, volts from results ; 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.

160

TSL Guide & Reference

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 Tsl.labelFont Usage The font to use for labels in dialogs (normally set to a proportional font such as New Century Schoolbook or Helvetica). 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). The font to use for all push-button in dialogs i.e the OK and Cancel buttons.

Tsl.dataFont

Tsl.buttonFont

161

Chapter

Miscellaneous Topics

Font type Tsl.menuFont Tsl.toolboxFont Tsl.normalFont Tsl.boldFont Tsl.useVueFonts

Usage The font to use for all menu entries in the pulldown menu system. The font to use for all toolbox labels. The font to use in the main TSL window for normal, non-enhanced text. The font to use in the main TSL window for bold text enabled via the @B symbol in TSL. 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 Tsl.rows Tsl.columns Tsl.bufrows Description The number of rows that fit in the terminal window i.e not including the menu bar. The number of columns in the terminal window. 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.

162

TSL Guide & Reference

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 Tsl.alignRows Description Defines the default value for the ALIGNROWS attribute. If this resource is not defined, the default value for ALIGNROWS is set to TRUE. Defines the default value for the ALIGNCOLUMNS attribute. If this resource is not defined, the default value for ALIGNCOLUMNS is set to TRUE. Defines the default value for the ALIGNITEMS attribute. If this resource is not defined, the default value for ALIGNITEMS is set to TRUE.. Defines the default value for the COLUMNS attribute. If this resource is not defined, the default value for COLUMNS is set to 2.

Tsl.alignColumns

Tsl.alignItems

Tsl.defaultColumns

163

Chapter

Miscellaneous Topics

Attribute

Description

Tsl.defaultButtonColumns Defines the default value for the BUTTONCOLUMNS attribute. If this resource is not defined, the default value for BUTTONCOLUMNS is set to 1. Tsl.defaultMode Defines the default value for the MODE attribute. If this resource is not defined, the default value for MODE is set to 0. Defines the default value for the BUTTONLAYOUT attribute. If this resource is not defined, the default value for BUTTONLAYOUT is set to COLUMNCENTRE. Defines the default value for the BUSYONAPPLY attribute. If this resource is not defined, the default value for BUSYONAPPLY is set to TRUE.

Tsl.buttonLayout

Tsl.busyOnApply

Toolbox attributes
The default values for all of the TOOLBOX attributes are specified in the resource file. Attribute Tsl.toolboxToolGap Description 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 attribute. If this resource is not defined, the default value for GROUPGAP is set to 10. Tsl.toolboxFrame Defines the default value for the FRAME attribute. If this resource is not defined, the default value for FRAME is set to TRUE. Defines the default value for the GRAVITY attribute. If this resource is not defined, the default value for GRAVITY is set to WEST.

Tsl.toolboxGravity

164

TSL Guide & Reference

Menus and dialogs

Attribute Tsl.toolboxRows

Description 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. 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.

Tsl.toolboxColumns

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 Tsl.maxDialogs Tsl.maxMenuItems Description Defines the maximum number of dialogs that can be defined. The default value is 200. Defines the maximum number of items that can be defined in a menu pane. The default value is 20. Defines the maximum number of levels to which a menu may be nested. The default value is 5.

Tsl.maxMenuNesting

165

Chapter

Miscellaneous Topics

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 Tsl*january: <month> Tsl*february: <month> Tsl*march: <month> Tsl*april: <month> Tsl*may: <month> Tsl*june: <month> Tsl*july: <month> Tsl*august: <month> Tsl*september: <month> Tsl*october: <month> Tsl*november: <month> Tsl*december: <month> Tsl*monday: <day> Tsl*tuesday: <day> Tsl*wednesday: <day> Tsl*thursday: <day> Tsl*friday: <day> Tsl*saturday: <day> Tsl*sunday: <day> Description Substitute month with the month in your chosen language, for example: Tsl*january: <janvier> displays the French translation of January.

Substitute day with the day in your chosen language, for example: 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.

166

TSL Guide & Reference

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

Command-line options
The TSL interpreter is invoked using the tsl command. This command takes a number of options which control the behaviour of both the interpreter and the TQL Server. The available options are described below. tsl <X-options> [-user <username>] [-host <hostname>] [-server <hostname>] [-outfile <file>] [-printer] [-raw] [-buffersize <bytes>] [-old] [-debug] [-nowindow] [-nomap] [-term <termname>] [-logFile <file>] [-printCommand <command>]

167

Chapter

Miscellaneous Topics

[-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. 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. 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. 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.

-debug

-host

-nomap

168

TSL Guide & Reference

Command-line options

-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. This argument enables compatibility mode with a previous incarnation of TSL known as the Document Processor. 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. This argument specifies that the logical printer is the configured system printerthat is, any printed output is sent to the printer. 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. as for -host The argument defines the terminal that should be used when executing SHELL commandsfor example, - term xterm 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.

-old

-outfile

-printer

-raw

-server -term

-user

169

Chapter

Miscellaneous Topics

If you are running TSL in nowindow mode (described above), TSL will not find the X resources specified in $TQL_CLIENT_DIR/appdefs/Tsl. Resources that configure the log file, the default printer and the input/output formats of dates, times and constants can be defined using the following command-line arguments. Additional information on these command-line arguments can be found by looking for the appropriate X resource in the file $TQL_CLIENT_DIR/appdefs/Tsl. -complexOutputFormat 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 This argument specifies the format that TSL will use to read in dates. This corresponds to the X resource Tsl.dateInputFormat. For example: -dateInputFormat "%d%m%y" -dateOutputFormat This argument specifies the format that 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. 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

-printCommand

170

TSL Guide & Reference

Command-line options

-printerModel

This argument is used to obtain highlighting details for the printer. It must be followed by the name of a model file in $TQL_CLIENT_DIR/etc/models. If you are using tbprint in PostScript mode, this should be set to TBPS. This corresponds to the X resource Tsl.printerModel. 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. This argument specifies the format that TSL will use to display times. This corresponds to the X resource Tsl.timeOutputFormat. For example: -timeOutputFormat"%H:%M:%S"

-rawPrintCommand

-timeOutputFormat

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

Miscellaneous Topics

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.

172

TSL Guide & Reference

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.

174

TSL Guide & Reference

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.

176

TSL Guide & Reference

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.

178

TSL Guide & Reference

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.

180

TSL Guide & Reference

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.

182

TSL Guide & Reference

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: [] {} | () name 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. 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 TQL_expression quoted_TQL_bool_expr TQL_variable_name TQL_bool_var integer Description Indicates any valid TQL expression. Indicates any valid TQL boolean expression between quotes. Indicates any valid TQL variable name. Indicates any valid TQL boolean variable name. Indicates any sequence of characters which form a valid integer.

186

TSL Guide & Reference

Construct data_type

Description Indicates the name of a valid TQL data type, thus data_type = STRING | BYTE | SHORT | LONG | SHORTREAL | REAL | COMPLEX | BOOL | DATE | TIME | CHAR. Indicates any sequence of characters enclosed by double or single quotation marks. Indicates any sequence of characters which represents a valid file name on the underlying operating system. Indicates any sequence of characters which represent a valid bitmap file name which can be found by searching the directories in the system variable XBMLANGPATH. Indicates any sequence of valid TSL commands (possibly empty). Indicates any sequence of characters which are to be executed by a UNIX shell. Indicates any sequence of numbers optionally followed by the letter c, m, i, p l or g, for example 13p or 15i. Indicates any sequence of numbers followed by the letter c, m i, p or l. A sequence of alphabetic or numerical characters. The first letter must be alphabetic.

quoted_string

filename

bitmap_file

commands system_command dimension_unit

dimension_unit_no_grid procedure_name

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

188

TSL Guide & Reference

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.

190

TSL Guide & Reference

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 labelFont Description The font used for messages and titles and for labels within a dialog. May be fixed or proportional. The font used for data values within a dialog. Should be a fixed-width font. The font used for button labels in dialogs. May be fixed or proportional. The font used for menu entries. May be fixed or proportional. The font used for toolbox labels. May be fixed or proportional. The font used for displaying text in the TSL terminal window. Should be a fixed-width font. 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. If TRUE, HP VUE system and user fonts are used by the application as appropriate.

dataFont buttonFont menuFont toolboxFont normalFont boldFont

useVueFonts

Each font resource may be set to the name of any font recognised by the X windows server. XFontSets TSL uses FontStructs placed in FontLists to store the fonts used by the application. However in order to enable TSL to support international characters, for example the Korean and Japanese languages which consist of thousands of characters, the FontStructs need to be combined

192

TSL Guide & Reference

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 labelFontset Description The font used for messages and titles and for labels within a dialog. May be fixed or proportional. The font used for data values within a dialog. Should be a fixed-width font. The font used for button labels in dialogs. May be fixed or proportional. The font used for menu entries. May be fixed or proportional. The font used for toolbox labels. May be fixed or proportional. The font used for displaying text in the TSL terminal window. Should be a fixed-width font. 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. If TRUE, HP VUE system and user fonts are used by the application as appropriate.

dataFontset buttonFontset menuFontset toolboxFontset normalFontset boldFontset

useVueFontset

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 rows columns bufrows bufcols halfBright Description Integer. Number of rows in the TSL terminal window Integer. Number of columns in the TSL terminal window Integer. Number of rows in the vertical scroll buffer for the TSL terminal window. Integer. Number of columns in the horizontal scroll buffer for the TSL terminal window. 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 columnGap rowGap horizMargin vertMargin Description Integer. Gap in pixels between columns in a multicolumn dialog. Integer. Gap in pixels between rows in a dialog. Integer. Gap in pixels between left and right borders of dialog and nearest dialog element. Integer. Gap in pixels between top and bottom borders of dialog and nearest dialog element.

194

TSL Guide & Reference

Resource labelGap buttonGap buttonRowGap buttonExtra

Description Integer. Gap in pixels between a dialog items label and the dialog item itself. Integer. Gap in pixels between application defined buttons. Integer. Gap in pixels between rows of application defined buttons. Integer. Pixels added either side of the largest application defined button label to define the size of all buttons. Integer. Gap in pixels between the dialog items and the separator and the separator and application defined buttons.

separatorGap

Dialog layout The following resources set the default values for dialog layout attributes. They may be overridden for an individual dialog using the DIALOG LAYOUT command. Resource defaultColumns Description 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 alignColumns alignItems defaultMode Boolean. Default value for ALIGNROWS attribute. Boolean. Default value for ALIGNCOLUMNS attribute. Boolean. Default value for ALIGNITEMS attribute. Integer. Default value for MODE attribute. This should be in the range 0 5.

195

TSL Reference

Resource buttonLayout

Description String. Default value for BUTTONLAYOUT attribute. This should be either COLUMNCENTRE or DIALOGCENTRE. Boolean. Default value for BUSYONAPPLY attribute.

busyOnApply

Scroll bar display Resource horizontalscroll Description Used to indicate if a horizontal scroll bar should be displayed in the terminal output window. The default setting for this resource is FALSE. Used to indicate if a vertical scroll bar should be displayed in the terminal output window. The default setting for this resource is TRUE.

verticalscroll

Toolbox Appearance The following resources set the default values for toolbox attributes. They may be overridden using the TOOLBOX command. Resource toolboxToolGap toolboxGroupGap toolboxFrame toolboxGravity Description Integer. Default value for TOOLGAP attribute. Integer. Default value for GROUPGAP attribute. Boolean. Default value for FRAME attribute. String. Default value for GRAVITY attribute. This should be one of NORTH, EAST, SOUTH, WEST. Integer. Default value for ROWCOLS attribute if the GRAVITY attribute is either NORTH or SOUTH.

toolboxRows

196

TSL Guide & Reference

Resource toolboxColumns

Description Integer. Default value for ROWCOLS attribute if the GRAVITY attribute is either EAST or WEST.

197

TSL Reference

Dates and times Resource dateInputFormat Description 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. 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. String. Determines the format used when 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.

dateOutputFormat

timeOutputFormat

198

TSL Guide & Reference

Printing Resource printCommand Description String. The operating system command that TSL uses to spool output to the system printer. 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. 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.

rawPrintCommand

printerModel

Menus and dialogs Resource maxDialogs maxMenuItems Description Defines the maximum number of dialogs that can be defined. The default value is 200. Defines the maximum number of items that can be defined in a menu pane. The default value is 20. Defines the maximum number of levels to which a menu may be nested. The default value is 5.

maxMenuNesting

199

TSL Reference

Miscellaneous Resource logFile Description 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. Integer. The size of the query buffer in bytes. String. Determines the format used when 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. 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. Boolean. Determines whether the Kingfisher canvas windows are killed off whenever a TSL error occurs. The default setting is FALSE.

queryBufferSize complexOutputFormat

displayErrors

killCanvasOnError

200

TSL Guide & Reference

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

202

TSL Guide & Reference

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. 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. 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.

204

TSL Guide & Reference

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.

206

TSL Guide & Reference

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.

208

TSL Guide & Reference

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 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. CLEAR HIDE PRINT RAISE REFRESH SNAPSHOT

210

TSL Guide & Reference

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 0: 3: 7: 8: Description The command was executed successfully. Kingfisher was busy executing on behalf of another client. The colourmap could not be found. 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.

212

TSL Guide & Reference

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 one of the following: Value 0: 3: 9: 10 : Description The command was executed successfully. Kingfisher was busy executing on behalf of another client. The configuration file could not be found. 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. If no graphics canvas exists, a CANVAS ON command is executed automatically.

214

TSL Guide & Reference

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. If no graphics canvas exists a CANVAS ON command is executed automatically. Example CANVAS MODE autoraise=on enables AUTORAISE mode.

216

TSL Guide & Reference

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

218

TSL Guide & Reference

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 geometry = x_position y_position width height Description The CANVAS RESIZE command allows you to resize the current graphics canvas programmatically. The geometry is specified as a sequence of four numbers corresponding to the X position, Y position (where the X position 0, Y position 0 is the top left corner of your screen), width and height. The position is specified in pixel coordinates of the root window; the size is specified in pixels. Any or all of the numbers can be replaced by an asterisk indicating that the default position or size, as specified in the X resource database, is to be used. Text substitution is performed on geometry. Examples CANVAS RESIZE 0 0 600 500 Resizes the Kingfisher canvas to 600x500 pixels and positions it at the top left of the display.

220

TSL Guide & Reference

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 dialog_number = 1 200 dialog_name = string Description When a dialog is submitted using an application defined button or a standard control buttons such as Apply, the dialog remains on the screen until a CLOSEDIALOG is executed for that dialog. The CLOSEDIALOG command is used to close a dialog that is no longer required by the application. If one of dialog_number or dialog_name are not specified, the current dialog is closed. It is not an error to close a dialog that is already closed. Text substitution is performed on dialog_number and dialog_name. Example CLOSEDIALOG 3 closes dialog number 3. CLOSEDIALOG print_options closes the dialog named print_options.

222

TSL Guide & Reference

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?"

224

TSL Guide & Reference

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.

226

TSL Guide & Reference

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 varname = TQL_variable_name label = quoted_string extradepends upon dialog_type attributesdepends upon dialog_type Description A dialog item is a single user interface element. It may be one of the following: Label Text field Multi-line text field Horizontal slider Vertical slider Scrolling list Option menu Selection panel Toggle button Push button (LABEL) (TEXT) (MULTITEXT) (SLIDER or HSLIDER) (VSLIDER) (LIST) (OPTION) (PANEL) (TOGGLE) (BUTTON)

227

TSL Reference

Calendar Time range bar

(CALENDAR) (TIMERANGE)

Most items have a label string label. To create an unlabelled item, set label to the empty string (""). The maximum length of a label is 60 characters. Each item, except a LABEL or BUTTON item, must have a TQL variable associated with it. The value of this variable is used to initialise the dialog element when the dialog is displayed and is used to store the return value of that element when the dialog is submitted. The data type of the variable should be appropriate for the dialog item. The variable need not be declaredif it does not exist it is created when the dialog first opens (see ASKDIALOG). Text substitution is performed on label and some other attributes, depending upon the dialog item type. Note that elements can be added to a dialog only as long as that dialog has not been processed (using the ASKDIALOG command). If a DIALOG command is executed for a dialog after that dialog has been processed, that dialog is discarded and construction of a new dialog begins. All dialog items which are placed in the main dialog area (that is, not in the user-defined button area) have optional positioning attributes. If any of these are set, they override or adjust the default position of the dialog item. These attributes are given at the beginning of this section, under Notation. Their use is described in Chapter 4 (Dialogs). A detailed reference for each of the individual dialog item types, as well as DIALOG LAYOUT and DIALOG SKIP, may be found on the following pages.

228

TSL Guide & Reference

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 attributes = attribute { , attribute } attribute = ACTION = quoted_string | AREA = 0 | 1 | SENSITIVE = boolean_attribute | position_attribute Description The DIALOG BUTTON command is used to create a button on the current dialog, either in the dialogs main area or the application defined button area. The application defined button area is positioned between the main area and the standard control buttons. The first style of the command creates a button with a label on it. The second creates an iconic buttonthat is, a button that has an icon on it instead of a label. This normally uses the primary_bitmap for the icon, but uses active_bitmap (if this is given) while the button is depressed. An iconic button may also have a label positioned next to it, provided it is in the dialogs main area. The values primary_bitmap and active_bitmap are bitmaps which are searched for in the directories specified by the XBMLANGPATH environment variable. See Icons on page 20 for a description of this environment variable. Text substitution is performed on button_label, primary_bitmap, active_bitmap and on the values given with the ACTION, SENSITIVE, XPOS, YPOS, XADJUST, YADJUST and LABELGAP attributes.

229

TSL Reference

Activation When a button is pressed the dialog is submitted, with the variable %DIALOGVAL set to TRUE and %BUTTONVAL set to the buttons ACTION attribute. Note that the ACTION attribute must be defined for all buttons. An application defined button may be designated as the dialogs default buttonthat is, the button that is activated if the user double clicks on a list or presses return. The default button is identified on the dialog by a box surrounding the button. A dialog can only have one default button. Sensitivity The value of the SENSITIVE attribute determines whether button can be pressed or not. Each time the ASKDIALOG command is executed, TSL evaluates the SENSITIVE attribute (if defined) and sets the button to be sensitive only if it is TRUE. Positioning The AREA attribute is used to control the location of the button, and is assigned a value of 0 to signify the application defined button area and a value of 1 to signify the dialogs main area. The buttons placed in the application defined button area are arranged in columns as controlled by the BUTTONCOLUMNS attribute (set using the DIALOG LAYOUT command). Buttons placed in the dialogs main area are positioned in the same way as other dialog items. In addition, if the button is a labelled iconic button the attribute LABELGAP can be used to define the gap between the label and the iconic button. All labelled buttons are made the same size, determined by the largest button. Iconic buttons use the size of the bitmap to determine their size. Example DIALOG BUTTON "Next Row" ACTION = "Next" DIALOG BUTTON DEFAULT "Add Customer" ACTION = "AddCust" DIALOG BUTTON DEFAULT ICON "kingfisher" \ ACTION = "Start Kingfisher" DIALOG BUTTON "Delete Row" ICON "delete.bm" \ AREA = 1, ACTION = "Delete", \ SENSITIVE = "sysuser() = 'DBA'" DIALOG BUTTON "Weekly Nett Report" \ AREA = 1, ACTION = "WNett", \ XPOS = 3i, YPOS = 2i, XORIGIN = LEFT

230

TSL Guide & Reference

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 attributes = attribute { , attribute } attribute = ACTION = quoted_string | SENSITIVE = boolean_attribute | position_attribute Description This dialog item allows the user to select dates from a calendar interactively. The item consists of two option items that indicate which month and year is currently displayed and a calendar from which the user can select a date. The user can change which month is displayed by clicking on the month option item. This displays a pop-up menu listing the months of the year. When the user selects a new month, the dates in the calendar change to reflect the new selection. To select another year, the user clicks on the forward and back arrows on the year item. As a new year is selected, the calendar changes to reflect the selection. The date the user selects is stored in the datevar variable that is associated with the item when it is created. If, at the time of creation, datevar contains a valid date, the calendar item is created with this date selected. Otherwise, the calendar is displayed with the current date selected. Note that, unlike most other dialog items, if the user selects a date, the value of %DLOGCHANGED is not affected. Using this item in a dialog may give unexpected results when used in conjunction with %DLOGCHANGED. Text substitution is performed on label and on the values given with the ACTION, SENSITIVE, XPOS, YPOS, XADJUST, YADJUST and LABELGAP attributes.

231

TSL Reference

Activation If the ACTION attribute is defined, the dialog item is made active whenever a new date is selected. If the dialog item is made active, the value of the ACTION attribute is stored in the variable %BUTTONVAL and TRUE is stored in the %DIALOGVAL variable. Sensitivity If the SENSITIVE attribute evaluates to FALSE, the calendar is insensitivethat is, it is greyed out and the user cannot select it. Positioning The position of the time range slider can either be determined by TSL or defined by position_attributes. Example DECLARE report_date \[11/1/98] DIALOG CALENDAR report_date "Report Date" defines a calendar dialog item labelled Report Date with the initial display date set to 1 November 1998.

232

TSL Guide & Reference

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 label = quoted_string bitmap = bitmap_file attributes = attribute { , attribute } attribute = SENSITIVE = boolean_attribute | position_attribute Description A label item is simply an output field intended for use as a title in a dialog. This can consist of either text or an icon. If this is text, the label is limited to 60 characters. The first command creates an output field containing text, while the second places an icon in the dialog. By default, both types are centred in the current column of the dialog. The value bitmap is a bitmap which is searched for in the directories specified by the XBMLANGPATH environment variable. See Icons on page 20 for a description of this environment variable. Text substitution is performed on label and on the values given with the SENSITIVE, XPOS, YPOS, XADJUST and YADJUST attributes. Activation Labels cannot be made active. Sensitivity The SENSITIVE attribute can be used, but this only affects the labels appearance (a label cannot initiate an action). Insensitive text labels appear greyed out but insensitive iconic labels appear the same as sensitive iconic labels.

233

TSL Reference

Positioning The position can be modified using the position attributes, XPOS, YPOS, and so on. As a label has only one component, the LABELGAP attribute cannot be used. Example DIALOG LABEL "Parameter Details"

234

TSL Guide & Reference

DIALOG LAYOUT

Sets the layout parameters for the current dialog


Syntax DIALOG LAYOUT attributes Arguments attributes = attribute { , attribute } attribute = COLUMNS = integer | BUTTONCOLUMNS = integer | BUTTONLAYOUT = blayval | ALIGNCOLUMNS = boolean | ALIGNROWS = boolean | ALIGNITEMS = boolean | BUSYONAPPLY = boolean | MODE = integer | WIDTH = dimension_unit_nogrid | HEIGHT = dimension_unit_nogrid | GRID = integer x integer blayval = COLUMNCENTRE | DIALOGCENTRE Description Within a dialog, items are, by default, laid out left to right in the order that they are created. The number of columns and the way that the default positions of items may be altered using this command. Also, the size of a dialog and the size of the dialogs grid can be changed using this command In addition the configuration of the standard control buttons can be controlled using the MODE parameter. The parameters that can be altered are: Parameter COLUMNS Description 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 BUTTONLAYOUT

Description 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). 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. 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. If true, within each column the labels of the dialog elements are right-aligned. 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. 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.

ALIGNCOLUMNS

ALIGNROWS

ALIGNITEMS BUSYONAPPLY

MODE

236

TSL Guide & Reference

Parameter WIDTH

Description 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. 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. 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.

HEIGHT

GRID

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 BUTTONCOLUMNS BUTTONLAYOUT COLUMNS ALIGNCOLUMNS ALIGNROWS ALIGNITEMS BUSYONAPPLY MODE Resource defaultButtonColumns buttonLayout defaultColumns alignColumns alignRows alignItems busyOnApply defaultMode Internal Default 1 COLUMNCENTRE 2 TRUE TRUE TRUE TRUE 0

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.

238

TSL Guide & Reference

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 label = quoted_string stringvar = TQL_variable_name choice_items = quoted_string { , quoted_string } | query_buffer_expansion | file_name query_buffer_expansion = column_name [/ count ] count = integer list_attributes = list_attribute { , list_attribute } list_attribute = ACTION = quoted_string | SENSITIVE = boolean_attribute | MINWIDTH = integer | MAXWIDTH = integer | SCROLLMODE = 0 2 | SELECTION_POLICY = SINGLE | BROWSE | MULTIPLE | RANGE | DISCONTIGUOUS | SELECTION_DELIM = quoted_string | SELECTION_MAXITEMS = integer | position_attribute Description This dialog item allows the user to make a choice from an enumerated list of options. These are displayed in a scrollable list in which size items are visible; the other items may be viewed by scrolling the list. The currently selected item is highlighted. If size is omitted, all items in the list are visible. In all three cases the choice is represented by a string. No other data types may be used with these dialog items. The list of choices may be specified in one of two ways:

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.

240

TSL Guide & Reference

Positioning The attributes, XPOS, YPOS, and so on, can be used to override or modify TSLs default positioning of these dialog items. Configuring the lists width and scroll bars LIST dialog items can also use the SCROLLMODE, MINWIDTH and MAXWIDTH attributes set the size of the width and to define how the lists scroll bars are managed: The SCROLLMODE attribute defines which scroll bars are enabled and when. The default is SCROLLMODE = 0, which enables a vertical scroll bar only when there are more items in the list than can be seen at a time. Setting SCROLLMODE to 1 enables the vertical scroll bar all the time. Scrollmodes 0 and 1 never have horizontal scroll bars. Setting the lists SCROLLMODE to 2 enables both horizontal and vertical scroll bars all the time. The width of the list automatically updates itself after a list command when SCROLLMODE is 0 or 1. The minimum and maximum widths of a list in characters are set using the MINWIDTH and MAXWIDTH attributes. If SCROLLMODE is set to 2that is, there is a horizontal scroll barTSL checks whether MAXWIDTH has been defined and uses this value to set the width of the list item. Otherwise it uses the value set for the MINWIDTH attribute. If neither were defined, the width of the widest item in the list is used. For more information on SCROLLMODE, see page 60. Selection policy The SELECTION_POLICY attribute specifies whether the user can select one or several items from the list. It may take the following values: Attribute SINGLE BROWSE Meaning Allows single selection. An item is selected by clicking on it. This is the default. 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 MULTIPLE RANGE

Meaning Allows multi-selection. An item is selected by clicking on it. 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. Allows multi-selection. Similar to RANGE but several ranges may be selected by pressing the Ctrl key while selecting ranges.

DISCONTIGUOUS

For list types that allow multi-selection, the maximum number of items that may be selected can be specified with the SELECTION_MAXITEMS attribute. By default, this is set to the number of items in the list. If the selection policy is MULTIPLE, RANGE or DISCONTIGUOUS, the TQL variable associated with the list is set to the selected values as a comma separated list. An alternative list delimiter can be set using the SELECTION_DELIM attribute. Three system variables hold information that aid in the processing of multiple selections:

%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

242

TSL Guide & Reference

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 varname = TQL_variable_name command = INSERT pos values | DELETE pos [num] | REPLACE pos [num] values | APPEND values | SAVE [filename] | READ [filename] | CLEAR pos = integer | quoted_string num = integer values = quoted_string { , quoted_string } | query_buffer_expansion query_buffer_expansion = column_name [/ count ] count = integer Description This command is used to change the contents of a list without having to recreate the entire dialog. This can only be done to a list in the current dialog, which must already have been displayed using the ASKDIALOG command. All the commands, except CLEAR, require parameters. The position in the list where the contents change can either be a string or a number. The INSERT command accepts any number greater than or equal to 0. The DELETE and REPLACE commands accept a number if it is greater than 0 and less than or equal to the number of items in the list. If a string is given, the string must exist in the list. If the position is invalid, the variable %LISTOK is set to FALSE and the list is not modified. Otherwise %LISTOK is set to TRUE and the list is updated. The APPEND and CLEAR commands do not require a position to be given and %LISTOK is always set to TRUE after executing one of these commands.

244

TSL Guide & Reference

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. QUERY DISPLAY param_name AS pname FROM setup WHERE batch = [batch_no] ; DIALOG LIST parmchosen APPEND pname/10 appends at most ten items from the column pname to the list identified by the variable parmchosen.

246

TSL Guide & Reference

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 label = quoted_string attributes = attribute { , attribute } attribute = SENSITIVE = boolean_attribute | READONLY = boolean_attribute | ALLOWNULL = boolean_attribute | NULL_ERR_MSG = quoted_string | MAXLEN = integer | position_attribute Description A multitext item is a multiline text editor in which the user can enter multiple lines of text and can use simple text editing capabilities. A multiline text item can only be used to display and edit string data. The size of the text item is controlled by specifying the number of columns in the item and the number of rows. The item is created at this size but the user can enter longer lines or more lines into the item in which case scroll bars are added automatically. Unlike the normal text dialog item, the maximum size of the string returned by the dialog item cannot be specified. The TSL script must be prepared to process a string up to the maximum allowable size of 4096 characters. If, when the dialog is processed, textvar is not defined or its value is not valid for a string, the field contents are initialised to an empty string. If the user changes the content of the text field, the system variable %DLOGCHANGED is set to TRUE. Note, however, that selecting the default or preselected value does not affect the value of %DLOGCHANGED. In

247

TSL Reference

addition, if, after editing a text field the user returns to the original value, %DLOGCHANGED is not updated. Text substitution is performed on size_spec, label and the values given with the SENSITIVE, READONLY, ALLOWNULL, NULL_ERR_MSG, MAXLEN, XPOS, YPOS, XADJUST, YADJUST and LABELGAP attributes. Activation Multiline text items cannot be made active, but they are validated when the user submits the dialog. Sensitivity The SENSITIVE attribute can be used to define whether or not the multiline text item can be selected or not. If it is insensitive, its contents cannot be modified or selected. The READONLY attribute is used to define whether or not the contents of the multiline text item can be changed. This defaults to FALSEthat is, the multiline contents of the text field can be changed by the user. The difference between an insensitive multiline text item and a readonly multiline text item is that the readonly multiline text item can be selected and its contents copied to another text field. Positioning The position of the multiline text item can be set by TSL or by using the positioning attributesXPOS, YPOS, and so on. Validation When the dialog is submitted (by pressing a button or activating an active dialog item) ASKDIALOG can test the values of multiline text items for NULL values, and not allow ASKDIALOG to return until a non-NULL value is entered for the multiline text item. This is done by setting the ALLOWNULL attribute to an expression that evaluates to FALSE. By default the ALLOWNULL attribute is set to TRUE. The error message generated can be determined by TSL, or you can set it yourself using the NULL_ERR_MSG attribute. TSL generates an error and exits if readonly is true and data validation failsthat is, ALLOWNULL evaluates to FALSE and the multiline text field is set to NULL. In addition, the maximum length of the string that may be put in the multiline text items can be defined using the MAXLEN attribute. If this is

248

TSL Guide & Reference

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 stringvar = TQL_variable_name label = quoted_string choice_items = quoted_string { , quoted_string } | query_buffer_expansion query_buffer_expansion = column_name [/ count ] count = integer option_attributes = option_attribute { , option_attribute } option_attributes = ACTION = quoted_string | SENSITIVE = boolean_attribute | position_attribute Description This dialog item allows the user to make a choice from an enumerated list of options which are displayed in a menu-pane. Only the value for the current selection is displayed in the dialog area. Other choices are viewed by displaying the menu. The choice is represented by a string. No other data types may be used with this dialog item. The list of choices may be specified in one of two ways:

Simply by specifying a list of strings. Text substitution is performed on each of these strings. 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 are 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 256k characters are retained, so if you have a very long list you may find that it has been truncated.)

250

TSL Guide & Reference

If, at the time that the dialog is processed, stringvar is not defined or does not have a valid value, the first item is selected. If the user makes a selection from the list of items, the system variable %DLOGCHANGED is set to TRUE. Note, however, that selecting the default or preselected value does not affect the value of %DLOGCHANGED. Text substitution is performed on label, choice_items and the values given with the ACTION, SENSITIVE, XPOS, YPOS, XADJUST, YADJUST and LABELGAP attributes. Activation If an ACTION attribute is defined, the dialog item is made active whenever the value of the option menu is changed. If the dialog item is made active, the value of the ACTION attribute is stored in the variable %BUTTONVAL and TRUE is stored in the %DIALOGVAL variable. Sensitivity The option menu dialog item can use the SENSITIVE attribute. An insensitive OPTION can not be selected and appears greyed out. Positioning The attributes, XPOS, YPOS, and so on can be used to override or modify TSLs default positioning of these dialog items. Examples DIALOG OPTION ingredient "Ingredient" "[ingred1]" \ "[ingred2]" "[ingred3]" "[ingred4]" creates an option menu with four choices. Note how the actual choices are obtained using text substitution. QUERY DISPLAY param_name AS pname FROM setup WHERE batch = [batch_no] ; DIALOG OPTION parmchosen "Parameter to Plot" pname/10 creates an option menu with at most 10 items where the items are obtained from a display query on the database. DIALOG OPTION parmchosen "Parameter to Plot" pname/10 \ ACTION = "Parm Selected" This creates an option menu, the contents of which are taken from the query buffer. If an item is selected from the option menu, ASKDIALOG

251

TSL Reference

validates any text dialog items. If this is successful, ASKDIALOG returns and puts Parm Selected in %BUTTONVAL and TRUE in %DIALOGVAL.

252

TSL Guide & Reference

DIALOG PANEL

Defines a selection panel and adds it to the current dialog


Syntax DIALOG [ STRING ] PANEL stringvar label choice_items \ [panel_attributes] Arguments stringvar = TQL_variable_name label = quoted_string choice_items = quoted_string { , quoted_string } | query_buffer_expansion query_buffer_expansion = column_name [/ count ] count = integer panel_attributes = panel_attribute { , panel_attribute } panel_attributes = ACTION = quoted_string | SENSITIVE = boolean_attribute | position_attribute Description This dialog item allows the user to make a choice from an enumerated list of options which are permanently displayed in the dialog area. Each has an indicator alongside which shows whether or not it is currently selected. Only one choice may be selected at a time. The choice is represented by a string. No other data types may be used with this dialog item. The list of choices may be specified in one of two ways:

Simply by specifying a list of strings. Text substitution is performed on each of these strings. 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 are 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 256k characters are retained, so if you have a very long list you may find that it has 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 %DLOGCHANGED is set to TRUE. Note, however, that selecting the default or preselected value does not affect the value of %DLOGCHANGED. Text substitution is performed on label, choice_items and the values given with the ACTION, SENSITIVE, XPOS, YPOS, XADJUST, YADJUST and LABELGAP attributes. Activation If an ACTION attribute is defined, the dialog item is made active whenever the value of the panel is changed or, if nothing was originally selected, when a value is selected. When the dialog item is made active the value of the ACTION attribute is stored in the variable %BUTTONVAL and TRUE is stored in the %DIALOGVAL variable. Sensitivity The panel dialog item can use the SENSITIVE attribute. An insensitive PANEL can not be selected and appears greyed out. Positioning The attributes, XPOS, YPOS, and so on, can be used to override or modify TSLs default positioning of these dialog items. Examples DIALOG PANEL output_dest "Output destination" \ "Plotter" "Screen" "HPGL file" creates a selection panel with three items. QUERY DISPLAY param_name AS pname FROM setup WHERE batch = [batch_no] ; 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", \

254

TSL Guide & Reference

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)

256

TSL Guide & Reference

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 label = quoted_string min = integer max = integer attributes = attribute { , attribute } attribute = ACTION = quoted_string SENSITIVE = boolean_attribute | position_attribute Description A slider allows the user to select a value between a specified minimum and maximum by moving a slider bar along a scale. It may be used only with integer data (TQL data types short or long). If no data type is specified, long is assumed. If slider_type is SLIDER or HSLIDER, the slider bar runs horizontally across the dialog. If slider_type is VSLIDER, the bar runs vertically. If size is present, it determines the length (in pixels) of the slider bar, otherwise the length is defaulted by the underlying window system. If, at the time the dialog is processed, var is undefined or its value is not valid for the specified data_type, the slider is initialised to the minimum value. If the value of the variable is out of range for the slider, it is rounded to the minimum or maximum as appropriate. If the slider is moved and a new value is selected, the system variable %DLOGCHANGED is set to TRUE. Note, however, that selecting the default or preselected value does not affect the value of %DLOGCHANGED. Text substitution is performed on size, label, min and max and on the values given with the ACTION, SENSITIVE, XPOS, YPOS, XADJUST, YADJUST and LABELGAP attributes.

257

TSL Reference

Activation If the ACTION attribute is defined, the dialog item is made active whenever the value of the slider is changed. If it succeeds, the value of the ACTION attribute is stored in %BUTTONVAL and TRUE in %DIALOGVAL. Sensitivity If the slider is insensitive, it cannot be selected or changed. By default, a slider is sensitive. Positioning The position of the slider can be determined by TSL or defined using the positioning attributes. Examples DIALOG VSLIDER(200) num_ticks "Number of ticks" 10 30 \ ACTION = "Changed Ticks" \ XADJUST = 3p, YADJUST = 5p DIALOG SHORT SLIDER x_axis_min "X axis minimum" \ [minval] [maxval] \ SENSITIVE = FALSE

258

TSL Guide & Reference

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 label = quoted_string attributes = attribute { , attribute } attribute = SENSITIVE = boolean_attribute | SECRET = secret_attr | READONLY = boolean_attribute | ALLOWNULL = boolean_attribute | NULL_ERR_MSG = quoted_string | RANGEMIN = TQL_variable_name | TQL_constant | quoted_TQL_expr | RANGEMAX = TQL_variable_name | TQL_constant | quoted_TQL_expr | RANGE_ERR_MSG = quoted_string | position_attribute secret_attr = TRUE | FALSE Description A text item is an editable text field in which the user can enter any character sequence. A text item may be used to display and edit data of any type. In addition to the standard data_type arguments, the DIALOG TEXT command may take an AUTO type. This allows users to type any valid TQL expression in a text field. The expression is then checked and assigned to the appropriate data type. A text field has a display width (the number of characters visible in the field) and a maximum width (the number of characters that can be entered in the field), which are determined by display_length and

259

TSL Reference

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 %DLOGCHANGED is set to TRUE. Note, however, that selecting the default 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, YADJUST and LABELGAP attributes. 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.

260

TSL Guide & Reference

Positioning The position of the dialog can either be set by TSL or defined by you using the positioning attributes. Secrecy You may want to display an asterix (*) each time a character is entered in a text field, for example, when passwords are entered. If the SECRET attribute evaluates to TRUE, text entered in the TEXT field is not displayed. The default value for this attribute is FALSE. Validation When the dialog is submitted, the ASKDIALOG command can check for invalid NULL values and values out of range in text fields. If you wish TSL to test for NULL values, set ALLOWNULL so that it evaluates to FALSE. You can specify the error message to display if a NULL value is detected using the NULL_ERR_MSG attribute otherwise TSL generates its own message. Range checking is performed if either or both the RANGEMIN and RANGEMAX attributes are defined. An error is reported if a value is entered that is less than the RANGEMIN attribute or greater than the RANGEMAX attribute. The error message generated can be defined using the RANGE_ERR_MSG attribute otherwise TSL determines its own error message. TSL generates an error if the text field is readonly and its contents are invalid. Examples DIALOG DATE TEXT(8) date1 "Start Date" \ READONLY = TRUE DIALOG TEXT(15,60) outfile "Output File" DIALOG COMPLEX TEXT(12) sensor_pos "Sensor Position" \ RANGEMIN = \[3,5], RANGEMAX = \[10,4]

261

TSL Reference

DIALOG TIMERANGE

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 label = quoted_string attributes = attribute { , attribute } attribute = ACTION = quoted_string | SENSITIVE = boolean_attribute | GRANULARITY = short | MAXRANGES = short | position_attributes Description This dialog item allows the user to define multiple time ranges within one day. The item is displayed as a horizontal bar with 24 points denoting hours in the day. To define a time range, the user clicks on the bar and drags the cursor to the beginning or end time of the range. As the user defines a range, it is displayed below the barfor example, 9:4511:00. Note that the user cannot overlap time ranges or join two existing time ranges. However, he or she can modify an existing range by dragging its beginning or end time markers and delete a range by dragging a beginning or end time marker over the other marker that defines the range. The rangevar variable stores the ranges that have been selected as an array of TQL times. The start and end times of each time range are stored in consecutive pairs within the arraythat is, the first element is the start of range 1, the second element is the end time of range 1, the third element is the start of range 2, and so on. If the user does not define any time ranges, rangevar is a one element array where the time value is NULL. If, at the time of creation, the rangevar variable contains an array of times, these are used as an initial set of ranges and displayed by the dialog item.

262

TSL Guide & Reference

Note that, unlike most other dialog items, if the user creates a new time range or changes an existing one, the value of %DLOGCHANGED is not affected. Therefore, using this item in a dialog may give unexpected results when used in conjunction with %DLOGCHANGED. Text substitution is performed on label and on the values given with the ACTION, SENSITIVE, GRANULARITY, MAXRANGES, XPOS, YPOS, XADJUST, YADJUST and LABELGAP attributes. Activation If the ACTION attribute is defined, the dialog item is made active whenever a new time range is created, modified or deleted. If the dialog item is made active, the value of the ACTION attribute is stored in the variable %BUTTONVAL and TRUE is stored in the %DIALOGVAL variable. Sensitivity If the SENSITIVE attribute evaluates to FALSE, the dialog item is insensitivethat is, it is greyed out and the user cannot select it. Accuracy and number of time ranges The GRANULARITY attribute defines the smallest unit, in minutes, with which the user can define the start and end times of a range. A unit is always defined in minutes but may be greater than one hour. The default is 15. The MAXRANGES attribute defines the number of ranges the user can define. The maximum number of ranges that can be defined is dependent on the value of GRANULARITY. The default is 50. Positioning The position of the time range bar can either be determined by TSL or defined by position_attributes. Example DIALOG TIMERANGE shop_hours "Opening Hours" \ GRANULARITY=5, MAXRANGES=2 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 label = quoted_string attributes = attribute { , attribute } attribute = ACTION = quoted_string | SENSITIVE = boolean_attribute | position_attribute Description A toggle is a user interface item with two states, On and Off, and is used for input/output of boolean data (TQL data type bool). If, at the time the dialog is processed, the variable boolvar does not exist or does not have a valid boolean value, the toggle is initialised to the Off state. If the user changes the toggle value, the system variable %DLOGCHANGED is set to TRUE. Note, however, that selecting the default or preselected value does not affect the value of %DLOGCHANGED. Text substitution is performed on label and the values given with the ACTION, SENSITIVE, XPOS, YPOS, XADJUST, YADJUST and LABELGAP attributes. Activation If the ACTION attribute is defined and the value of the toggle changes, ASKDIALOG submits the dialog. If this succeeds, ASKDIALOG returns and stores the value of the ACTION attribute in the %BUTTONVAL variable and TRUE in the %DIALOGVAL variable. Sensitivity The SENSITIVE attribute defines whether the toggle can be selected and its value changed. By default, toggle items are sensitive.

264

TSL Guide & Reference

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.

266

TSL Guide & Reference

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.

268

TSL Guide & Reference

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.

270

TSL Guide & Reference

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. If no graphics canvas exists, a CANVAS ON command is executed automatically. If no graph exists, a default graph is created automatically.

271

TSL Reference

GRAPH DRAW

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 0 3 11 Description The command was executed successfully. Kingfisher was busy executing on behalf of another client. The query did not or could not return any data.

272

TSL Guide & Reference

If no graphics canvas exists, a CANVAS ON command is executed automatically. If no graph exists, a default graph is created 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 one of the following: Value 0 Description The command was executed successfully.

274

TSL Guide & Reference

Value 3 4 5 6

Description Kingfisher was busy executing on behalf of another client. 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. If no graphics canvas exists a CANVAS ON command is executed automatically. If no graph exists, a default graph is created automatically. Example GRAPH FORMAT LOAD spectra 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 geometry = x_position y_position width height Description The GRAPH POSITION command sets the position and size of the current graph. The geometry controls the initial placement and size of the graph in the canvas window. The geometry is specified as a sequence of four numbers corresponding to the X position, Y position, width and height. The position is specified as a percentage of the canvas with 0,0 at the top left; the size is specified in percentage of the canvas. Any or all of the numbers can be replaced by an asterisk indicating that the default position or size is to be used. The default is 0 0 100 100. Text substitution is performed on geometry. If the current graph contains datathat is, a GRAPH DRAW command has been executedand canvas graph edit mode is not enabled, the graph is destroyed. If edit mode is enabled, the graphs position is changed and the graph is automatically redrawn. If no graphics canvas exists, a CANVAS ON command is executed automatically. If no graph exists, a default graph is created automatically. Example GRAPH POSITION 0 0 50 100 positions the graph in the right hand half of the canvas.

276

TSL Guide & Reference

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. If the command is followed by the SET modifier, or by no modifier, the command sets valuesthat is, it changes the graph format. The property_value_list consists of one or more property names, each followed by an optional qualifier, an equals sign and the appropriate value for that property. The qualifier is a number introduced by a forward slash. The value can either be a number, quoted string or a TQL variable which has been set to either a number or a string. The correct type and range of values for a property, as well as the names of all graph properties, are described in Chapter 9 of the Kingfisher Reference. Text substitution is carried out on property_value_list. If the command is followed by the GET modifier, the command obtains values from the graph format. The property_var_list consists of one or more property names, each followed by an optional qualifier, an equals sign and then the name of a TQL variable. The qualifier is a number introduced by a forward slash. The value of each property named is retrieved and stored in the associated TQL variable. The value is either an integer (long), a real or a string. If the variable does not exist it is created automatically. Text substitution is carried out on property_var_list.

277

TSL Reference

If no graphics canvas exists, a CANVAS ON command is executed 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.

278

TSL Guide & Reference

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. If the environment variable TB_SPEC_PATH is defined, each directory on this path is searched in turn. The current directory is searched.

Otherwise:

Otherwise:

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

280

TSL Guide & Reference

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 Bold Underline Emphasis User1 User2 Indicator @B @U @E @1 @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 Bold Underline Emphasis User1, User2 Effect Printed in font specified by boldFont resource Underlined Simulation of Half-bright using the colour specified by the halfBright resource 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.

282

TSL Guide & Reference

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,

284

TSL Guide & Reference

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

286

TSL Guide & Reference

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.

288

TSL Guide & Reference

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 0 1 2 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. If no graphics canvas exists, a CANVAS ON command is executed 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

290

TSL Guide & Reference

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.

292

TSL Guide & Reference

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 attributes = attribute { , attribute } attribute = ACTION = quoted_string | SENSITIVE = boolean_attribute Description menu_id identifies the position of the menu item in the menu hierarchy. For a top level menu item (that is an item whose label appears on the menu bar of the application) the menu-id is a single integer giving the position in the menubar. Items are numbered starting from the left, starting with 1. Each item on the menubar may have up to four levels of pull-down menus associated with it. For a menu item appearing in the nth level of pull-down menus the menu-id comprises a dash-separated sequence of n+1 integers. The last integer in this sequence gives the position of the item in the menu-pane in which its label appears. The preceding characters give the menu-id of the item in the higher level menu from which the menu-pane was generated. By default, a menu pane at any level of the hierarchy may contain at most 20 items. However, this limit may be changed using the maxMenuItems application resource. Menu items may be defined in any order. If a menu-id is used in more than one MENU command, the last definition takes precedence. The menu_label can contain the special character @ to indicate a mnemonic for the menu entry. The first occurrence of the character after the @ is taken as the mnemonic and is underlined in the menu, thus the label Print @Report underlines the R in Report and the label Print Repo@rt underlines the r in Print.

294

TSL Guide & Reference

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 until a menu item or a tool is pressed. When this happens, the variable %MENUVAL is set to the action string of the menu item (or tool) that was selected. The menus action string is set using the ACTION attribute but defaults to the string containing menu_id. For example: 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.

296

TSL Guide & Reference

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.

298

TSL Guide & Reference

PAGESTYLE

Defines the attributes of the current pagestyle


Syntax PAGESTYLE attributes Arguments attributes = attribute { , attribute } attribute = STARTLINE = integer | ENDLINE = integer | HEADLINE = integer | FOOTLINE = integer | HEADER = quoted_string | FOOTER = quoted_string | LENGTH = integer | LMARGIN = integer | RMARGIN = integer Description The PAGESTYLE command can be used to set the page style attributes of the current pagestyle. The meanings of the attributes are: Attribute STARTLINE ENDLINE HEADLINE FOOTLINE HEADER FOOTER LENGTH LMARGIN RMARGIN Meaning The first line on which the main text is printed The last line on which the main text is printed The line on which to start printing the header The line on which to start printing the footer The header string The footer string The length of a page The first column on which text is printed 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 STARTLINE ENDLINE HEADLINE FOOTLINE HEADER FOOTER LENGTH LMARGIN Default value 2 Same as LENGTH attribute. No default. No default. No default. No default. 65 or the length set by the last LENGTH command. 4 or the default left margin value set by the last MARGIN command. 1 or the default right margin value set by the last MARGIN command.

RMARGIN

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"'

300

TSL Guide & Reference

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.

302

TSL Guide & Reference

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 d 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.

o x

304

TSL Guide & Reference

Character f

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.

c s v %

If the data item is a complex number, the following characters can be used: Character x y 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 a A 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 b B d D e h H I j m M n R S t T w y Y

Description The abbreviated month name for the current locale (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. The abbreviated month name for the current locale (for example, Jan). Hour of the day, in the format 00 to 23. Hour of the day, in the format 01 to 12. 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).

306

TSL Guide & Reference

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 attributes = attribute { , attribute } attribute = OUTPUT = ( PRINTER | PIPE | FILE ) | FILENAME = quoted_string | COMMAND = quoted_string | APPEND = ( TRUE | FALSE | YES | NO ) Description After execution of a PRINTER ON command, all text output is sent to the current printer (which may be a printer, file or pipe) rather than the TSL terminal window, until a PRINTER OFF is executed. The current printer defaults to the output destination selected when the TSL interpreter was started, and is set using the SETPRINTER command. If the printer is turned on and off several times during the execution of a script, a separate print job is created each time. The PRINTER command is also used to define the attributes of the current printer (see SET-PRINTER on page 331). The destination of the output is specified using the OUTPUT attribute. If the destination is a file, the OUTPUT attribute should be defined as FILE and the name of the file should be defined with the FILENAME attribute. Normally when a file is opened for the first time, TSL overwrites the file. However, if you would prefer to append your output to the end of the file, define the APPEND attribute as TRUE. If the destination is either a command or a printer, OUTPUT should be defined appropriately and the command executed should be defined with the COMMAND attribute. Initially the printer is turned off, so all output is sent to the TSL main window. This command also redefines a special TQL macro %OUTPUT. This is defined to the name of the current output destination. When output is going to the screen (PRINTER OFF or no logical printer specified) %OUTPUT is defined as screen. When the PRINTER is on and the logical

308

TSL Guide & Reference

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 12000 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.

310

TSL Guide & Reference

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.

312

TSL Guide & Reference

Note that in each case the termination condition is checked only at the end of the loop so the commands which form the body of the loop are executed at least once. The NOTRAP modifier If during the execution of the loop, the user presses q in response to a --More-- prompt (see MORE on page 297), the usual behaviour is to abort the loop and continue execution with the command immediately after the end of the loop. Specifying the NOTRAP modifier at the start of the loop prevents the loop from being aborted in this fashion. For nested loops the loop aborted in response to q is the innermost loop for which NOTRAP was not specified. If paging mode is disabled, NOTRAP has no effect. REPEAT loops may be nested to a maximum depth of 20. The start and end of a loop must be in the same script file. Thus it is not permissible to begin a loop within an included file and to end it in the including file. Examples REPEAT '[exp_no] [exp_result] NEXT FORALL prints the values of exp_no and exp_result for each row in the query buffer. REPEAT '[exp_no] [exp_result] NEXT FOR 10 As above put prints at most 10 rows of data. REPEAT '[exp_no] [exp_result] 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 QUERY DISPLAY exp_no, exp_result \

313

TSL Reference

FROM rsltdata WHERE batch = [batch_no] ; 'Batch Number: [batch_no] REPEAT NOTRAP '[exp_no] [exp_result] 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.

314

TSL Guide & Reference

REPORT

Defines the attributes of the current report or turns reporting on


Syntax REPORT [ ON | OFF | attributes ] Arguments attributes = attribute { , attribute } attribute = FIRST = 1 30 | LEFT = 1 30 | RIGHT = 1 30 | DEFAULT = 1 30 Description The REPORT command can be used to switch report mode on and off, or to define the attributes of the current report style. The current report style is set using SETREPORT. Reporting is enabled using the REPORT ON command. When this command the variable %PAGENUM is set to 1. This variable is updated as more pages are printed and can be used in a pagestyles HEADER or FOOTER attributes (see PAGESTYLE on page 299). The %PAGENUM variable is dropped when reporting is disabled using the REPORT OFF command. LEFT and RIGHT define the page style to use for left (even numbered) and right (odd numbered) pages, respectively. FIRST defines the style for the first page, and DEFAULT gives the pagestyle use for any page whose style is otherwise undefined. 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.

316

TSL Guide & Reference

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.

318

TSL Guide & Reference

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 directory on this path is searched in turn. If the environment variable TB_SPEC_PATH is defined, each directory on this path is searched in turn;

Otherwise:

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

320

TSL Guide & Reference

SELECT

Displays a list selection dialog


Syntax SELECT text_label choice_items Arguments text_label = quoted_string choice_items = { quoted_string } | query_buffer_expansion query_buffer_expansion = column_name [/ count ] count = integer Description Pops up a list selection dialog whose scrolled list contains the choice_items and whose text field is labelled with text_label and suspends the application until the dialog is dismissed. The selection dialog has buttons labelled OK and Cancel. If the user presses the OK button and the text field is not empty, the special variable %SELECTVAL is set to the value otherwise it is set to NULL. In addition, if the OK button is pressed, %DIALOGVAL is set to TRUE and %BUTTONVAL is set to OK. If the Cancel button is pressed, %DIALOGVAL is set to FALSE and %BUTTONVAL is set to Cancel If you do not want the %DIALOGVAL and %BUTTONVAL variables to be set, set the environment variable TSL_13_COMPATIBILITY to 1. The list of choices may be specified in one of two ways:

Simply by specifying a list of strings. Text substitution is performed on each of these strings. 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 are 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 256k characters are retained, so if you have a very long list you may find that it has 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

322

TSL Guide & Reference

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.

324

TSL Guide & Reference

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 %GRFOCUSSED %GRSELECTED The number of graphs in the canvas. The graph with the data focus. 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

326

TSL Guide & Reference

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 dialog_number = 1 200 dialog_name = string Description The default number of dialogs that may be defined at any one time is 200. However, this limit may be changed using the maxDialogs application resource. All DIALOG (item), DIALOG SKIP and DIALOG LAYOUT commands apply to the current dialog. If no SETDIALOG command has been executed, the most recently defined dialog is used. Text substitution is performed on dialog_number and dialog_name. Example SETDIALOG 3 sets dialog 3 as current. Subsequent commands apply to that dialog. SETDIALOG setup_graph sets the dialog named setup_graph as current.

328

TSL Guide & Reference

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

330

TSL Guide & Reference

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

332

TSL Guide & Reference

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.

334

TSL Guide & Reference

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

336

TSL Guide & Reference

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.

338

TSL Guide & Reference

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 BYTE, SHORT, LONG Printing description Right-justified within the field.

340

TSL Guide & Reference

Data type SHORTREAL, REAL

Printing description Right-justified within the field. If fraction length not specified or too long for field width, number is printed in e-format. Output as one of the strings Yes, No (or their equivalent in the users Local Language environment). Left-justified within the field. 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. 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. 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.

BOOL

STRING, CHAR TIME

DATE

COMPLEX

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]

342

TSL Guide & Reference

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()]"

344

TSL Guide & Reference

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 label = quoted_string primary_bitmap = bitmap_file active_bitmap = bitmap_file attributes = attribute { , attribute } attribute = ACTION = quoted_string | SENSITIVE = boolean_attribute Description The TOOL command is used to either define the label positioned on top of a group of tools or to define a tools bitmap(s) and attributes. The first command given above is used to define the label of the tool group numbered groupnum to be label. The second command defines a tool in position of toolgroup to use the bitmap file primary_bitmap as its inactive bitmap. Each tool must have its ACTION attribute defined. When a tool is pressed, if the optional bitmap active_bitmap is defined, the bitmap displayed is changed to active_bitmap. The values primary_bitmap and active_bitmap are bitmaps which are searched for in the directories specified by the XBMLANGPATH environment variable. See Icons on page 20 for a description of this environment variable. A tool is activated by pressing and releasing the tool whilst the mouse is over the tool when an ASKMENU command is been executed. When a tool is activated the ASKMENU command ends and the value associated with the tools ACTION attribute is put in the %MENUVAL variable. The sensitivity of the tool is defined by the SENSITIVE attribute. Insensitive tools appear the same as sensitive tools but users cannot select insensitive tools.

345

TSL Reference

Examples TOOL 1 "Kingfisher" 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.

346

TSL Guide & Reference

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 GRAVITY Description 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. Defines the maximum number of rows in each tool group if GRAVITY is NORTH or SOUTH or the maximum number of columns in each tool group if GRAVITY is EAST or WEST. Defines whether each tool group should have a box drawn around it. Default value EAST

ROWCOLS

1 if GRAVITY is NORTH or SOUTH, 2 otherwise

FRAME

True

347

TSL Reference

Attribute GROUPGAP

Description Defines the distance that exists between the last tool in the previous tool group and the current tool groups label. Defines the distance that exists between each tool in all of the tool groups.

Default value 10p (ten pixels)

TOOLGAP

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).

348

TSL Guide & Reference

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 one of the following: Value 0 1 Description The command was executed successfully. 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 4 5

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.

350

TSL Guide & Reference

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. If the command is followed by the SET modifier, or by no modifier, the command sets valuesthat is, it changes the transfer configuration. The property_value_list consists of one or more property names, each followed by an equals sign and the appropriate value for that property. The value can either be a number or a quoted string. The correct type and range of values for a property, as well as the names of all transfer properties, are described in Chapter 8 of the Kingfisher Reference. Text substitution is carried out on property_value_list. If the command is followed by the GET modifier, the command gets values from the transfer configuration. The property_var_list consists of one or more property names, each followed by an equals sign and the name of a TQL variable. The value of each property named is retrieved and stored in the associated TQL variable. The value is either an integer (long), a real or a string. If the variable does not exist it is created automatically. Text substitution is carried out on property_var_list. Example TRANSFER PROPERTY delimiter=";" terminator=0 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.

352

TSL Guide & Reference

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.

354

TSL Guide & Reference

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.

358

TSL Guide & Reference

Warnings

Warnings
In addition to the fatal errors, TSL may issue warning messages. These do not cause the TSL interpreter to exit and are simply echoed to the terminal and the TSL log file.

Errors
#1 Failed to obtain query buffer The TSL application could not get a query buffer of the size requested. There may be insufficient virtual memory availabletry again with a smaller buffer size or when the system is less heavily loaded. Alternatively the system limit of shared memory segments may have been reached. Use ipcs to check the current shared memory status and ipcrm to remove any redundant segments. If this happens frequently you may need to consider reconfiguring your UNIX kernel to allow more shared memory segments. #2 Insufficient memory There was insufficient virtual memory available for the TSL interpreter. Try running again when the system is less heavily loaded. #3 This error number is not used in the current version of Metrica/NPR. #4 Cant open input file <filename> The specified TSL script file <filename> could not be opened. Check that the file can be found on TB_TSL_SPEC_PATH or TB_SPEC_PATH and that you have read permission for the file. #5 Cant open output file The file specified for text output cannot be opened. Check that you have write permission in the directory containing the file and, if the file exists, on the file itself. Can occur during PRINTER ON commands. #6 This error number is not used in the current version of Metrica/NPR. #7 End of loop with no start of loop A FOR, FORALL, UNTIL, or ENDLOOP was encountered before a REPEAT, WHILE statement had been executed. #8 Bad fork in shell escape The command specified in a SHELL statement could not be executed or returned a non-zero exit code.

359

Appendix

Error Messages

#9 Document aborted by user The document was aborted prematurely using the window-manager or a user interrupt. #10 Token or command too long The maximum length of a token (e.g the text for a QUERY) is limited to 16384 characters. #11 Unknown TSL command <command> TSL was expecting a command, instead it found <command>. #12 Unknown enhancement (@<enhancement>) Current valid printer enhancements are @B,@U,@E,@1 and @2. #13 Cant access terminal TSL terminates with this error if it fails to initialise the terminal window or if a TELL command fails. #14 Invalid condition in IF/UNTIL The condition evaluated as part of an IF or UNTIL statement returned NULL or a non-boolean value. #15 Badly formed or nested IF An ELSE, ELIF or ENDIF was encountered with no matching IF, or the end of a script file was reached with an IF statement still unterminated. #16 Error in QUERY The TQL Server detected an error during the execution of query. The TQL errors should give further information. #17 This error number is not used in the current version of Metrica/NPR. #18 Unable to load user help file <filename> The help file <filename> could not be opened. Check that the file can be found on TB_TSL_SPEC_PATH or TB_SPEC_PATH and that you have read permission for it. #19 Expected quoted string TSL expected to find an argument to a command given in double or single quotes. #20 Menu system is already built A MENU, TOOL or TOOLBOX command may not be executed once an ASKMENU has been executed.

360

TSL Guide & Reference

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 #30 Unfinished query in included file The end of an included file was reached with no terminating semi-colon found on a QUERY command.

361

Appendix

Error Messages

#31 End of loop not found The end of a script file was reached with a REPEAT or WHILE loop still unterminated. #32 This error number is not used in the current version of Metrica/NPR. #33 Badly formed or nested SWITCH A CASE, OTHERWISE or ENDSWITCH was encountered with no matching SWITCH, or the end of a script file was reached with an SWITCH statement still unterminated. #34 You cannot create more than <n> dialogs A maximum of n dialogs can be created in a TSL application. Attempting to define more dialogs gives this error message. #35 The dialog to manipulate has not been created An ASKDIALOG command was attempted on an undefined dialog. This error also occurs if a CLOSEDIALOG is attempted on a dialog that has not been displayed. #36 Illegal number of columns for dialog (Min=1, Max=30) The number of columns in a dialog (as set by the DIALOG LAYOUT command) must be in the range 1 to 30 inclusive. #37 Cannot set number of columns once dialog already built The DIALOG LAYOUT command can only be used on a dialog for which no dialog items have currently been defined. #38 Bad dialog LAYOUT specification One (or more) of the specified layout options was not recognised or was given an invalid value. #39 Only NOTRAP is allowed after REPEAT An unexpected string was found after the REPEAT keyword. #40 Expected variable name after dialog type A TQL variable name must be specified for all dialog item types except labels. #41 This error number is not used in the current version of Metrica/NPR. #42 This error number is not used in the current version of Metrica/NPR.

362

TSL Guide & Reference

Errors

#43 This error number is not used in the current version of Metrica/NPR. #44 Incorrect TQL server revision The TQL Server you are using is too old a revision to be used with your version of TSL. Refer to the release notes accompanying your system to determine the supported combinations. #45 Bad expression in SWITCH An error occurred when trying to evaluate the expression for a SWITCH statement. The TQL error messages should give further information. #46 TQL server is not authorised for TSL The TQL Server you connected to is not authorised for use with TSL. If you have a licence entitling you to use TSL, contact your distributor to obtain a new security code. #47 Illegal arguments - too long or out of range The arguments to a CANVAS or GRAPH command were out of range e.g a graph size larger than 100% was specified. #48 Failed to start Kingfisher or make connection TSL was unable to start the Kingfisher display window either because the executable could not be found or executed or because it was the wrong version. #49 Kingfisher display has not been started A CANVAS or GRAPH command was executed when no display window was connected. #50 Connection lost or Kingfisher exited The user has probably closed the Kingfisher display window using the window manager. #51 Illegal/failed operation on display/graph TSL terminates with this error if there was an unexpected Kingfisher error while TSL was communicating with Kingfisher to carry out a CANVAS or GRAPH command. #52 Graph not defined The graph specified by TSL was not recognised by Kingfisher. #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

363

Appendix

Error Messages

codes are set in the special variables %QERR, %DERR and %FERR and the error messages are stored in %QMSG. %DMSG and %FMSG. #54 Graph for DRAW command must be last created Kingfisher only allows datasets to be added to the last graph that has been created and not to the currently selected graph. #55 Graph ID out of range in SETGRAPH TSL supports graph identifiers ranging from 1 to 50. #56 Unknown graphics command A word following a GRAPH or CANVAS command has not been recognised by TSL as a valid sub-command. #57 Expected property name TSL expected to read in an attribute name = value pair but was unable to find an attribute name. #58 Expected a qualifier for the property TSL expected to read in an attribute name = value pair but was unable to find an attribute value. #59 Bad property-value syntax The syntax of a GRAPH PROPERTY, CANVAS HARDCOPY or TRANSFER PROPERTY command was incorrect. #60 Unrecognised graphics option An invalid mode was given in a CANVAS MODE command, or the position and resizing values in a CANVAS RESIZE command were not specified as integers. #61 Unknown display mode The mode specified in a CANVAS MODE command is not known. #62 Property/mode value is of incorrect type Every property has a data type, either string, integer or real. You have specified a value of incorrect type. Check the data type in the Kingfisher Reference. #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.

364

TSL Guide & Reference

Errors

#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. #74 Expected ICON or quoted string The DIALOG BUTTON DEFAULT command must be followed by the keyword ICON or by a quoted string.

365

Appendix

Error Messages

#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. #86 Missing argument before , The arguments or parameters in a CALL command were specified incorrectlyno argument was found before the first comma.

366

TSL Guide & Reference

Errors

#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. #99 Unknown attribute in TOOLBOX Acceptable attributes for TOOLBOX are GRAVITY, ROWCOLS, FRAME, GROUPGAP and TOOLGAP.

367

Appendix

Error Messages

#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.

368

TSL Guide & Reference

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.

370

TSL Guide & Reference

Errors

#138

A dialogs width should be smaller than the width of the screen This error message is not used in the current version of Metrica/NPR. #139 A dialogs height should be larger than 0 This error message is not used in the current version of Metrica/NPR. #140 A dialogs height should be smaller than the height of the screen This error message is not used in the current version of Metrica/NPR. #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 This error message is not used in the current version of Metrica/NPR. #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.

372

TSL Guide & Reference

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 #180 #181 Button/dialog item sensitivity evaluates to NULL Dialog item READONLY attribute evaluates to NULL 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 This error number is not used in the current version of Metrica/NPR.

374

TSL Guide & Reference

Errors

#190 This error number is not relevant to the current version of Metrica/NPR. #191 This error number is not relevant to the current version of Metrica/NPR. #192 This error number is not relevant to the current version of Metrica/NPR. #193 This error number is not relevant to the current version of Metrica/NPR. #194 This error number is not used in the current version of Metrica/NPR. #195 Data provided is invalid The data provided is not valid for the operation requested. #196 This error number is not relevant to the current version of Metrica/NPR. #197 This error number is not relevant to the current version of Metrica/NPR. #198 This error number is not relevant to the current version of Metrica/NPR. #199 This error number is not relevant to the current version of Metrica/NPR. #200 This error number is not relevant to the current version of Metrica/NPR. #201 This error number is not relevant to the current version of Metrica/NPR. #202 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.

376

TSL Guide & Reference

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 The status returned by Kingfisher after performing a TRANSFER command indicated that the specified pipe or file could not be written to. TSL will not terminate but the TRANSFER command may not have been successful. Label truncated to <label> (60 characters) A label in a dialog was too big and has been truncated to <label>. Motif Window Manager is not running If the Motif version of TSL is started but the Motif window manager is not running, this warning message is printed. The application will

377

Appendix

Error Messages

continue to run but some aspects of the user interface may not behave as expected. Normal and bold fonts have different heights Normal and bold fonts have different widths The fonts specified as the bold and normal fonts for the terminal window must have identical height and width. If they do not the application continues but uses the normal font for both normal and bold text. Overflow in text expansion for list item When the items in a list, option menu or panel are obtained via a query buffer expansion the total length of the expanded items is limited to 16384 characters. Property settings and data are incompatible Check the property name and the valid values in the Kingfisher Reference manual. Property value out of range Check the property name and the valid values in the Kingfisher Reference manual. Query buffer is too small - use -buffersize There is insufficient space in the query buffer for the operation. Rerun TSL using the -buffersize command line argument to increase the buffer size. Timed out waiting for connection TSL could not establish a connection to the Kingfisher display window. Check that a Kingfisher display has been started. UNIX command failed in transfer pipe The status returned by Kingfisher after performing a TRANSFER command indicated that the specified pipe could not be opened. TSL will not terminate but the TRANSFER command may not have been successful. Unknown property name Check the property name and the valid values in the Kingfisher Reference manual.

378

TSL Guide & Reference

Warnings

Unknown table in TRANSFER command The status returned by Kingfisher after performing a TRANSFER 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 application defined buttons 63 and ASKDIALOG command 203 and convenience dialogs 4446 and DIALOG BUTTON command 230 and DIALOG LIST command 240 and DIALOG OPTION command 251

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 %DISPLAY system variable 310 %DLOGCHANGED variable and ASKDIALOG command 202 and calendars 231 and printing reports 114 and timerange bars 263 purpose of 47 %DMSG variable 272 and ABORT command 189 and GRAPH DRAW errors 135 and QUERY command 310 database level message 158 error messages 364 %FERR variable 272, 310 and ABORT command 189 and GRAPH DRAW command 135 error messages 364 file level error code 157 %FILEVAL variable and file selection dialog 45 and SELECTFILE command 323 %FMSG variable and ABORT command 189 and GRAPH DRAW command 135, 272 and QUERY command 310 error messages 364 filer level message 158 %GRFOCUSSED variable 147 %GRSELECTED variable 147 %GRSTATUS variable 272 and CANVAS COLOURMAP command 211

381

Index

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 DIALOG LIST command 244 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 printing reports 110 and REPORT command 315 %QERR variable and ABORT command 189 and GRAPH DRAW command 135, 272 and QUERY command 310 and query errors 157 description of 157 error messages 364 %QMSG variable and ABORT command 189 and GRAPH DRAW command 135, 272 and QUERY command 310 description of 158 error handling 158 error messages 364 %QOK variable 272

and ABORT command 189 and abort mode 156 and GRAPH DRAW command 135 and QUERY command 310 error handling 156 %ROWS variable and printing reports 100 and QUERY command 310 number of rows in query buffer 90 %SELECTED system variable 60, 242 %SELECTVAL variable and list selection dialog 44 and SELECT command 321 %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 and GRAPH CURSOR command 271 stores cursors Y value 140142 %ZVAL variable and GRAPH CURSOR command 271 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 terminate script on GRAPH DRAW errors 135 accelerator defining 30

382

TSL Guide & Reference

ACTION attribute and %BUTTONVAL 203 and application defined buttons 230 and DIALOG LIST command 240 and DIALOG OPTION command 251 and DIALOG PANEL command 254 and DIALOG SLIDER command 258 and DIALOG TOGGLE command 264 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 set in application defaults file 163, 195 set with DIALOG LAYOUT command 236 ALIGNROWS 163 ALIGNROWS attribute description of 68 set in application defaults file 163, 195 set with DIALOG LAYOUT command 236 ALLOWNULL attribute and ASKDIALOG command 202 and DIALOG MULTITEXT command 248 and DIALOG TEXT command 261 check for NULL values in text fields 180 error messages 368, 369, 374 range checking in text fields 5355 syntax conventions 188 when evaluated 19 and DIALOG OPTION command 251 and GRAPH DRAW command 272 and PRINTER command 308

and QUERY command 310 APPEND attribute and PRINTER command 111, 308 error messages 372 APPEND command and DIALOG LIST command 244 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 and DIALOG BUTTON command 230 placing application defined buttons 63 ASK command 201 ASKDIALOG command 56 activating the current dialog 4648 and DIALOG BUTTON command 230 and DIALOG MULTITEXT command 248 and DIALOG TEXT command 261 and DIALOG TOGGLE command 264 and TIMEOUT command 158, 343 attributes always evaluated when called 19 changing control buttons 74

383

Index

description of 202204 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, 368 GRAVITY 32, 164, 165, 196, 347, 368 GRID 71, 237 GROUPGAP 32, 164, 196, 347348, 368 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, 368 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, 368 WIDTH 70, 237 XADJUST 71, 73, 371 XORIGIN 7173 XPOS 7173, 371 YADJUST 71, 73, 371 YORIGIN 7173 YPOS 7173, 371

B
backslash character 14 BEEP command 206 bitmap, creating bitmaps 20 BREAK command

384

TSL Guide & Reference

and loops 312 description of 207 buffer copying screen output to 208 query buffer 90 setting the current 325 BUFFER command description of 208 error messages 376 printing reports from a buffer file 114 building, see creating BUSYONAPPLY attribute defines appearance of insensitive dialog 76 set in application defaults file 164, 196 set with DIALOG LAYOUT command 236 BUTTONCOLUMNS attribute description of 68 set in application defaults file 164, 195 set with DIALOG BUTTON command 230 set with DIALOG LAYOUT command 235 BUTTONLAYOUT attribute description of 68 set in application defaults file 164, 196 set with DIALOG LAYOUT command 236 buttons application defined 76 changing control buttons 74

C
CALL command calling procedures 1012 description of 209 error messages 365 canvas description of 122 modes 122 CANVAS CLEAR command 130 and multiple graphs 144 description of 210 CANVAS COLOURMAP command description of 211

loading a colourmap 143 CANVAS CONFIG command description of 213 loading hardcopy configuration 130 CANVAS HARDCOPY command 364 description of 214215 override current hardcopy settings 129 CANVAS HIDE command description of 210 hiding the canvas 131 CANVAS MODE command and AUTORAISE mode 131 description of 216 editing graphs 134 error messages 364 CANVAS OFF command description of 217219 destroy a canvas 124 CANVAS ON command and error conditions 127, 135 and GRAPH CURSOR command 271 and GRAPH FORMAT command 275 and GRAPH POSITION command 276 and GRAPH PROPERTY command 278 and KFPROC command 290 creating a canvas 122125 description of 217219 CANVAS PRINT command description of 210 printing a canvas 129130 CANVAS RAISE command and CANVAS MODE command 216 description of 210 raising a canvas 131 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

385

Index

description of 210 cascading menu, defined 24 CASE command description of 335336 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 description of 244245 error messages 369 clearing the display window 130 CLOSEDIALOG command and application defined buttons 63 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 set in application defaults file 163, 195 set with DIALOG LAYOUT command 235 COMMAND attribute and PRINTER command 111 defines printing command 308 error messages 372 commands ABORT 135, 156158, 189190, 272, 310 ADJUST 191 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

386

TSL Guide & Reference

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, 364 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, 362 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, 368 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

387

Index

TSL fonts 192 CONFIRM command confirmation dialog 42 description of 224 confirmation dialog CONFIRM command 224 description of 42 control button area 38 control buttons 63 creating application scripts 33 dialogs 46 display window snapshots 131 graphs 132 graphs with Kingfisher procedures 149 menus 27, 33 multi-level menu system 28 multiple dialogs 79 multiple graphs 143 on-screen reports 96 printed reports 111 the display window 122 variables 9 current pagestyle 108 cursor commands 140 cutting and pasting TSL text 160

D
data coordinates reading with GRAPH CURSOR 141 data types and dialog items 49 list of 187 dates finding records by 14 printing 104 select date dialog 166 DECLARE command assigning value to variable with text substitution 65 creating variables 9 description of 225

DEFAULT attribute and REPORT command 315 define report page style 109 error messages 373 defaults, dialog layout 68 defining accelerator 30 mnemonics 30 DEFPROC command defining a procedure 912 description of 226 error messages 365 DELETE list editing command 81 and DIALOG LIST command 244245 changing a lists contents 82 error messages 369, 373 dialog appearance set with application resources 194 DIALOG BUTTON command application defined buttons 6364 description of 229230 error messages 373 dialog buttons 38 DIALOG CALENDAR command creating calendar items 61 description of 231 DIALOG command and SETDIALOG command 328 creating dialog items 46 creating dialogs 4879 description of 227228 dialog item types 4964 error messages 367 managing multiple dialogs 7981 DIALOG HSLIDER command 56 description of 257258 DIALOG LABEL command description of 233 labelling dialog items 62 DIALOG LAYOUT command ALIGNCOLUMNS attribute 68, 163, 195, 236

388

TSL Guide & Reference

ALIGNITEMS attribute 68, 163, 195, 236 ALIGNROWS attribute 68, 163, 195, 236 and SETDIALOG command 328 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 description of 235238 error message 362 error messages 362, 370 GRID attribute 71, 237 HEIGHT attribute 70, 237 MODE attribute 164, 195, 236 changing control buttons 74 set attributes in application defaults file 163164, 195196 WIDTH attribute 70, 237 DIALOG LIST command defining dialog list items 5759 description of 239243 list selection policy 60 DIALOG MULTITEXT command defining multiline text fields 55 description of 247249 DIALOG OPTION command defining option items 5759 description of 250251 DIALOG PANEL command defining panel items 5759 description of 253254 DIALOG SKIP command and SETDIALOG command 328 description of 256 skip position in allocating items 70 DIALOG SLIDER command defining sliders 56 description of 257258 DIALOG TEXT command creating text fields 5255

description of 259261 DIALOG TIMERANGE command 262 defining time ranges 61 DIALOG TOGGLE command creating toggle buttons 56 description of 264 DIALOG VSLIDER command creating sliders 56 description of 257258 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 managing multiple dialogs 79 multiline text field 55 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

389

Index

clearing 130 creating 122 generating a snapshot 131 moving to front 131 printing 129 refreshing 130 setting fonts 161 setting number of columns 162 setting number of rows 162 specifying position, size and mode 122

E
EJECT command 266 ELIF command description of 284285 error messages 360 example usage 29 with IFOK command 286 ELSE command description of 284285 error messages 360 example usage 29 with IFOK command 286 Encrypted TSL 4, 319 ENDIF command description of 284285 error messages 360 example usage 29 ENDLINE attribute and PAGESTYLE command 299 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 description of 335336 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 ABORT command 156 and executing CANVAS COLOURMAP commands 143 and executing GRAPH commands 130, 135 and running procedures 126 and transferring data 155 escape and backslash character 14 exclusive panels 49, 57 EXPAND command description of 268 text substitution 14

F
file selection dialog 45 FILENAME attribute and PRINTER command 111 defines output filename 308 error messages 372

390

TSL Guide & Reference

FILL command description of 269 in free format reports 107 finding records by date 14 script files 3 FIRST attribute 373 and REPORT command 315 define page style 109 error messages 373 FIRST command description of 270 navigating the query buffer 90 fonts application resources 161, 192 in TSL window menus 192 FOOTER attribute 315 and PAGESTYLE command 299 error messages 373 page style attribute 108110 FOOTLINE attribute and PAGESTYLE command 299 error messages 373 page style attribute 108, 110 FOR command description of 312314 error messages 359 example usage 91 FORALL command description of 312314 error messages 359 example usage 91 format characters 103, 304 formatting type dependent 102 type independent 102 formatting on-screen reports 99 FRAME attribute and TOOLBOX command 347 draw toolbox frame 32 error messages 368 set in application defaults file 164, 196

free format reports 106

G
generating, see creating GRAPH CURSOR command and EDIT mode 216 description of 271 enabling the graphics cursor 140142 implicit creation and destruction 134 GRAPH DRAW command and AUTORAISE mode 216 and GRAPH POSITION 276 creating a graph 132137 description of 272273 error messages 364 multiple graphs 143 GRAPH FORMAT command description of 274275 example usage 142 implicit creation and destruction 138 using predefined graph formats 132134 GRAPH LOAD command 135 GRAPH POSITION command description of 276 position a graph 133 GRAPH PROPERTY command description of 277278 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 368 set in application defaults file 164, 196 set with TOOLBOX command 347

391

Index

GRID attribute define grid size 71 set with DIALOG LAYOUT command 237 grid units change number of in grid 70 GROUPGAP attribute 32 error messages 368 set in application defaults file 164, 196 set with TOOLBOX command 347348

H
hardcopy configuration 130 hardcopy, see printing 129 HEADER attribute and %PAGENUM attribute 315 and PAGESTYLE command 299 error messages 373 pagestyle attribute 108110 HEADLINE attribute and PAGESTYLE command 299 error messages 373 pagestyle attribute 108110 HEIGHT attribute and DIALOG LAYOUT command 237 define dialogs main area 70 help button 39 menus 1718 HELPFILE command 39 define current help file 1718 description of 280 HPGL hardcopy format, supported by Kingfisher 129

error messages 360 example usage 29 IFOK command and ABORT command 189 and error handling 157158 description of 286 importing/exporting data, see transferring data INFO command description of 287 information dialog 40 information dialog 40 initialising the graphics server 122 INSERT list editing command and DIALOG LIST command 244245 changing a lists contents 8182 error messages 369, 373

J
JUSTIFY command description of 288 free format reports 107

K
keysym in accelerators 30 KF_COLOURMAP_PATH environment variable 142, 211 KF_EXEC_TIMEOUT, set Kingfisher timeout period 123 KF_FORMAT_PATH environment variable 134135, 274 and GRAPH command errors 135 KF_PROC_PATH environment variable 126 127, 289 KFPROC command and AUTORAISE mode 216 calling a Kingfisher procedure 125126 description of 289290 Kingfisher procedures 125129 defined 125 errors 126 executing in TSL 125

I
iconic buttons, creating 63 icons definition of 20 on tools 25 IF command and IFOK command 286 description of 284285

392

TSL Guide & Reference

executing with KFPROC 289290 specifying variables 126 using for graphics development 149

L
labeled-iconic buttons 64 LABELGAP attribute and DIALOG BUTTON command 230 and DIALOG LABEL command 234 define position of dialog item 71 description of 74 error messages 373 position attribute 187 labels, in dialogs 62 LAST command description of 291 navigating the query buffer 90 LEFT attribute 315 define report layout 109 error messages 373 LENGTH attribute and PAGESTYLE command 299300 description of 109 error messages 373 pagestyle attribute 108 LENGTH command and PAGESTYLE command 300 and PRINT command 303 defining the default page length 106 description of 292 example usage 119 list editing commands APPEND 81, 83, 369 changing a lists contents 8186 CLEAR 81, 8384, 369 DELETE 81, 82, 369, 373 DIALOG LIST command 244246 error messages 369, 373 INSERT 8182, 369, 373 REPLACE 81, 83, 369, 373 list selection dialog 43 LMARGIN attribute

and PAGESTYLE command 299300 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 managing multiple dialogs 79 MARGIN command and LMARGIN/RMARGIN attributes 300 and PRINT command 303 controlling page layout 106 description of 293 sets value of RMARGIN attribute 109 MAXLEN attribute and DIALOG MULTITEXT command 248 maximum string length for multiline text 55 MAXWIDTH attribute and DIALOG LIST command 241 and list editing commands 181 in lists 59 MENU command defining a menu system 2532 description of 294296 error messages 360, 365 example usage 34 menu hierarchy, defined 24 MENU SKIP command description of 294296

393

Index

skipping menu items 32 menus 24 creating a menu system 24 creating a multi-level menu system 28 MINWIDTH attribute and DIALOG LIST command 241 and list editing commands 181 in lists 59 mnemonics defining 30 MODE attribute 74 and DIALOG LAYOUT command 236 set in application defaults file 164, 195 MORE command controlling the More prompt 159160 description of 297 --More-- prompt 159 multiline text fields defining 55

O
option menu creating 57 description of 50 DIALOG OPTION command 250 OTHERWISE command description of 335336 error messages 362 OUTPUT attribute and PRINTER command 111, 308 error messages 372 overlays, plotting 137

P
PAGESTYLE command defining a reports pagestyle 108110 description of 299 ENDLINE attribute 108110, 299, 373 error messages 373 example usage 117 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

N
NEXT command description of 298 navigating the query buffer 90 NOEDIT modifier 135 and error conditions 127 prevent graph editing 124 NOMENU modifier 135 and error conditions 127 for CANVAS command 125 NOPROMPT modifier and variables in Kingfisher procedures 150 example usage 127 for Kingfisher procedures 126 NOTRAP modifier disable abort signal trapping 160 NULL_ERR_MSG attribute and DIALOG MULTITEXT command 248 and DIALOG TEXT command 261 define error message for NULL values 53

394

TSL Guide & Reference

PREV command description of 302 navigating the query buffer 90 PRINT command description of 303306 formatting reports 96 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 description of 308309 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

description of 303306 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 and TSL errors 358 description of 310311 error messages 360, 362

R
raising the display window 131 RANGE_ERR_MSG attribute 53, 261 RANGEMAX attribute 368 and ASKDIALOG command 202 and DIALOG TEXT command 261 error messages 368 restricting acceptable values 5254 when evaluated 19 RANGEMIN attribute and ASKDIALOG command 202 and DIALOG TEXT command 261 error messages 368 restricting acceptable values 5254 when evaluated 19 READ command adds items to a list 245 READONLY attribute and DIALOG MULTITEXT command 248

395

Index

and DIALOG TEXT command 260 error messages 368 style guidelines 180 syntax conventions 188 when evaluated 19 RECOVER command 352 refreshing the display window 130 REPEAT command defining a loop 27 description of 312314 error messages 359, 362 traversing the query buffer 91 REPLACE list editing command 373 and DIALOG LIST command 244245 changing a lists contents 81, 83 error messages 369 REPORT command 373 and SETREPORT command 332 DEFAULT attribute 109, 315, 373 defining reports 109110 description of 315 error messages 373 example usage 117118 FIRST attribute 109, 315 formatting reports 96 LEFT attribute 109, 315, 373 RIGHT attribute 109, 315, 373 REPORT OFF command defining reports 110 description of 315 example usage 118 REPORT ON command and PRINT command 303 creates %PAGENUM variable 300 defining reports 110 description of 315 example usage 117 reports formatting for screen 99 free format reports 106 printing from a buffer file 114 printing to printer 111

printing to screen 96 retrieving data 90 RETURN command 317 RIGHT attribute and REPORT command 315 defining pagestyles 109 error messages 373 RMARGIN attribute and PAGESTYLE command 299300 defining a pagestyle 108109 error messages 373 ROWCOLS attribute 165, 347 and TOOLBOX command 347 and toolbox definition 32 error messages 368 set in application defaults file 165, 196 rows changing dialog default layout 68

S
SAVE command write a list to a file 245 SCREEN command 318 SCRIPT command description of 319 error messages 361 script files defined 8, 33 finding 3 search paths 33 scrolled lists 49, 57 SCROLLMODE attribute 241 and changing list contents 245 and DIALOG LIST command 241 setting for lists 59 style guidelines 181 searching, see finding 14 SECRET attribute and DIALOG TEXT command 261 in text fields 55 SELECT command creating a list selection dialog 44

396

TSL Guide & Reference

description of 321 presetting list selection dialog 66 SELECTFILE command creating a file selection dialog 45 description of 323 SELECTION_DELIM attribute 60, 242 SELECTION_MAXITEMS attribute 60, 242 SELECTION_POLICY attribute 241 SENSITIVE attribute 251 and ASKMENU command 205 and DIALOG BUTTON command 230 and DIALOG LABEL command 233 and DIALOG LIST command 240 and DIALOG MULTITEXT command 248 and DIALOG PANEL command 254 and DIALOG TOGGLE command 264 and MENU command 295 and option, menu, list and panel items 59 and TOOL command 345 description of 19 error messages 365, 367, 368 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 syntax conventions 188 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 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 application resources 166 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

397

Index

list of 38 STARTLINE attribute and PAGESTYLE command 299 defining a pagestyle 108110 error messages 373 STOP command 334 SWITCH command description of 335336 error messages 362, 363 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 error messages 359, 360 path for help files 18, 280 path for script files 319 TB_TSL_SPEC_PATH environment variable error messages 359, 360 path for help files 18, 280 path for script files 3, 319 tbprint script and printCommand 163 using in PostScript mode 171 TELL command 338 TERM environment variable 333 terminal window application resources 194 text fields creating 51 creating multiline text fields 55 description of 49 DIALOG MULTITEXT command 247 DIALOG TEXT command 259 text items 340

and EXPAND command 14 assigning a value to 12 complex numbers 13 control expansion of with TABLE 96 dates 13 definition of 12 in script files 8 in TSL commands 14 strings 13 times 13 text lines, description of 12 text substitution 13 and EXPAND command 14, 268 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 description of 345346 error messages 360, 367 tool groups 25 toolbox appearance setting with application resources 196

398

TSL Guide & Reference

TOOLBOX command attributes in application defaults file 164, 196 creating a toolbox 32 description of 347348 error messages 360, 368 example usage 34 FRAME attribute 32, 164, 196, 347, 368 GRAVITY attribute 32, 164, 165, 196, 347, 368 GROUPGAP attribute 32, 164, 196, 347 348, 368 ROWCOLS attribute 32, 165, 196, 347, 368 TOOLGAP attribute 32, 164, 196, 347348 toolbox, description of 25 TOOLGAP attribute and TOOLBOX command 347348 error messages 368 set distance between tools 32 set in application defaults file 164, 196 TQL_CLIENT_DIR environment variable 23 TRANSFER LOAD command description of 349350 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 description of 349350 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 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 description of 312314 error messages 359

V
variables %BUTTONVAL 19, 44, 47, 56, 63, 87, 203, 230, 240, 251, 254, 258, 264, 321, 323 %CONFIRMVAL 42, 224 %DERR 135, 157, 189, 272, 310, 364 %DIALOGVAL 4447, 56, 63, 203, 230, 240, 251, 254, 258, 264, 321, 323 %DISPLAY 310 %DLOGCHANGED 47, 202 %DMSG 135, 158, 189, 272, 310, 364 %FERR 135, 157, 189, 272, 310, 364 %FILEVAL 45, 323 %FMSG 135, 158, 189, 272, 310, 364 %GRFOCUSSED 147 %GRSELECTED 147 %GRSTATUS 126, 130, 135, 143, 211, 213, 272, 274, 289 %LISTOK 8183, 244 %LISTPOS 61, 242

399

Index

%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 %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

setting a dialog items offset from default 73 XBMLANGPATH environment variable and DIALOG BUTTON command 229 error messages 366 path for bitmaps 20, 233, 345 xfontsel application resources 193 XFontSets application resources 192 XORIGIN attribute defining a dialog items position 7173 position attribute 187 XPOS attribute defining a dialog items position 7173 error messages 371 position attribute 187 xrdb and changing application resources 166

Y
YADJUST attribute defining a dialog items position 71 error messages 371 position attribute 187 setting a dialog items offset from default 73 YORIGIN attribute defining a dialog items position 7173 position attribute 187 YPOS attribute 7173 error messages 371 position attribute 187

W
WHILE command defining a loop 28 description of 355 error messages 359, 362 WIDTH attribute and DIALOG LAYOUT 237 defining the position of dialog items 70 window managers, TSL and 18 titles, changing 18 windows positioning on the workspace 131

X
XADJUST attribute error messages 371 position attribute 187 positioning dialog items 71

400

TSL Guide & Reference

Corporate Headquarters 13431 NE 20th Street Bellevue, WA 98005 USA Phone: +1 425 564 8000 Fax: +1 425 564 8001

EMEA 5300 Cork Airport Business Park Kinsale Road Cork, Ireland Phone: + 353 21 730 6000 Fax: + 353 21 730 6024 Spencer House 23 Sheen Road Richmond Surrey, UK, TW9 1BN Phone: +44 (0)20 8332 7400 Fax: +44 (0)20 8332 7403

Asia Pacific 901B, Tower B, Uptown 5 5 Jalan SS21/39, Damansara Uptown 47400 Petaling Jaya Selangor, Malaysia Phone: +60 3 7712 7000 Fax: +60 3 7726 7207

www.vallent.com Email: info@vallent.com


Vallent, Metrica, Prospect and ServiceAssure are registered trademarks or trademarks of Vallent Corporation and/or Vallent Software Systems UK in the United States and/or other countries. All other trademarks, trade names, company names, or products mentioned herein are the property of their respective owners. Copyright 2005 Vallent Corporation. All rights reserved.

You might also like