User's Guide - Sentences

Sentences Users

Guide

Sentencesreg Version 40

A publication of Lazysoft Ltd

Web wwwsentencescom

Email supportsentencescom

Copyright copy 2000-2014 Lazysoft Ltd All rights reserved

The information in this document is subject to change without notice and does not represent a

commitment on the part of Lazysoft Ltd No part of this document may be reproduced stored or

transmitted in any form or by any means electronic or mechanical for any purpose without the

express written permission of Lazysoft Ltd

The software described in this document is supplied subject to a License Agreement and all use

of the software is subject to the terms of the agreement Lazysoft Ltd accepts no liability for any

damages incurred directly or indirectly from any errors omissions or discrepancies between the

software and the information contained in this document

Sentences is a registered trademark of Lazysoft Ltd

LazyView is a trademark of Lazysoft Ltd

IBM AS400 DB2 DB2 Universal iSeries pSeries xSeries zSeries Lotus and WebSphere are

registered trademarks of International Business Machines IBM Corporation

Microsoft Windows Windows XP Windows Vista Windows 7 SQL Server Internet

Information Server (IIS) Internet Explorer Microsoft Office Microsoft Word Microsoft Excel

Microsoft Outlook Microsoft Sharepoint and Microsoft Access are trademarks or registered

trademarks of Microsoft Corporation

Oracle and Java are registered trademarks of Oracle Corporation andor its affiliates

Adobe the Adobe logo PostScript and the PostScript logo are either registered trademarks or

trademarks of Adobe Systems Incorporated in the United States andor other countries

The Tomcat Web server redistributed with Sentences and the Xalan XSLT Stylesheet Processor

and the Xerces XML Parser incorporated in Sentences were developed by the Apache Software

Foundation (httpwwwapacheorg) Copyright copy 1999-2000 The Apache Software Foundation

All rights reserved Please see the accompanying text files in the Licenses subdirectory for full

details of the copyright and warranty limitations for Apache Software Foundation products

InstallAnywhere is a registered trademark of Flexera Software Ltd

Linux is a registered trademark of Linus Torvalds

SAP Crystal Reports is a registered trademark of SAP AG in Germany and other countries

All other product names used may be trademarks or registered trademarks of their respective

owners

Document Information

Last Updated September 2014 ndash Build 191

Table of Contents

Overview 17

Introducing Sentences 17 Key features 17 Whats new in Sentences Version 40 18 How to use this guide 19

Document conventions 19 Your comments 20

Chapter 1 21

Configuring Sentences 21

Sentences editions and components 21 Additional components 21

Sentences licensing 22

Configuration files 22 Personal Edition environments 22 Enterprise Edition evaluation and testing environments 22

Security 24 Enterprise Edition production environments 24 Web servers not using Java Enterprise standards 25 Sentences installation directories 25 Server properties 29 Virtual directories 36 About the ImageURLBase parameter 36 Support for configuring other environments 37 Configuring server utilities 37

The lazystart script file 37 Using the classpath argument 38 Sentences client configuration 39

Java Runtime Environment 39 Java browser plugins 39 Javascript helper library lazyDeployJavajs 40 Applet configuration 40 Sentences applet parameters 42 Additional optional parameters 43 Web Start Configuration 44

User-defined parameters 46 Format of user-defined parameters 46 Pre-defined names 47 User Parameters 47 Referring to user-defined parameters 47 User-defined parameters in the Client API 47 User-defined parameters in triggers 47 User-defined parameters in query expressions 47

Monitoring server activity 47 Shutting down and restarting the Sentences server 47 Backing up and restoring your data 49

Online backup 49 Preparing to run online backup 49 Using the online backup command 50 Restoring your data from an online backup 50 Exporting the database for backup 51 Copying chapters for backup 51

Using trace files 51 Sentences log files 52

Running the Sentences client 52 Starting the Sentences client 52 Java Runtime Environment Plug-in 53 Security and certificate acceptance 53 Using the Java Console tool 54

Activating the Java Console on Windows systems 54 Activating the Java Console on Unix Linux systems 54

Errors reported at the Sentences client 54 Contacting Technical Support 56

Security considerations 57 Automatic check of HTML page host 57 Using database views for enhanced security 57

Sentences user security reference 57 Users and roles 57

Anonymous access to Sentences 59 Creating a new role 59 Creating a new user 62 Resetting a locked user 63

System Administrator Lockout 63 Privileges 64

Combining chapters example 65 The current user 65 Combining chapters example continued 66

User security parameters 66 The Serverproperties file 66 Client properties 66

Servlet access to Sentences 67 URL patterns and Servlets available in Sentences 67 Sentences servlets and web server security 68 Enabling and disabling servlet access 69

Uninstalling Sentences 69

Chapter 2 71

Introducing the associative model 71

Entities and associations 71 Entities and values 73

Types and instances 73 Comparing the relational model and the associative model 74

Structural comparisons 75

LazyView - Using Sentences to view relational databases 76 LazyView chapters 76 Relational schema and Sentences schema 76 Representing relational structures in Sentences 76

Relational tables and columns 76 Views 77 Tables and views with no primary key 77 Tables with a foreign key 78 Defining your own foreign keys 79 Tables with composite keys 80 Tables with self-referencing columns 80 Tables representing subtypes 80 Tables representing additional information 80

LazyView chapter setup 81 Installing a JDBC driver 81 Indexing the relational database 81 Java memory and stack requirements 81 Adding a LazyView chapter to a profile 81

Dynamic and static LazyView chapters 82 Optional connection properties 83 Using an existing LazyView chapter 83 Copying an existing LazyView chapter 83

Creating a mapping definition 84 Select tables and columns 85 SubsetSubtype choices 87 New and existing Sentences schema conflicts 87 Filtering mappings 89 Resolving conflicts 89 Summary of schema to generate 91 Processinghellip 92

Creating and Editing Translation Lists 93 Creating a new Translation List 93 Editing a Translation List 94

Importing or updating static data 95 Recorded updates 97 Selecting date columns to limit incremental data updates 98 Creating and assigning limiting queries for a data import 98 Memory requirements and timeouts 100

Combining databases 100 Making entity types equivalent 100 Display name queries 100

Viewing existing definitions 101 Checking for schema changes 101

Using LazyView to view data 101 Performance 101 Large database fields 102

LazyView Query Optimisation 102 Optimisation Queries 102

LazyView reference 104 LazyView parameters in the Serverproperties file 104

Chapter 3 107

Sentences database design 107

Database modelling in Sentences 107 Database design skills 107 Choosing entity association or value types 107 Creating verbs for association types 108 Modelling one-to-many association types 108 Iterative design and prototyping 108 Designing for change 108 Modelling behaviour common to multiple types 109 Using instance-specific association types 109 Using chapters and profiles 109

Sentences user interface design options 109 Using the Sentences Explorer and Dataform interface 110 Using custom Dataforms 110 Using applets in HTML pages and using JSPs 110 Using an XML-based user interface 111 Using the Sentences client API 111 Using the Sentences HTML5 Interface 111

Chapter 4 113

The Sentences Quick Tour 113

About tree displays in Sentences 113

The Sentences Explorer quick tour 114 The Explorer Menu bar 114

The Explorer Toolbar 115 Copying and Pasting 115 Finding data 116 Sentences Explorer tooltips 116 Tree displays in the Sentences Explorer 116 Nodes and icons 116 Schema and data pane features 117 Schema and data pane icons 117 Expand node and collapse node buttons 118 Sentences Explorer drill-down 118 Sentences Explorer tabs 118 The schema pane 119 Finding schema 120 The Core types folder 120 The Core queries folder 121 The All types folder 121 The All queries folder 121 The data and properties pane 121 The Status bar 122 Divider bar 123 Shortcut keys 123 Display Session Options 123 Support information 125 Explorer shortcut menus 127

The Dataform quick tour 128 Different kinds of Dataform 128 Title bar 129 Dataform tabbed pages 129 Labels and fields 129 Ellipsis button and picker lists 130 Dataform shortcut menus 130

The Query Editor quick tour 131 Query Editor menu bar 132 Query Editor toolbar 132 Query Editor icons 132 Query pane 133 Schema pane 133 Results pane 133 Query Editor status bar 133 Query Editor divider bars 134

The Message Log 134

Chapter 5 135

Working with Sentences 135

Profiles and chapters 135 Data and schema updates 135 Chapter file locations 136 System chapters 136 The Profiles database and the Profiles profile 136 Using multiple profiles 137 Profile and chapter commands 137 Profile and chapter constraints 137 The Open Profile dialog 138 Creating a new profile 138 Creating a new profile with the profile wizard 138 The Edit Profile dialog 142 Using the Edit Profile dialog 142

Chapters 143 Changes chapters 143 Generate Core types automatically 143 Determine if child associations are present 143 Saving a profile 144 Deleting a profile 144 Working with chapters 144 Add chapter 144 New chapter 145 Naming chapter files 145 Rename 145 Properties 146 Checking chapters used for changes 146 Deleting a chapter 146 Password-protected chapter files 146 To set a password 146 To change a password 147 To delete a password 147 To enter a password 147 Password-protected files and the Personal Edition 148

Sentences user security 148 Logging into Sentences 148 Changing your password 148 Changing to a different user 149 User Preferences 149

Available User Preferences 149

Deploying profiles and chapters 151 Schema and data visibility 152 Exporting and importing databases 152 Benefits of exporting a database 152 Database export and internal identifiers 152 Default export behaviour 153 To export a database 153 Export command option switch 153 To import a set of chapters 154 Import command option switches 155 Visibility of imported profiles 155 Visibility of imported profiles using the -renumber option 156 Limitation on parameters with Import command on Windows 156 Importing a database export file from a previous version 156 Transferring the profiles database 156 Export command troubleshooting 157 Copying chapter files 158 Restrictions on copying chapter files 158 Chapter format 158 Changing chapter file block size (single chapter export and import) 158 ExportChapter command 159 ImportChapter command 159

Using the Sentences Explorer 159 Delayed display of inverse associations 159 Display order of instances 159 Refreshing the display 160 Determining if child associations are present 160 Hiding the data pane 160 Sandbox Modes 161 Transaction Visibility 162 Browsing transactions 163

Database components 164 Entity types and entities 164 Creating entity types 164 Creating entities 165 Size of entity and value instances 165 Value types and datatypes 166 Defining value types with datatypes 167 Impact of changing a datatype 167 Visibility of value instances 168 Behaviour of value types and values 168 Creating value instances 169 Association types and associations 169 Creating association types 169 Schema and data change visibility 169 Source verb and target 170 Source 170 Verb 170 Target 170 Inverse verb 170 Page 171 Cardinality 171 Cardinality rules and data display 171 Singular inverse 171 Symmetric 172 Display ordering 172 Instance options 172 Schema Pages 172 Metatypes 174 Using metatypes 174 Creating associations 174 Deleting types and instances 174 Impact of deleting dialog 174 Implicit deletion 175 Renaming types and instances 176 Inactive Instances 176

Locating data in the Sentences Explorer 178 Demand loading of data 178 The More prompt 178 The Positioner and Filter tools 179 The Positioner tool 180 The Filter tool 181 Pattern matching with the Filter tool 181 Using Filtering and Positioning tools together 182 Reloading data 183 Stopping data retrieval 183 The Stop button 183 Sorting and sequencing 184 Sequencing association types 184 Sequencing multiple instances 185

Properties 185 General properties page 186

Display in Core types folder 187 Instance options 187 Instance name creation options 187

Datatype properties page 189 Instances are values 189 Assigning datatypes 190

String datatypes 190 Numeric datatypes 191 International considerations for the currency datatype 192 Date and time datatypes 192 International considerations for date and time datatypes 193

Format properties page 194 Presentation 194 Picker 196 Style 196 Display width 198 Table column width 198 Display height 198 Format options 198 Presentation of date formats 199 Presentation of time formats 199 Restore Default settings button 199

Presentation properties page 200 Display Name Query properties page 201 Subsets properties page 202

Comparison of subsets and supertypes 203 Dataform behaviour with subsets and supertypes 204 Subsets of association types 204 Viewing subset type instances 204

Supertypes properties page 205 Using supertypes with association types 206

Equivalence properties page 206 Triggers properties page 206 Description properties page 207 Custom Dataform properties page 208 State Domains properties page 209 Business Rules properties page 209 Diagram Images properties page 210 Default Sorting properties page 211 Dataform (Navigation) properties page 212 Dataform Filter properties page 213 Retrieval Methods properties page 213 Association Type properties page 213 Target Parameters properties page 214 Derived target properties page 215 Retrieval Methods properties page 216 Operations on instances 217

Supersedes 218 Instance equivalence 218 Instance-specific association types 219

Business rules 220 Introduction 220 Domains and states 221 Effector queries 226 Effector query parameters 226 Effector triggers 227 Business rules 227 Business rules reference 230 Browsing state domains 231 Browsing business rules 231

The Sentences Dataform 232 Dataform Layout Systems 232 Dataform Page Layout System 232

Dataform Section Layout System 233 Dataform Field Formatting 234 The base Dataform and the default Dataform 235 Create and update Dataforms 235 The create Dataform 235 The update Dataform 236 Parent Dataforms and child Dataforms 237 Creating an association in the Dataform 237 Association type targets and metatype targets 238 Dataform shortcut menu 238 Selecting targets in the Dataform 239 Creating an entity instance in the Dataform 239 Targets with duplicate names 240 Targets that are subsets 240 Changing the target in a Dataform 240 Instance specific Dataforms 240 Picker list initial selection 240 Business rules and states 241 Display names 241 Table and list buttons 241 Creating a custom Dataform 241 Refresh button on custom Dataforms 243 Custom Dataform restrictions 243 Selecting a custom Dataform 243 Custom Dataforms with subsets and supertypes 244

The Dataform applet 244 Dataform applet code example 245 Applet parameters for the Dataform applet 245

The Picker applet 248 Picker applet code example 249 Applet parameters for the Picker applet 250

The Query applet 251 Query applet code example 252 Applet parameters for the Query applet 253

Using colours in Sentences applets 253 Sentences and external formats 255

Using triggers when you import data 255 CSV Import 255 CSV Import and supertypes and subsets 256 Structure of CSV files 256 CSV Import rules 256 Cardinality rules and triggers with CSV import 257 Running CSV Import 257 To import a CSV file on Windows platforms 257 To import a CSV file on Unix Linux platforms 257 CSV Export 258

Server Process Scheduler 258 Access to the Scheduler 258

Scheduled Process Lists 258 Server Processes 258

Execute Query Process 259 Set Entity Type Name Creation Seed Process 259 Update Static LazyView Data Process 259 Replace Data Chapter Process 260 Backup Database Process 260

Schedule Plans 260

Managing Scheduled Process Lists 261 Manually running a Scheduled Process List 261 Viewing Scheduled Process List Progress 261

Chapter 6 263

Advanced techniques 263

Sentences and Java technology 263 Transaction processing in Sentences 264

Sentences Explorer based updates 264 Dataform based updates 265 Updates in parent and child Dataforms 265

Dataform tabbed pages with subsets and supertypes 265 Dataform appearance with Supertypes 266 Dataform example with Subsets 269

Target parameters 270 Conference room example 271 Allowed products example 274 Limitations of the Target Parameters mechanism 275

Creating database views using profiles and chapters 275 Database views example 275

Creating Candidate Lists 277 Item Candidates 277 Value Candidates 278

Filtering Dataform Tables 283 Limitations 283

Server Text Documents 283 Configuration 284

Chapter 7 287

Sentences queries 287

Introducing the Query Editor 287 New in version 4 287 Starting the Query Editor 288 The Query Editor window 289 General query properties dialog 290 Database queries 290 Building the request tree 290 Binding Nodes 296 Selection Sort and Derived type nodes 297 Derived types and derivations 299 Specific derived type targets 304 Using expressions in queries 304 Required nodes 316 Renaming request nodes 317 Hidden Nodes 318 Transitive closure and recursive closure 319 Query Parameters 323 Attaching Subset Queries 325 Using parameters in subset queries 325 Sentences query execution process 325 Additional expression capabilities 325 The expression and function editors 336 Update Queries 343

Creating and deleting instances 343 Firing triggers 345 Requesting a state change 346 Adding a message action 346

Adding an email action 347 Grouping instances 348 Sandbox mode 348

Grouping results 349 Reporting using SAP Crystal Reports 350

Display name queries 351 Creating a display name query 351 Display names in Sentences 352

Custom Dataforms 353 Page Nodes 354 Query node Properties dialog 355

Statistics and Graphical Output 362 Adding statistics to your query 362 Making your query into an X-Y chart 363 Making your query into a pie chart 364 Making your query into a distribution chart 365

The Query Editor and XML 367 XML properties dialog 367 Node name considerations for XML output 370 Create an XML DTD from a query 370 Export query results as XML 371 Export XSL stylesheet 371 View query results as XML 372 Example stylesheets 372

Exporting query results as CSV data 374 Running CSV Export 374

Chapter 8 377

Sentences and XML 377

Introducing XML 377 XML Terminology 377

XML Support in Sentences 378 Export Sentences schema to XML 379 XML data input and output methods 380

Using the Query Editor 381 Using Servlets 381 Using command line tools 387 Using the Sentences API 388

Sentences XML conventions 389 Use content not attributes 389 Associations appear as child elements 389 Mixed content is not allowed 390 Derived element type names 390 Split multiple lines 390 Allow the action attribute 391 Include Sentences IDs 391 Combining simple elements 391 Using Element IDs 391

Setting XML options in the Query Editor 392

Chapter 9 393

Sentences diagrams 393

The Diagram Editor 393 Diagram Editor components 393 Diagram Editor preferences 394 Diagram elements 396 Diagram element types 396

Adding diagram elements 396 Deleting diagram elements 397 Moving diagram elements 397 Consistency with Sentences Explorer 397 Adding Query Results 398

Exporting and importing diagrams 398 Printing 398

Chapter 10 401

Customising Sentences 401

Sentences API overview 401 Sentences API 401 Comparing the Sentences Client API and Server API 402 Example code and online documentation 402 Program build and execution 402 API packages 403 Class hierarchy 403

Triggers 404 Server-side triggers 404 Triggers and the Sentences API 405 Installing a trigger 405 Attaching a trigger 405 Trigger threading issues 408 Trigger invocation 408 Trigger actions 408 Customised validation (rules) 408 Customised actions 409 Using triggers with import and export 409

Custom datatypes API 409 Custom datatypes API 410 Installing a custom datatype 410 Custom datatypes and import and export 411 Removing custom datatypes 411

Adding custom Help topic pages 411 Help button display 411 Creating Help topic pages 412 Creating a Help topic mapping file 412

Localisation notes 414 Localising Sentences system text 414 Translating Sentences application text 415

Chapter 11 416

Worked examples 416

The Human resources example application 416 The Employee entity type 416 The Group company entity type 417 The Project entity type 417

CSV Import example 417 Preparing a profile for the example CSV Import 418 Importing the example CSV files 419 Viewing the imported data 419 Adding image data 420 Viewing additional data 421 Restoring the original Human Resources profile 422 Repeating the CSV Import example 422

Derivations example 422 Setting up the Order Entry example application 423

Starting the Order Entry example application 423 Order Entry base Dataform and custom Dataform 424 The Order Entry query 428 The Picker applet for the Order Entry example 432 Using the Picker applet to enter and update orders 432 Design assumptions used in the Order Entry example application 433 Restoring the original Human Resources profile 434

Trigger examples 434 Example trigger classes 434 Loading the example triggers 434 Viewing enabled triggers 435 Attaching triggers and editing trigger assignments 435 Refuse Update trigger example 436 Email Address trigger example 439 Auto Number trigger example 442 Disabling the example triggers 449

Custom datatype example 450 About datatype classes 450 Loading the custom datatype example 450 Custom datatype example TelecomsNumber 451 Using the example custom datatype 451

Client API example 455 Preparing to run the demonstration 455 Using the Salary Update example 455 Enabling Sentences Client API connections 456 Setting up the demonstration profile 456 Creating a command file 456 Demonstrating the Salary Update example 457 Restoring the original Human Resources example application 458

Integration with Microsoft Office applications 458 Creating Mail merge letters from Sentences data 458 Creating Mail merge emails from Sentences data 460 Creating Microsoft Outlook Contacts from Sentences data 462 Creating Sentences data from an Outlook Contacts folder 465 Copying Excel Data to and from Sentences 467

Integration with Crystal Reports 467

Appendix A 469

Menus and Commands summary 469

Sentences Explorer menus 469 Sentences Explorer function keys 472

Dataform function keys 472

Query Editor menus 473 Query Editor function keys 474 Diagram Editor menus 475

Diagram Editor function keys 476

Appendix B 477

Statistics and analysis 477

Viewing Sentences statistics 477 Message statistics 478 User statistics 478 Open profile statistics 478 Chapters statistics 480 Detailed chapter statistics 480 Memory usage summary 483 Scheduled process status 484

Chapter file analysis 484 Server request statistics 485

Glossary 487

17

Introducing Sentences

Overview

Overview

Welcome to the Sentences Users Guide This Overview chapter describes

bull the key features of Sentences

bull new features introduced in this version

bull how to use the rest of this guide

Unless otherwise noted in the text this Users Guide describes the Sentences

Enterprise Edition If you are using the Sentences Personal Edition please refer to the

Personal Edition Supplement which describes the differences between the Personal

and Enterprise editions of Sentences You can find a copy of the Personal Edition

Supplement in the DocUserDocuments folder of your Sentences installation


Sentencesreg produced by Lazysoft is a database management system offering rapid web-

based business solutions Sentences is based on the associative model of data developed

in Java and is optimised for intranet and internet use Sentences is available in the

following editions

bull Sentences Enterprise Edition a commercial multi-user edition

bull Sentences Personal Edition a non-commercial single-user edition for evaluation

purposes only

Sentences offers unparalleled ease of development and speed of deployment for Web

based business solutions The Sentences Enterprise Edition runs on a Web server as a

Java servlet with client access through a conventional Web browser running a Java applet

Alternative client access is possible using XML for example from HTML forms The

Sentences Personal Edition runs as a stand-alone Java application that does not require a

separate server process

Key features

The main features of Sentences include

bull the associative database engine which provides a multi-user transactional capability for

the Sentences database (see Chapter 2 Introducing the associative model and Chapter

6 Advanced techniques)

bull configurable chapters and profiles allowing the flexible configuration of schema and

data (see Chapter 5 Working with Sentences)

bull support for XML as a means of exchanging data with other systems (see Chapter 8

Sentences and XML)

bull the Sentences Explorer for the creation and maintenance of associative schemas and for

browsing searching and selecting data (see Chapter 5 Working with Sentences)

bull the Sentences Dataform user interface for the entry and maintenance of data (see

Chapter 5 Working with Sentences)

bull a powerful associative query capability (see Chapter 7 Sentences queries)

bull Java APIs for the creation of custom-code Java applications (see Chapter 10

Customising Sentences)

18

Whats new in Sentences Version 40

Overview


Version 40 of Sentences includes new functionality and enhances some of the previously

existing features

bull LazyView

LazyView allows Sentences to query browse and import data from any data source that

has a JDBC driver This includes all modern relational databases Mapping the data

sourcersquos meta-data into an associative schema is automated but allows fine-grain tuning

of how the mapping is performed Both data and schema may be periodically refreshed

Corresponding data types in different databases may be made equivalent in Sentences and

their instances aggregated This functionality allows seemingly disparate data sources

including relational databases to be combined and viewed or queried as a whole

bull User Security

Sentences now has a User Security Model for managing users and their privileges

bull Business Rules Engine

Sentences now includes a rule-driven engine for describing and enforcing an applications

behaviour

Schema in the database can be given one or more domain to describe its states Rules can

be created to either prevent certain state changes or act upon a change from one state to

another

Effector Queries can be triggered by a state change or rule These specialised queries

allow the user to add update and delete data send messages or emails and fire Triggers

bull Queries

The existing Query Engine has been enhanced and extended to provide update

functionality to support Business Rules and additional functions for data manipulation

and cleansing

A new tool for composing expressions within the query editor has been developed to

make authoring easier and more productive

In addition a query can be attached to a type that defines a friendlier name to display in

place of uninformative data such as a name in place of a unique ID These are called

Display Name Queries bull Sandbox Mode

Sentences now includes Sandbox functionality to enable the user to make data and

schema changes and then discard those changes when they have finished experimenting

bull Transaction Visibility Mode

Sentences now includes the ability to set a Visibility Timestamp which sets a point in

time in the past to view the state of the current profile This has no impact on

performance

bull Server Process Scheduler

Sentences now includes a process scheduler This provides the ability to create lists of

tasks to be executed at regular intervals including updates to static LazyView data

execution of queries (with the ability to save the output) and starting an online backup

bull Automatic entity name generation

Sentences now includes the ability to generate entity names from the current timestamp

an incrementing ID or a Globally Unique Identifier as well as the existing generation

through the Sentences trigger functionality

19

How to use this guide

Overview

bull Inactive instances

Sentences allows you to conveniently hide obsolete or inactive data during data entry

whilst retaining the data for historical records and reporting purposes The inactive status

can be set or cleared individually or en masse using an update query


For a rapid introduction to Sentences see the Sentences Tutorial which is available as a

printed book a PDF file and directly from the Help menu

If you are responsible for installing Sentences please see the Sentences Installation Guide

If you are responsible for configuring and deploying Sentences read Chapter 1

Configuring Sentences

If you are new to Sentences and the associative model of data you should start by reading

Chapter 2 Introducing the associative model If you have worked with other database

products you should find the first part of Chapter 3 Database modelling in Sentences

useful as well Continue with Chapter 4 The Sentences Quick Tour and Chapter 5

Working with Sentences Refer to other chapters as necessary

If you have used earlier versions of Sentences you should first look at the section Whats

new in Sentences Version 40 in this chapter If you have not used Sentences Version

30 or later you should also read Chapter 5 Working with Sentences Chapter 7

Sentences queries and Chapter 8 Sentences and XML Chapter 9 Sentences

diagrams

If you are an experienced application developer read the second part of Chapter 3

Sentences user interface design options You should then look at Chapter 6 Advanced

techniques Chapter 10 Customising Sentences and Chapter 11 Worked examples

You may also want to consult the Doc and Examples directories of your Sentences

installation for additional online information for developers

At the end of this guide there is an Appendices section which contains lists of menus and

commands information on server statistics and a Sentences glossary A copy of this

Users Guide and of the Sentences Tutorial are available as Adobe Acrobat PDF files in the

DocUser Documents directory of your Sentences installation An online Help system

and an online copy of the Tutorial are accessible from the Sentences Help menu

Document conventions

Sentencesrsquo product documentation uses the following phrases

bull Type in means to enter data with your keyboard

bull Press means press a key on your keyboard

bull Click means move your mouse pointer over a button or other item on the screen and

press once on the primary button on your mouse (usually the left button if you are right-

handed)

bull Double-click means move your mouse pointer over a button or other item on the screen

and press twice rapidly on the primary button on your mouse (usually the left button if

you are right-handed)

bull Right-click means move your mouse pointer over a button or other item on the screen and

press once on the secondary button on your mouse (usually the right button if you are

right-handed)

bull Shortcut menu means the pop-up context menu displayed when you right-click (click

with the secondary button) on an object

This document uses the following typographical conventions

20

Your comments

Overview

bull Names of menus commands dialogs and fixed elements in Sentences are shown in

boldface font For example

the All Types folder

the Expand node command on the View menu

the Properties toolbar button

bull Names of actual files and directories are shown in monospaced font For example

the Human resources datachap file

The monospaced font is also used for examples of batch file HTML XML javascript

and Java code and for commands to be entered at a command prompt

bull When a command line or a line of code in a batch file HTML file or Java file cannot be

displayed on one line in this book the symbol sect is used to indicate that the line has been

split for display in this book only You should type in the lines of code in this book as one

line in the file or command

bull All user-created schema and data elements in examples of the Sentences database

(association types entity types associations and entities) are shown in a sans serif font

The verb of an association type or association is shown in sans serif italics Nested

associations are enclosed in parentheses for greater clarity

For example

Person

Project

Person assigned to project

(Louise East assigned to Pisces) starting date 25th March 2000

The sans serif font is used for the data and schema items you create in examples of the

Sentences database and for error messages that are displayed in the Message Log

Your comments

We welcome your comments on this Users Guide Please let us know how it has helped

your work with Sentences or how you would like to see it improved in the future

Please email your comments to supportsentencescom

21

Sentences editions and components


Chapter 1


This chapter explains how to set-up and configure a Sentences installation It is

designed primarily for system administrators The topics covered in this chapter

include

bull licensing

bull configuring Sentences

bull shutting down and restarting the Sentences server

bull backing up and restoring your data

bull security considerations

bull servlet access to Sentences

bull uninstalling Sentences

For information on system requirements and installation procedures please see the

Sentences Installation Guide


Sentences is available in an Enterprise Edition and in a Personal Edition The Enterprise

Edition has two software components a server and a client The server component (the

Sentences server) runs as a Java servlet under a Web Application Server The Web

Application Server must be running a compatible servlet container (previously known as a

servlet engine) in order to run the Sentences server You need to have the appropriate

level of authorisation for your system in order to install Sentences

The client component (the Sentences client or Sentences applet) runs as a Java applet

in a Web browser or as a Java Web Start application and communicates with the server

using HTTP over TCP IP It is also possible to configure Sentences to use the secure

HTTPS protocol

More information is available from supportsentencescom

You must install an appropriate version of the Java runtime Plug-in for your browser

either before running the Sentences client or when it is first run on each machine but

apart from this there is no installation on the client

You can run the Enterprise Edition in Web mode with the server and client on different

machines or in local mode with the server and client on the same physical machine (see

Running the Enterprise Edition on a single computer)

The Personal Edition is a stand-alone Java application that does not require a separate

server process The Personal Edition cannot communicate with other clients or servers

and is designed for evaluation use on one computer only It is not licensed for commercial

use of any kind

The Personal Edition can be downloaded from wwwsentencescom If you are using the

Personal Edition please make sure you read the Personal Edition Supplement which can be

found in the DocUserDocuments folder of your Sentences installation

Additional components

There are two additional optional components to the Sentences Server

22

Sentences licensing


For information about the requirements and installation of each of these additional

components please see the Sentences Installation Guide For information about using each

of these components please see the separate guides provided in the

ltSentences_homegtDocUserDocuments directory

LazyView

The Sentences LazyView tool enables you to view external data alongside data from

Sentences chapters in one integrated view External data can include one or more

relational databases and MS-Excel spreadsheets

To enable the LazyView component you must have a suitable Sentences License

Application Suite

The Sentences Application Suite is a set of modular applications that introduce Sentences

features and showcase its potential The applications within the suite centre on core

business functions and use both the native Sentences Explorer interface and additional

custom HTML and applet interfaces

The Application Suite component is not installed by default It can be included during

installation by selecting the Custom install option

Sentences licensing

Sentences Enterprise Edition is supplied in accordance with a license agreement which

governs your use of the product Please see your license agreement for further details

The Sentences license file now is version-specific Only a Version 40 license will

activate Sentences Version 40 The license file contains the encrypted Initial System

Administrator password See System Administrator passwords for details

Sentences Personal Edition is distributed free of charge for evaluation purposes only The

Personal Edition is not licensed for any commercial use whatsoever You must have a

License file to run Sentences For more details see the Sentences Installation Guide

Personal Edition users should refer to the Personal Edition Supplement

Please see wwwsentencescom for more details about obtaining the Sentences Personal

Edition

Configuration files

Personal Edition environments

The Sentences Personal Edition runs as a Java application and does not require a separate

Web server The start-up properties for the Personal Edition are set in the

Serverproperties and Applicationproperties files For further information please

see the Personal Edition Supplement

The available memory default locale and locations of supporting libraries (for example

Java Database Connectivity libraries used in LazyView) are configured in the lazystartbat

or lazystartsh script See the section on Configuring server utilities for details as the same

file is used for starting the Personal Edition and running personal edition utilities such as

database backup data import and data export

Enterprise Edition evaluation and testing environments

The Sentences Version 40 installer installs the Tomcat Web server to host Sentences as a

Web application according to the guidelines of the Java Enterprise Edition specification

This is intended as a lightweight minimalist test server for evaluation and testing

To facilitate this Sentences 40 introduces a small desktop application ldquoSentences

Launcherrdquo This is intended for use as a Test environment rather than Production It

23

Configuration files


allows you to start and stop the Tomcat Web Application Server and launch the Sentences

Explorer Client locally using Java Web Start or open the welcome html web page

It is also possible to run the Tomcat Web Server as a service on Windows or other

platforms More information is available from supportsentencescom

Tomcat memory configuration

By default the Tomcat Test server is set up to use a default of 512MB system memory

The amount of memory (Java Heap) can be changed in the Server properties dialog or by

editing the catalinabat catalinash file directly in the tomcat installation The file

is located under the Sentences installation directory

ltinstallation dirgtTomcat4bincatalinabat (or catalinash)

To modify the maximum memory allocated edit the file and alter the line

SET JAVA_OPTS=-Xmx512m ndashXms512m ndashXss1m ndashshowversion

The example shows 512 MB allocated to increase the available memory to 2GB you

would alter the line to read


Tomcat locale configuration

By default the Tomcat Test server is set up to use the default locale of the machine it is

installed on To change the default locale that Tomcat (and Sentences) will use you can

add the following parameters

SET JAVA_OPTS=-Xmx512m ndashXms512m ndashXss1m ndashshowversion sect

-Dusercountry=ltcountry codegt sect

-Duserlanguage=ltlanguage codegt -Dusertimezone=lttimezone codegt

This should be entered on a single line

For example a user in Chicago might change the line to read

SET JAVA_OPTS=-Xmx512m ndashXms512m ndashXss1m ndashshowversion -Dusercountry=US sect

-Duserlanguage=en -Dusertimezone= AmericaChicago

Tomcat port configuration

The Sentences tomcat server is configured to listen for server requests (from the

Sentences applet to the Sentences servlet) on a specific port number and to listen for

shutdown requests on a different specific port number By default these port numbers

are 8090 and 8095 respectively During installation users who select the Custom

installation option can specify alternative port numbers to be used by the Sentences

server

If you need to change the port numbers used by the Sentences test server you must edit

the references to port numbers in specific files listed below If you have installed the

Applications Suite there are additional references that must be edited You must always

shut down the Sentences server before making any changes to the port numbers and

restart it afterwards for the changes to have effect

bull References to the shut-down port for all installations

References to the shut-down port number are in

ltSentences_homegtTomcat4confserverxml

bull References to the request listener port for all installations

References to the request listener port number are in


24

Configuration files


bull Additional references to the request listener port for installations with the

Application Suite

Additional references to the request listener port number are in

ltSentences_homegtresourcescreateAppSuiteChaptersxml

ltSentences_homegtresourcescreateAppSuitexml

ltSentences_homegtTomcat4webappsIdeasWEB-INFwebxml

ltSentences_homegtTomcat4webappsCASWEB-INFwebxml

Security

When you first run the Sentences Launcher application you may be asked to confirm

some security checks depending upon your Operating System and system configuration

On Windows executing the Sentences Launcher application may invoke the User

Account Control mechanism that will prompt you to confirm running the application

On Windows executing the Sentences Launcher application may also invoke a dialog

from the Firewall program asking to grant access to the Java Runtime Environment

Enterprise Edition production environments

When installing Sentences into a production Web Application Server you will use the

Java Enterprise Edition standard Web Archive (WAR file) for the Sentences application

The Java Enterprise Edition standard enables convenient deployment of Web

Applications that are packaged into a single WAR file A default Sentenceswar file is

included in the Sentences installation

25

Configuration files


A single environment entry included in the Sentences web application webxml file needs

to be configured to tell Sentences where to locate the Sentences Serverproperties file

For detailed information please see the Sentences Installation Guide All server

configuration is stored in the Serverproperties file See below for details This

environment entry can either be specified in the webxml file or set in your Web

Application Server Management Application

Other customisations of the WAR file may include

the addition of Java Database Connectivity libraries (JDBC jar files) for use with

LazyView

the addition of static or dynamic web application pages for a customised web

application that includes embedded Sentences applets

Web servers not using Java Enterprise standards

If you wish to install Sentences into a Web server that does not use the Java Enterprise

Edition standards you will need to create a directory structure that includes a

WebApplication directory and a Server directory under your ltSentences_homegt

location The web server needs to define a virtual directory that is set to this

WebApplication directory We recommend using the mapping name Sentences

The WebApplication directory needs to contain all the files that are accessed by the

Sentences client including those listed above under the webappsSentences directory

The Server directory needs to contain all the files that are accessed by the Sentences

server including those listed above under the webappsSentencesWEB-INF directory

It will need to be able to read the ldquoenvironment entryrdquo that specifies the location of the

Sentences Serverproperties file

Sentences installation directories

There are two separate locations for files in a Sentences installation program files and

data files You are prompted for these tow locations during installation

Prior to Sentences Version 40 Sentences Trace files were kept with the program files

These are now located by default along side the chapter data directory The Java process

running the Sentences server must have permission to create read and write files in both

the Chapters directory and the Trace directory

If the Trace directory does not exist the Java process running the Sentences server must

have permission to create it

The following list shows the directories created by the installation procedure for the

Sentences Enterprise Edition with descriptions of the directories and files which are

important for Sentences users The initial installation of Sentences includes all the

directories and files required for Tomcat 41 a J2EE compliant Web server An

exhaustive description of the directories and files required by Tomcat is beyond the scope

of this Users Guide

In this guide the term ltSentences_homegt refers to the main Sentences server program

installation directory This is the directory selected during installation and specified in the

InstallPath parameter in the Serverproperties file The default location for the

Sentences server installation directory on Windows platforms is CProgram FilesLazySentences40

The default location for the Sentences server installation directory on Unix or Linux

systems is usrlocalLazySentences40

26

Configuration files


All the data files required by a default installation of Sentences including the files

required by optional components are in the ltSentences_datagt directory and its

subdirectories This directory is also specified during installation The default location for

ltSentences_datagt on Windows platforms is CSentencesData40

The default location for ltSentences_datagt on Unix Linux systems is usrlocalLazySentencesData40

The default locations for Sentences chapters (referred to in this guide as

ltSentences_chaptersgt) for Sentences images (referred to in this guide as

ltSentences_imagesgt) and for Sentences trace files (referred to in this guide as

ltSentences_tracegt) are subdirectories of ltSentences_datagt

The ltSentences_chaptersgt location is the first directory listed in the ChapterPathList

parameter in the Serverproperties file

bull ltSentences_chaptersgt

The default location for the Sentences chapters directory on Windows platforms is

CSentencesData40Chapters

The default location for the Sentences chapters directory on Unix Linux platforms is

usrlocalLazySentencesData40Chapters

During the installation procedure you can choose a different location for the chapters

parent directory You can specify additional directories for chapters in the

ChapterPathList and choose different directories for the SystemChapterPath and

TempChapterPath properties in the Serverproperties file (see The Serverproperties

file ) This directory is used by the Sentences server and is not accessed directly by Web

users Make sure that the file system security permissions for this directory are set so that

the Java process running the Sentences server is able to create read and write files within

the Chapters directory

By default the chapters directory contains the system chapters Metaschemachap

Schedulerchap and Profileschap which are used internally by Sentences and which

must not be changed The system chapter Profileschap has a special status in all

Sentences sessions as it is used to store profiles and other configuration data It must not

be used as a changes chapter for user updates

The Examples subdirectory of the chapters directory contains the chapter files for the

Human resources example application and further subdirectories containing chapter

files for the Application Suite examples if these are installed

bull ltSentences_tracegt

The default location for the Sentences trace file directory on Windows is CSentencesData40Trace

The default location for the Sentences images directory on Unix Linux platforms is usrlocalLazySentencesData40Trace

This is the physical location in which the server trace files are stored When diagnosing

any problems the trace files are useful in providing information on the server activity

The location is also used to store the outcome of LazyView activity when creating a

LazyView Mapping or updating the static data for a LazyView

This directory is the default location for any Sentences server trace files It is referenced

by the TracePath property in the Serverproperties file The file system security

permissions for this directory must allow the servlet container process create read and

write access to files within the directory If the trace directory does not exist the

Sentences servlet attempts to create it You must either create the directory manually or

27

Configuration files


set the file system security permissions for the directory containing the trace directory to

allow the servlet process to create it

A trace file is created each time the Sentences server starts You can delete these files

manually when they are no longer required

bull ltSentences_imagesgt

The default location for the Sentences images directory on Windows is CSentencesData40Images

The default location for the Sentences images directory on Unix Linux platforms is

usrlocalLazySentencesData40Images

This is the physical location in which any images referenced in your Sentences database

can be stored This directory is used by the Web server to deliver images to clients and for

this reason it has a virtual directory mapping in Tomcat (ImagesforSentences)

bull ltSentences_homegt

This is the main Sentences program installation directory This directory contains server

administration scripts and batch files the Serverproperties file the Sentences license

file (SentencesLicensetxt) and the small application to facilitate the Tomcat Test

server

Server administration scripts include

Database backup and restore scripts

Chapter and Profile import and export scripts

XML data import and export scripts

Other diagnostic scripts

bull ltSentences_homegtDatatypes

This directory is the default location for any custom datatypes It is referenced by the

DatatypePath property in the Serverproperties file Any custom datatypes that are

compiled into Java archive (JAR) files which are placed in this directory are

automatically available to Sentences

bull ltSentences_homegtDoc

This directory contains extensive Sentences documentation for application developers and

users You can access detailed information on the Sentences API and also access the

Sentences Tutorial and Sentences Users Guide by opening the file indexhtml in your

Web browser

bull ltSentences_homegtExamplesChapters

This directory contains backup copies of the system chapter Profileschap and the

chapter files for the Human resources example application

bull ltSentences_homegtExamplescom

bull ltSentences_homegtExamplesCSVImport

bull ltSentences_homegtExamplesDerivations

bull ltSentences_homegtExamplesExistingDatatypes

bull ltSentences_homegtExamplesHTML

bull ltSentences_homegtExamplesJars

This group of subdirectories contains various files that are referred to in Chapter 11

Worked examples

The ExamplesExistingDatatypes subdirectory contains the source code for the

datatypes included in Sentences

28

Configuration files


The ExamplesHTML directory contains examples of HTML pages for the Dataform applet

(see ldquoThe Dataform appletrdquo) the Picker applet (see ldquoThe Picker appletrdquo) and the Query

applet (see ldquoThe Query appletrdquo)

bull ltSentences_homegtLicences

This directory contains the text of the Sentences License Agreement

(SentencesLicenseAgreementtxt) and the text of the license agreements pertaining to

software produced by the Apache Software Foundation and included with Sentences The

Sentences License file that is needed to activate Sentences is not placed in this directory

but in ltSentences_homegt

bull ltSentences_homegtresources

This directory contains image resources javascript libraries and additional JAR files that

might be needed for a server process such as a JDBC library

This directory also contains the lazystartbat file and lazystartsh files These files

contain scripts for invoking the Sentences server-side utilities For more information see

The lazystart script filerdquo

This directory also contains script files that can be used to import the chapter and profile

definitions for the optional Sentences component Sentences Application Suite Usually

these chapter and profile definitions are created as part of the installation process

However if you install the Sentences server on the IBM i you need to run these scripts

You can also run these scripts if you have restored the default profiles database by

copying the Profileschap file from ltSentences_homegtExamplesChapters

bull ltSentences_homegtStylesheets

This directory contains sample XSL stylesheets used to transform XML data exported

from Sentences Additional XSL and XSLT files required for your Sentences applications

should be added to this location or to a sub-directory of it If you change the location of

the files in this directory you must update the StylesheetURLBase property in the

Serverproperties file For more information about XSL stylesheets in Sentences see

Chapter 8 Sentences and XML

If you have installed the Application Suite this directory also includes a subdirectory

named ApplicationSuite which contains the stylesheets used by the Application Suite

examples

bull ltSentences_homegtTomcat4

This directory contains all the files and directories required for the Tomcat Web server

which conforms to the Java Enterprise specifications Sentences and the Sentences

Application Suite examples are installed as web applications under this Tomcat server

bull ltSentences_homegtTomcat4webapps

This directory includes Web archive (WAR) files for Sentences and for the Application

Suite example programs If you wish to run Sentences with any other Java Enterprise

compliant Web server you can use the WAR files from this directory

The following paragraphs describe the sub-directory structure for Sentences The pattern

of sub-directories for each of the Application Suite examples are similar

bull ltSentences_homegtTomcat4webappsSentences

This is the top-level directory for Sentences It contains all the files that need to be

accessed by the Sentences client such as the Sentencesjar archive file and

launchhtml start page If you create any customised message files they must be put into

this directory as well as into the WEB-INFclasses subdirectory This directory contains

29

Configuration files


the example Swiss German messages file Messages_de_CHproperties (see

Localisation notes )

If you create any customised Help topic HTML pages you must place them along with

the Help topics mapping file in this directory (see Adding custom Help topic pages )

This is also the parent directory for Sentences online Help and online Tutorial

bull ltSentences_homegtTomcat4webappsSentencesWEB-INF

This is the directory for all the files that need to be accessed by the Sentences server This

directory has two sub-directories classes for individual Java files and lib for Java

archive files

bull ltSentences_homegtTomcat4webappsSentencesWEB-INFclasses

This directory contains individual Java code class files that need to be accessed by the

Sentences server

If you create any customised message files they must be put into this directory as well as

into the webappsSentences parent directory This directory contains the example Swiss

German messages file Messages_de_CHproperties (see Localisation notes )

bull ltSentences_homegtTomcat4webappsSentencesWEB-INFlib

This directory contains compiled Java code archive files (JAR files) that need to be

accessed by the Sentences server These include the SentencesServerjar file and any

JDBC jar files to support LazyView chapters Older versions of Java may require the

XML parser libraries such as xalanjar xercesjar and xml-apisjar Or you may

wish to use different XML parser libraries in which case you include them here

bull ltSentences_homegtTriggers

This directory is the default location for any triggers It is referenced by the TriggerPath

property in the Serverproperties file Any triggers that are compiled into Java archive

(JAR) files which are placed in this directory are automatically available to Sentences

bull ltSentences_homegtUninstaller

This directory contains files used for uninstalling Sentences

Server properties

Sentences Server has many configurable properties that govern the available functionality

and the way it behaves These properties are stored in a file called Serverproperties in

the installation directory

Sentences 40 introduces the ability for a System Administrator to be able to edit most of

these properties from a Sentences Client (The JDBC configuration is not included To

change these the user will still have to manually edit the Serverproperties text file and

restart the server) Where applicable these properties are changed with immediate effect

This allows an Administrator more flexibility and removes the need to restart the server

for many properties For example the Administrator can change the level of trace file

logging temporarily to debug a production issue

Some properties cannot be changed without restarting the server These are indicated

below

To change the Server Properties follow these steps

1 Log into Sentences as a System Administrator

2 Select the Server Propertieshellip item from the File menu in the Sentences

Explorer

3 Modify the properties you wish to change and select OK or cancel

30

Configuration files


Server Properties have been grouped into seven areas Installation Profile Security

Troubleshooting Email LazyView and Java Heap The last group concerns the amount

of memory allocated to Java Processes on the server

List entries should be separated by the path separator for this platform ie on

Windows or on Unix

Installation properties

All properties on the Installation tab are physical locations on the server and will not be

changed dynamically This is why a ldquolive valuerdquo is shown (if different from the currently

set value) The new value will only be used when the server is restarted

bull Chapter Path List

This property stores a list of locations for your Sentences chapters as fully-qualified

directory pathnames The entries in this list refer to the location you selected for

ltSentences_datagt during Sentences installation The default entries in this list are as

follows

ltSentences_datagtChapters (for user-created chapters)

ltSentences_datagtChaptersExamples (for the Human resources example chapters)

ltSentences_datagtChaptersExamplesApplicationSuite (for the Application Suite

example files - not listed if the Application Suite is not installed)

You can add additional locations for chapter files to this property setting by entering

fully-qualified pathnames Separate the entries with the appropriate delimiter character for

your system (a colon for UnixLinuxMac OS X and a semi-colon for Windows) If

you type in more than one location for this property then Sentences uses the first entry as

the default location

bull System Chapter Path

The location used to store the system chapters Metaschemachap Schedulerchap and

Profileschap If no location is given the first location in the Chapter Path List will be

used

bull Temporary Chapter Path

The location used to store temporary chapters such as query chapters If no location is

given the first location in the Chapter Path List will be used

bull Image Path

The location used to store relative images references for Image Datatypes This defaults to

a sibling folder next to the first chapter location

bull Backup Path

This property stores the location of the directory for any backup files created by the

Online Backup procedure (see Online backup )

bull Trace Path

The location used to store server trace files This defaults to a sibling folder next to the

first chapter location

bull Statistics Path

This property specifies the directory location in which statistics files are placed Statistics

files have the name format Statisticsxxxtxt (where xxx represents a timestamp)

31

Configuration files


There is no default setting for this property If this property is not set statistics files are

not created

bull Trigger Path

The location used to store Java Archive files containing User defined Server Triggers

bull Datatype Path

The location used to store Java Archive files containing User defined Datatypes

bull Default Image URL Base

The server will use this Image URL Base when no other has been specified from the

client The XML Export process uses this Image URL base when automatically

generating XSL Stylesheets

bull Stylesheet URL Base

The location used to store XSL Stylesheets

bull Text Document Path

This property stores the location of textual documents that can be imported into

Sentences For example txt or pdf files The TextDocumentPath property will

default to a subdirectory called Text next to your first Chapters directory and Trace

directory

bull Install Path

This property stores the location of your Sentences directory The InstallPath property

is set from your response to the installation prompts This location is known as

ltSentences_homegt This property can only be modified by editing the

Serverproperties file directly

Profile properties

bull Profile Timeout

The inactive timeout period in seconds for opened profiles

bull Pending Timeout

The inactive timeout period in seconds for pending data results

bull Chapter Timeout

The time period in seconds after which an update will time out waiting to lock a chapter

bull Backup Timeout

The time period in seconds after which a backup process will time out waiting to lock a

chapter

bull Cache Size

The maximum amount of memory in megabytes to use to cache data from all chapter

files combined

bull Visibility Cache Limit

The maximum size of the visibility caches This is the sum of the known visible objects

known hidden objects and known committed transactions

bull New Chapter Block Size

The default blocksize in kilobytes to use for a new chapter

bull New Temp Chapter Block Size

32

Configuration files


The default blocksize in kilobytes to use for a new temporary chapter

bull Minimum Transaction Memory

The amount of free memory in megabytes that a server update will insist on before

starting to carry out transaction updates

bull Statistics Poll Interval

This property specifies the time interval in seconds for which the number of server

requests is recorded The default setting for this property is 300

bull Hidden Request Buffer Size

The default buffer size used for hidden forwardinversedata request results when used in

derived type and derivation expressions This is used for very large databases

bull Maximum Effector Messages

The maximum number of messages generated by an Effector Query before we curtail

reporting to the client (to avoid overwhelming the client)

bull Maximum SMTP Emails

The maximum number of simple emails generated by an Effector Query

bull Preempt Interesting Associations For Large Databases

This property should be set to true for large databases where the process of determining

whether each instance has child associations is expensive Setting this property to true

will pre-emptively determine whether there are many triple pages to search (gt100) and if

so assume there are children Only when the user actually expands the instance do they

discover if it has child associations This property can only be modified by editing the


bull XML Parser Class

This property sets the class name of the XML parser used by Sentences when importing

XML documents whenever a parser other than the default is required The default parser

is orgapachexercesparserSAXParser

This property can only be modified by editing the Serverproperties file directly

Security properties

The Security properties do not include access flags for Servlets for the Personal Edition

bull Client Api Access

Grant access to user-written programs using the Sentences client API URL Pattern ApiServer

bull Statistics Access

Grant access to Sentences server statistics URL Pattern Statistics

bull Chapter Statistics Access

Grant access to Sentences chapter statistics URL Pattern Chapter

bull DTD Access

Grant access to Generation of XML DTDs URL Pattern DTD

bull XML Schema Access

Grant access to Generation of XML Schemas URL Pattern Schema

33

Configuration files


bull XML Access

Grant access to XML output from a saved query URL Pattern XML

bull Import XML Access

Grant access to XML import using a saved query URL Pattern ImportXML

bull Backup Access

Grant access to Online Backup URL Pattern Backup

bull Anonymous Login allowed

Allow end users to log on anonymously as Public

bull Maximum login attempts before lockout

The maximum number of failed attempts an end user is allowed before the account is

locked

bull Minimum length of a password

The minimum length of a new password

bull Default User Roles

A list of the Roles to assign any new Users separated by semicolons

Troubleshooting properties

bull Maximum log size

The maximum size in megabytes of a log file (used for robust journaling) before it is

closed and a new file opened

bull Business Rules Disabled

Disable all Business Rules functionality

bull Debug Business Rules

Log detailed troubleshooting information for Business Rules

bull Disable Scheduler

Disable the Server Process Scheduler This does not prevent a user manually triggering a

process list to be run The Scheduler is enabled by default

bull Check Value Visibility

Values can have an additional check made to determine whether they should be visible If

they are not the target of an association then they can be hidden This check is very

expensive to perform and not required in most applications If it is required it can be

enabled with this property This additional check is disabled by default

bull Trace Level

Trace Level is a set of bit flags that determine which server events are logged to the server

trace file Simply add together the numbers for the types of tracing that you want to

appear in the file

Value Meaning

0 Only major events are logged

34

Configuration files


Value Meaning

1 Profile operations are logged

2 A one-line summary of every request is logged

4 Requests from clients to update data are logged without the prior

requestresult pairs but including the results

8 Requests from clients to update data are logged including both prior

requestresult pairs and full results

16 All server update actions are logged whether they came directly from a

client or from some other server function provided that triggers are

being run

32 Requests from clients to read data are logged without their results

64 Data returned to clients is logged

128 Association checks made by the standard system rule are logged

256 A one-line summary of Client Parameters are logged This is only

available if a one-line summary is requested (2)

Email properties

bull SMTP Host

The host name or address of the SMTP server

bull SMTP Username

The username for the SMTP account

bull SMTP Password

The password for the SMTP account

bull Notify end user of SMTP failures

Notify the end user if there is a failure to send email

bull Valid From List

A List of valid email addresses that the server can send SMTP email from separated by

semi-colons

LazyView properties

The LazyView Properties are only displayed if the License File includes LazyView

functionality

bull Log SQL

Output the SQL being generated for LazyView

bull Multiline Text Threshold

The minimum size of Relational Text Column for which a Sentences text field is set to be

multi-line

35

Configuration files


bull Cache Timeout

The time period in seconds after which a cached dynamic LazyView object will be

discarded and re-read A value of zero indicates cached objects will never timeout

bull Maximum result set cache size

The maximum number of open cursored results sets to hold against each RDBMS

bull Query Timeout

The time period in seconds after which a JDBC query times out and stops when browsing

data dynamically or executing a query in a dynamic LazyView profile

bull Import Timeout

The time period in seconds after which a JDBC query times out and stops during a static

LazyView data import

bull Dynamic Snapshot Limit

The maximum number of results to obtain in any dynamic request to an RDBMS Zero

indicates no limit For very large databases this significantly improves performance by

avoiding creating a cursor over a large result set Note Caution should be used with this

feature as any queries will also have their input limited to this amount which will lead to

incorrect aggregate values

bull Disable In Clause Optimisation

This flag indicates whether to disable the optimisation of Select statements that use an IN

clause to improve dynamic Lazy View performance This property can only be modified

by editing the Serverproperties file directly

Java heap properties

The Java Heap properties will only change when the server is restarted These properties

are convenient when using the Personal Edition or the Tomcat Test environment

If you have deployed Sentences to a Web Application Server then the Java Heap available

will be dependent on the settings of your Server The Server Process Java Heap value is

relevant for any server utility programs that are run when the Sentences Server is stopped

bull Tomcat Java Heap

The size in megabytes of memory to use for the main Sentences Server process running in

Tomcat If you are using Tomcat you can set how much Heap is available to the server

here If you are not using Tomcat then you will need to configure the memory allocation

in your chosen Servlet Container The Tomcat Java Heap property is not applicable to the

Personal Edition

bull Server Processes Java Heap

The Server Processes Heap Size is used when running other exclusive server processes

such as exporting a database This is also the value used by the Personal Edition

Specialist properties

There are several properties that are not accessible from the User Interface because they

make fundamental changes to the way that the system works or are rarely used but

important They are set by editing the Serverproperties file in the installation directory

when the server has been stopped

bull DataformLayoutSystem=[Sections|Pages]

36

Configuration files


This property can be set to Sections or Pages and defaults to the former Page layout

was the original system by which fields were organised in Dataforms The more

sophisticated Sections Layout system replaces it If Pages have been used extensively in

an existing Sentences profile then this property allows the user to revert to that layout

system

bull ShowSetQueries=[true|false]

This property (which defaults to false) allows the Set Query functionality to be exposed

This would be useful when upgrading an existing profile that made use of Set queries

when converting them to request based queries

bull DisableDemandPagingQueryOptimisation=[true|false]

This property (which defaults to false) allows the system administrator to temporarily turn

off the demand paging optimisation for queries on large datasets

Virtual directories

When you install Sentences with the default Tomcat Web server Tomcat creates virtual

directories for two specific locations ltSentences_imagesgt (by default this is

SentencesData40Images) and for the Web application directory (by default this is

ltSentences_homegtTomcat4webappsSentences)

The jnlp files or javascript refer to the ltSentences_imagesgt location by using the

ImageURLBase parameter with the name the name ImagesForSentences (see About the

ImageURLBase parameter)

If you use Sentences with any Web server other than the default Tomcat Web server you

must create virtual directories on your Web server for these two locations Please refer to

the documentation for your Web server for instructions on how to do this

Note The documentation for some Web servers (for example the Apache HTTP server)

refer to virtual directories as aliases

If you want to allow users to access the Sentences Users Guide and Sentences Tutorial you

can also create a virtual directory for their location on the server which is

ltSentences_homegtDocUserDocuments

About the ImageURLBase parameter

The Sentences Enterprise Edition client is a Web-based application that does not use the

local file system This means that references to external files such as image files need to

be resolved to fully qualified (absolute) URLs

Image instances are defined in the Sentences database using a string representation of the

appropriate file name or URL Any full URL entered is referenced independently of the

ImageURLBase parameter Any non-URL file name entered is combined with the value of

ImageURLBase to create a full URL

As part of the Sentences initial installation the Images subdirectory created in the

ltSentences_datagt location you chose is automatically configured as a virtual directory

named ImagesForSentences The ImageURLBase parameter is set to refer to this virtual

directory

In general for the Enterprise Edition when the value of ImageURLBase starts with

images from the default location must be served by the same Web server which is serving

Sentences That Web server must serve the images in response to a request of the form

httplthostnameportnumbergtltImageURLBasegtltimage namegt where hostname and

portnumber are derived from the codebase from which the Sentences applet JAR file is

loaded

37

Configuration files


Where ImageURLBase does not start with the default image location can be served by

any URL In this case images must be readable on the client using a URL of the form

ImageURLBaseimage name For the Enterprise Edition this kind of configuration typically

uses a second web server as the default image source and ImageURLBase takes the form

httpimageWebHost imageVirtualDirectory where imageWebHost is the host with

optional port specifier and imageVirtualDirectory is a logical name mapped by the

web server to the images directory

Support for configuring other environments

Lazysoft Technical Support maintains the list of currently supported configurations for

Sentences and can advise you on setting up your environment

For further information please contact supportsentencescom

Configuring server utilities

Server utility programs including database backup restore import and export all use a

common script to start lazystartbat or lasystartsh This enables the memory

allocation locale and supporting java libraries to be configured in one file

The lazystart script file

The ltSentences_homegtresources directory contains the lazystart script file (named

lazystartbat on Windows systems and lazystartsh on UnixLinus systems) This

file contains a script used for starting various Sentences server-side utilities such as

Import and Export which require explicitly specified Java classpaths The lazystart

script file uses variables to simplify the specification and modification of Java classpaths

If you want to change any of these variables you may edit the lazystart script file

Always use a plain text editor to edit the file and always save the file as plain text

The commands and variables listed in the file are as follows

bull SENTENCES_HOME

This variable stores the location of your Sentences home directory The default value is

taken from the location you selected when you installed Sentences

bull LAZY_JAVA_HOME

This variable stores the location of the Java home directory used by Sentences

The default value is taken from the Java Virtual Machine location you selected when you

installed Sentences

bull Classpath elements

This section is used to set the classpath used in the Java execution command Please see

the section Using the classpath argument below for more detailed information

The classpath setting includes the JAR files used by Sentences Enterprise Edition which

in the default installation of Sentences are in the

ltSentences_homegtTomcat4webappsSentencesWEB-INFclasses directory and they

are

SentencesServerjar

xalanjar

xercesjar

xml-apisjar

The JAR files used by Sentences Personal Edition are all in the ltSentences_homegt

directory and they are

SentencesPEjar

xalanjar

38

Configuration files


xercesjar

xml-apisjar

If you move or delete any of these JAR files from the default installation of Sentences

with Tomcat you must edit this section of the lazystart script file to use the changed

paths

The script also includes several other mandatory jar files and then dynamically adds any

jar or zip file present in the resources directory This way you can include a java

library by simply placing it in the resources directory

bull JVM_OPTS

This property sets Java Virtual Machine options for server-side utilities such as the Java

memory parameters The memory parameters are in the format -Xmx512m ndashXms512m

where -Xmx specifies the maximum system memory that can eventually be used (shown

here with the example value 512m meaning 512MB) and -Xms specifies the initial amount

of memory to be allocated

The stack parameter is usually needed on the Windows operating system where the

default is not large enough for complex Sentences Schema The value of ndashXss1m is also

the default on Linux Unix systems and sspecifies a 1 MB stack

For more information refer to the appropriate Java documentation from Oracle If you

chose the Custom installation option the default settings are taken from the values you

specified during installation

By default Java will use the default locale of the machine it is installed on To change the

default locale that the utilities will use you can add the following parameters







-Duserlanguage=en sect

-Dusertimezone= AmericaChicago

The ndashshowversion parameter displays the version of java in the output

Using the classpath argument

The term classpath has two uses and this may cause some confusion CLASSPATH is an

operating system environment variable and -classpath (abbreviated -cp) is a command-

line argument for Java

bull -classpath (or -cp)

Whenever a Java program is run the Java Virtual Machine must find all the classes which

are required or the program fails Classes are found using the classpath which specifies a

list of JAR files and directories to be searched for class definitions

Oracle recommend setting a classpath on the Java command line using the -cp or -

classpath arguments and this recommendation is followed in the lazystart program

bull CLASSPATH

If a classpath is not supplied on the command line Java programs use the environment

variable CLASSPATH instead In some cases start programs for Java may include this

setting on the classpath used to run Sentences Loading some publicly available JAR files

can lead to the Sentences server failing to start depending on the installed JAR files and

on how the CLASSPATH for Sentences is determined (typically this is controlled by your

servlet container configuration) To avoid these problems Lazysoft recommends that the

39

Configuration files


you should not set the system wide variable CLASSPATH for users who run the Sentences

server

Sentences client configuration

There are several Clients to the Sentences Server The Server provides several Java

Servlets for different purposes For example there is an XML servlet and an XMLSchema

servlet that can be accessed to provide a CrystalReports ldquoclientrdquo with XML data to be

rendered into a Crystal Report The XML servlet can also be used to transform the

retrieved data into html utilising any javascript libraries to render graphs tag clouds etc

Most clients however will be end users or power users requiring a rich user interface

Sentences provides several Java Applets that can be used embedded into html web pages

or used as stand-alone desktop applications using the Java Web Start technology

All Java Applets require the user to log in unless the applet parameters and server are set

up to allow anonymous access

Java Runtime Environment

Java Applets require a Java Runtime Environment to be installed on the client machine

This is available for a large range of platforms The Java Runtime installation also

includes Browser plugins that enable the browser to display java applets embedded in

web pages We recommend the latest version of the Java Runtime Environment be

installed on client machines

You can manually install the Java Runtime Environment from the Oracle Web site

appropriate to your browser and platform

httpjavacomendownloadtestjavajsp

By default the Sentences web application contains a welcome page that detects the

browser and operating system of the client and any installed JRE If the JRE is not

installed or requires upgrading to the minimum required version then the page will either

redirect the user or show instructions on how to install the latest JRE

If a suitable version of the JRE is installed and the browser plugin is enabled then the

welcome page includes a link to launch the Sentences client as a desktop application

Upon first launch a desktop shortcut will be created that can be used without the need for

a browser next time

If you have developed your own application and embedded Sentences applets into it then

you will have created a ldquohomerdquo page which can use the same detection of browser

platform and JRE to assist new users of your application

See the launchhtml webpage for an example of how to use the javascript library to

detect the browser platform and JRE in your own web pages and launch Sentences as a

desktop application See the DataformApplethtml webpage in the ExamplesHTML

installation directory for an example of how to use the javascript library to detect the

browser platform and JRE in your own web pages and embed Sentences applets in the

HTML

Java browser plugins

Please note that if you intend to use both the 32-bit and 64-bit versions of a browser then

you will need to install both versions of the Java Runtime Environment The 32-bit

version of a browser can only detect and use the 32-bit version of Java Runtime

Environment Similarly the 64-bit version of a browser can only detect and use the 64-bit

version of Java Runtime Environment

It is possible to disable Java plugins in each of the browsers and in the Java Control Panel

Different versions of JRE have different options for enabling and disabling these plugins

Please consult the Oracle website for details

40

Configuration files


httpjavacomendownloadhelpenable_browserxml

Javascript helper library lazyDeployJavajs

Sentences includes a javascript library to assist in the detection of Java and both the

launching of a Java Web Start Sentences Application or the embedding of a Sentences

Applet in a web page

This javascript library has been adapted from the javaDeployjs library developed by

Sun Microsystems and Oracle

The javascript library can be used to detect whether a suitable version of Java is available

and if not then prompt the user to download and install one or if not possible then direct

them to the Oracle website The library means that you do not have to write separate code

for different Operating Systems 32-bit or 64-bit Operating systems or the many different

browser clients available All Enterprise environments can be dealt with A known

exception at the time of writing is Safari on Windows which cannot detect the Java

plugin

Applet configuration

When embedding a Sentences Applet into a web page the javascript library can be used

to write the appropriate html for the given browser

The javascript library must be referenced in the html usually in the ltheadgt section For

example

ltscript type=textjavascript src=resourceslazyDeployJavajsgtltscriptgt

In this example we use the JQuery javascript library to detect when the html document is

ready so that library must be referenced as well

ltscript type=textjavascript src=resourcesjquery-latestjsgtltscriptgt

You can use any javascript library you wish for this purpose The following script is an

example of an embedded Sentences Dataform Applet

41

Configuration files


The final component needed in the html is the elemet that the java applet will be rendered

into The first parameter to the writeAppletHTML method ldquosentencesAppletrdquo is the id of

the element Below is part of the ltbodygt html that includes a div element with an id

sentencesApplet This can be any name you give but different applets on the same page

must have unique ids

The second parameter to the writeAppletHTML method is a list of general parameters to

define which of the Sentences Applets to render and what its size in the html it should be

The code property defines which Sentences Applet is displayed

bull Dataform applet

code lsquocomsentencesdataformDataformAppletclassrsquo

The Dataform applet displays a dataform for a single instance or a blank ldquocreaterdquo

dataform for the specified Entity Type in the specified Profile

bull Diagram applet

code lsquocomsentencesguidiagramDiagramAppletclassrsquo

The Diagram applet displays either a saved diagram the results of a query or a blank

diagram

bull Picker applet

code lsquocomsentencesguipickerPickerAppletclassrsquo

lth1gtEmployee Detailslth1gt

lth2gtBarney Norrislth2gt

ltdiv id=sentencesAppletgtltdivgt

ltpgt

The above is an example of a Dataform applet embedded within an HTML page

ltscript type=textjavascriptgt

$(document)ready(function()

deployJavawriteAppletHTML(sentencesApplet

Applet Parameters

codecomsentencesdataformDataformAppletclass

archiveSentencesjar

width700

height500

Application Specific parameters

ProfileHuman resources

EditOptiondata

FixedProfileno

LazyTypeEmployee

LazyInstanceBarney Norris

EnablePickersyes

SaveButtonTextSubmit changes

ImageURLBaseImagesForSentences

Bordernone

ColourwindowFFFFEE

ColourmenuFFFFEE

ColourmenuText000000

ColourtextText000000

ColourtextHighlight6666AA

ColourtextHighlightTextFFFFFF

ColourcontrolDDEEFF

ColourcontrolText000000

ColourcontrolHighlightFFFFFF

ColourcontrolLtHighlightAAAAAA

ColourcontrolShadowDDDDDD

ColourcontrolDkShadow555555

ColourscrollbarEEEEEE

)

)

ltscriptgt

42

Configuration files


The Picker applet displays a list of instances for the user to viewedit in a dataform They

may also be able to create new instances

bull Query applet

code lsquocomsentencesdataformQueryParameterAppletclassrsquo

The Query applet displays a form to enter the parameters for a given query and then

displays the query results

bull Sentences Explorer applet

code lsquocomsentencesmainSentencesclassrsquo

This is the main applet for the Sentences Explorer Client

The third parameter to the writeAppletHTML method is a list of parameters specific to

each of these applets For more information on each of these see The Dataform applet

The Picker applet - and The Query applet An example of the Diagram applet is

included in the examplesHTML directory of the installation

The Sentences Explorer applet uses the following common applet parameters

Sentences applet parameters

bull Profile

The Profile parameter defines the default profile opened when the Sentences applet is

started You can change the value of this parameter to the name of the default profile for

your installation The name of the profile must not contain any special characters that

need to be represented by escape sequences in HTML If the Profile parameter is not

specified then Sentences will offer the user a list of profiles that they are allowed to open

The user can also cancel from this list and create a new profile to work with if allowed

bull FixedProfile

The FixedProfile parameter can have the values yes or no When the FixedProfile

parameter is set to yes the Open Profile Delete Profile and Edit Profile options in the

Explorer File menu are not available This creates a profile with limited database access

for end-users

Note You can restrict a users ability to change parts of the database by using a

combination of the FixedProfile and EditOption parameters and by specifying

changes chapters in the Edit Profile dialog (see Using the Edit Profile dialog )

Note If Sentences is deployed with Java Web Start technology the local JNLP file can be

edited and this parmeter could be altered so there are two other mechanisms for setting

this parameter on a per-user and per-roll basis See ldquoUsers and Rolesrdquo for details

bull EditOption

The EditOption parameter specifies what parts of the database can be edited by users

The possible values are schema query data and none

Parameter value Editing actions allowed

Schema allows the user to edit schema queries and data

Query allows the user to edit queries and data

Data allows the user to edit data

None no editing actions allowed

43

Configuration files


The settings for this parameter are not case-sensitive If no setting is given for this

parameter the default setting is none The setting in the jnlp file or javascript supplied

with Sentences is schema

If the EditOption parameter is set to data or none users can create edit and execute

queries but they cannot save any changes they make to queries




bull FontSize

The FontSize parameter specifies the font size to use in the Sentences Explorer (default

11 for Windows) This is intended for use on large monitors with large resolution where

the text size may be too small for adequate viewing during for example a presentation

Font sizes larger than 16 are not recommended

bull ImageURLBase

The ImageURLBase parameter specifies the URL base for the location of image files This

can either be a full format URL (for example

httpwwwanywebsiteaddresscomImages) or a relative URL Whatever is specified

in this parameter is prefixed to the image file names to allow Sentences to locate and

display images By default this is ImagesForSentences which is a relative URL

referring to the Images subdirectory you chose during installation For further details

about this parameter (see About the ImageURLBase parameter)

Note You can add further parameters at this point in the code (see Additional optional

parameters)

Additional optional parameters

You can add any of the following parameters to your HTML script

bull ServletPort

The Sentences applet attempts to connect to the Sentences servlet using the host name and

port from which it was downloaded If the applet was downloaded from a URL that

included an explicit port number that port number is used for the servlet port If the

applet was downloaded from a URL that did not include an explicit port number the

servlet port defaults to 80 which is the default port for HTTP If the applet needs to

access the Sentences servlet on a different port you must specify that port number with

the ServletPort parameter See also Starting the Sentences client

bull ServletContext

The Sentences applet requires a servlet context to connect to the Sentences servlet The

servlet context is the part of the URL after the host name and port The default value is

Sentences If the Sentences servlet is configured on a different context this must be

specified using the ServletContext parameter for example

ltparam name=ServletContext value=servletgt

See also Starting the Sentences client

bull RequestSize

Sets the number of data items retrieved from the Sentences database for each request If

more items exist Sentences displays the More prompt in the data pane The default

value for RequestSize is 500

44

Configuration files


bull LookandFeel

Sets the appearance of the Sentences client applet The possible settings are Default

Windows Metal Nimbus and Motif Not all of these possible settings are supported on

all platforms The supported settings depend on those supported by the version of Java

installed

bull UserText

This parameter specifies an optional text string that is added to transactions as userText

This can be referred to by triggers

bull ProfilesProfileVisible

This parameter determines whether the system profile Profiles is visible to users in the

Open Profiles dialog The possible values are Yes and No The default setting is No (see

The Profiles database and the Profiles profile)

Web Start Configuration

The Java Web Start technology uses a Java Network Launching Protocol (JNLP) file to

define how the Sentences Client is to be configured in a similar way to the way a Java

Applet is configured

One advantage of the JNLP configuration over HTML applet configuration is that it is

browser-independent Whilst the Sentences Server can be run with any version of Java

above Version 16 the client Web Start must use Version 7 to benefit fully from the

advantages of Web Start

The lazyDeployJavajs javascript library can be used to render the appropriate html for

the given browser and provide either a link that will launch the Sentences Explorer Client

as a Java Web Start application or instructions on how to install a suitable Java Runtime if

required

The lazyDeployJavajs javascript library must be referenced in the html usually in the

ltheadgt section For example






example of creating a link (or Java installation instructions)


into The first parameter to the writeLaunchHTML method ldquolaunchInfordquo is the id of the

element Below is part of the ltbodygt html that includes a div element with an id of

launchInfo This can be any name you give but different elements linking to different

client configurations on the same page must have unique ids



deployJavawriteLaunchHTML(launchInfo)

)

ltscriptgt

45

Configuration files


ltjnlp href=sentjnlpgt

ltinformationgt

lttitlegtSentences Explorer 40lttitlegt

ltvendorgtLazysoft Ltdltvendorgt

lticon href=resourcessentencesgifgt

ltdescriptiongtSentences Enterprise Edition V40150EEltdescriptiongt

ltshortcut online=falsegt

ltdesktopgt

ltshortcutgt

ltinformationgt

ltupdate check=backgroundgt

ltresourcesgt

ltjava version=170+ href=httpjavasuncomproductsautodlj2se

java-vm-args=-Xss1mgt

ltjar href=Sentencesjar main=true download=eagergt

ltresourcesgt

ltapplet-desc

name=Sentences Explorer V40150EE

main-class=comsentencesmainSentencesgt

ltparam name=ServletProtocol value=httpgt

ltparam name=ServletPort value=8090gt

ltparam name=FixedProfile value=nogt

ltparam name=EditOption value=Schemagt

ltparam name=ImageURLBase value=ImagesForSentencesgt

ltapplet-descgt

ltsecuritygt

ltall-permissionsgt

ltsecuritygt

ltjnlpgt

If a suitable version of the Java Runtime Environment is available then the generated

URL link will use the broswer plugin to launch a Java Web Start application according to

the JNLP file ltsentences_homegtTomcat4webappsSentencessentjnlp

The jnlp file contains parameters to customise and configure the particular client

behaviour and defaults (see below) If you wish to set up several different jnlp files then

alternatives to the default can be passed in as a second parameter to the writeLaunchHTML

method

The following JNLP configuration file is the example that is installed to launch Sentences

with the default settings It is the file located at ltsentences_homegtTomcat4webappsSentencessentjnlp

The JNLP file has an XML format The items in bold will differ depending upon the

installation Here are details of its contents

The name of the file must be included in the root jnlp element as a href attribute

bull information

The information element is used to describe the Web Start Application These can be

customised for specific application requirements The icon and title are used when a

desktop shortcut is created



deployJavawriteLaunchHTML(launchInfo myJNLPjnlp)

)

ltscriptgt

ltdiv class=headinggtSentences Explorer Clientltdivgt

ltdiv id=launchInfogt

ltpgt

46

User-defined parameters


bull update

The update element is used to indicate the preferences for how application updates should

be handled by the JNLP Client The default is to check for a new version in the

background

bull resources

The resources element is used to indicate which version of the java runtime environment

is required and which Java archive files are needed to run the client For the Sentences

Client only the Sentencesjar file is required

The java-vm-args attribute is used to specify aguments for the client to use If more

memory or stack is required or a different locale it can be added here The default value

is -Xss1m

The memory parameters are in the format -Xmx512m ndashXms512m where -Xmx specifies the

maximum system memory that can eventually be used (shown here with the example

value 512m meaning 512MB) and -Xms specifies the initial amount of memory to be

allocated









-Dusercountry=ltcountry codegt

-Duserlanguage=ltlanguage codegt

-Dusertimezone=lttimezone codegt

For example a user in Chicago might use

-Dusercountry=US -Duserlanguage=en -Dusertimezone= AmericaChicago

bull applet-desc

The ltapplet-descgt xml element is used to describe the Sentences client defaults and

configuration These are the same as the applet parameters described in the ldquoSentences

applet parametersrdquo and ldquoAdditional optional parametersrdquo With the exception that the

main-class=rdquocomsentencesmainSentencesrdquo parameter is used in place of the code

lsquocomsentencesmainSentencesrsquo parameter


You can add your own parameters to the HTML startup pages for Sentences applets and

for servlet access These parameters can be referred to using the Client API triggers and

query expressions

These parameters can also be added to the Applicationproperties file for use with

Sentences Personal Edition

Format of user-defined parameters

The name and value of a user-defined parameter are specified in the same way as other

parameters in the JNLP file or javascript

When using a jnlp file the a user-defined parameter is defined as follows

ltparam name=ClientParameter1 value=UserParamName=UserParamValuegt

47

Monitoring server activity


When using the javascript library a user-defined parameter is defined as follows

ClientParameter1rsquoUserParamName=UserParamValuersquo

The list of parameters are separated by commas

In the Sentences Personal Edition user-defined parameter is defined in the

Applicationproperties file on a single line as follows

ClientParameter1=UserParamName=UserParamValue

Pre-defined names

User-defined parameters use pre-defined names which must be in the form

ClientParameter1 ClientParameter2 and so on These names are not case-sensitive

and there is no practical limit to the number of parameters that can be added The pre-

defined parameter names must be used in sequence with no omissions For example if you

used the sequence of names ClientParameter1 ClientParameter2 ClientParameter4

only the first two entries would be recognised as ClientParameter3 is missing from this

sequence

User Parameters

The name part of the user parameter (UserParamName in the example above) is not case

sensitive Any characters except the equals sign (=) and the double quote () may be used

in parameter names

Sentences ignores any leading or trailing spaces in parameter names If any duplicate

parameter names are used Sentences processes the first one and ignores all the others

Missing values in user parameters are treated as null values

Referring to user-defined parameters

You can refer to user-defined parameters using the Sentences Client API triggers or

query expressions

User-defined parameters in the Client API

The Sentences Client API includes getClientParameter and setClientParameter

methods For more information on using the Sentences API see Sentences API overview

Note Detailed information for programmers about the Sentences API is available in the

online documentation installed with Sentences starting in the file

ltSentences_homegtDocapihtml The Javadoc files for the Sentences API can be found

in ltSentences_homegtDocjavadoc

User-defined parameters in triggers

A getClientParameter method is available to Sentences triggers For more information

on triggers see Triggers

User-defined parameters in query expressions

You can use the GetClientParameter method in query expressions For more details see

ldquoUsing user-defined parametersrdquo


You can use the Sentences statistics servlet to monitor server activity For more

information see Appendix B ldquoStatistics and analysisrdquo

Shutting down and restarting the Sentences server

Sentences operates in three modes Sentences Personal Edition is a single-user desktop

application that you run and exit as any other desktop application

48


Certain processes require exclusive access to the Sentences database You must shut

down the Sentences server before performing any of the following actions and restart the

server when the action is complete Certain processes require exclusive access to the

Sentences database You must shut down the Sentences server before performing any of

the following actions and restart the server when the action is complete

import a CSV file

export a profile

import a set of chapters

install a trigger or custom datatype

make changes to the Serverproperties file or Applicationproperties file

install a new SentencesLicensetxt license file

The steps required for shutting down and restarting the Sentences server vary with the

Sentences edition you are using as described in the table below

When you are usinghellip restart the server as followshellip

Sentences Personal Edition Shut down and restart the Sentences PersonalEdition

Sentences Enterprise Edition local

mode

Stop and restart the Sentences Web Application in

your Web Application Server If you are using Tomcat

you can use the Sentences Launcher application to

stop Tomcat You do not need to close the Sentences

client but if you do not you must refresh the profile

after you restart the server

Sentences Enterprise Edition Web

mode

make sure no users are connected to the Webserver

and then restart the Sentences web Application

Users should either close and restart the Sentences

client or refresh the profile

49

Backing up and restoring your data



It is always good practice to keep a backup copy of all your data The data in your

Sentences database is stored in chapter files which can be backed up in a number of

ways You should also back up the system chapter Profileschap which records

information about the profiles in your database and the Schedulerchap which contains

any scheduled server processes It is good practice to keep an independent record of the

profiles in your database and of the chapters used in each profile

Sentences offers you a number of ways to back up your Sentences database which are

explained in the following sections

Online backup

Online backup is not available in the Sentences Personal Edition

Online backup is a command line procedure that creates a backup file from all your

chapter files and profiles and uses journalling to maintain data integrity during the backup

procedure You can run online backup without the need to shut down the Sentences

server Online backup may be initiated by automated procedures

Online backup preserves the complete record of all the updates made to your chapters

When you restore your data from an online backup the resulting chapters are exact

duplicates of the original chapters

You can run online backup from any system that can communicate with your Sentences

server using HTTP If you wish to limit access to running the backup program you must

use the security mechanisms of your Web server to do so

The backup client communicates with a Backup servlet on the server With the default

installation of Sentences using Tomcat this servlet has the servlet name Backup and is

accessed locally using the URL httplocalhost8090SentencesBackup (see

Servlet access to Sentences ) When using any other Web server installation the

administrator must configure the Backup servlet in the same way as all other sentences

servlets The classname of the backup servlet is comsentencesbackupBackupServlet

The backup command script file (Backupbat on Windows or Backupsh on Linux

Unix) in the Sentences installation directory assumes that the command is being executed

on the same machine as the server and that the default Sentences configuration is being

used and uses the URL httplocalhost8090SentencesBackup to connect to the

servlet

Note If you chose Custom installation when you installed Sentences and specified a

different port number for Tomcat HTTP access then that port number is used rather than

8090

If you have installed Sentences into another Web server you need to edit the Backupbat

or Backup shell script to set the -url parameter to the appropriate value

Preparing to run online backup

Before you can run online backup you must verify or edit two settings in the

Serverproperties file

You must define the destination for the backup files in the BackupPath

parameter This path cannot be changed when the procedure is run By default

this parameter is not set

You must ensure that access has been granted to the Backup servlet in the

servlets section the appropriate entry must read BackupAccess=true

50



This is the default setting

For more details see The Serverproperties file

Using the online backup command

The Sentences server must be running when you run the online backup command

To perform an online backup open a command prompt navigate to the Sentences

installation directory and run the supplied script file On Windows systems this file is

named Backupbat and on Unix Linux systems the file is named Backupsh

You may specify a name for the backup by entering it after the command as follows Backup [-name backupname]

where backupname is an optional name used for the two files created by the backup

operation the backup file (with the extension bkp) and the journal file (with the extension

jnl)

For example if you specify the name mybackup the files created are named

mybackupbkp and mybackupjnl

If you do not specify a name the backup files are identified by a name indicating the date

and time of the backup For example if you started a back up on 15th March 2002 at

113023 the files created are named 20020315113023bkp and 20020315113023jnl

The backup operation copies all the Sentences chapter files including the system files

Profileschap and Schedulerchap The backup process copies each file in turn to the

backup file and records any changes to files that take place during the backup process to

the journal file This ensures that the combination of the backup file and the journal file

represent an accurate record of your database at the end of the backup process

Restoring your data from an online backup

You need to have exclusive access to the Sentences server when you restore from an

online backup

To restore from an online backup open a command prompt navigate to the Sentences


named Restorebat and on Unix Linux systems the file is named Restoresh

The following commands are available

bull Restore -display

This produces a summary of the backup file sets that are available

bull Restore -display [backupname]

This displays the details of the backup file set with the name you specify including the

name of the server the date when the backup was made and a list of chapters and their

locations

bull Restore [-overwrite] backupname

This starts the restore process with the given backup name If the restore involves

overwriting any existing chapters (other than the profile chapter) then the procedure

displays a list of the affected files and does not perform the restore You must use the -

overwrite switch to force the procedure to overwrite files

If your installation uses multiple locations for chapter files all the locations must be

available when you run the restore process If the original locations for some files are not

available during restore copies of these files are created in available locations The

resulting files are exact duplicates of existing chapter files When all your locations later

51

Using trace files


become available Sentences is unable to start because of these duplicate chapter files (see

Error 1267 The Sentences database is not available )

Exporting the database for backup

You can back up your data by exporting the database An exported database can later be

imported into Sentences For further details and restrictions on using export for backup

see the section Exporting and importing databases The Sentences server must be shut

down before you can export the database

Copying chapters for backup

You can back up your data by copying chapter files If you want to use a copied chapter

file in a different Sentences installation you need to create or edit a profile to use the

chapter Chapter files should not be copied while the Sentences server is running If the

server is not shut down the integrity of the copied files is not guaranteed For further

details and restrictions on copying chapters for backup see the section Deploying profiles

and chapters

Using trace files

Sentences trace files store server activity information They often contain valuable

diagnostic information that can be used to establish where an error occurred particularly

where a problem exists in client-server communication (see Errors reported at the

Sentences client )

The TraceLevel variable in the Serverproperties file determines which activities

generate messages to the trace file The basic settings are shown below

Value Meaning

0 Only major events are traced

1 Profile operations are traced


4 Requests from clients to update data are logged withoutthe prior




16

All server update actions are logged whether they came directly from a


being run




256

A one-line summary of Client Parameters is logged This is only

available if a one-line summary of every request is logged (trace level

2)

The trace levels can be used independently or in combination simply by adding together

their numeric values for use as the server trace level

The default setting for TraceLevel is 0 (zero) which is appropriate for general use An

effective setting for monitoring server activity in more detail is 23

When TraceLevel is set above zero the size of the trace files can grow rapidly so you

must ensure that there is always enough disk space for trace file usage

Every time you start the server a new trace file is created Trace files are named

trace_nnnnntxt where nnnnn is a positive integer 12 or 13 digits in length for

example

52

Running the Sentences client


trace_938079391280txt

The integer value used is the elapsed time in milliseconds since the Java system epoch

(midnight GMT 1st January 1970)

Sentences log files

Sentences creates a log file for every open chapter in the same directory as the chapter

file Sentences writes information about changes in a chapter file to the log file before

data changes are made to the chapter file This allows Sentences to maintain the integrity

of the chapter file You must not delete Sentences log files

Every time that a sequence of chapter actions that makes up a transaction iscompleted

Sentences ensures that the chapter file is written to disk which enables the size of the log

file to be reduced If the size of the log file reaches the limit set by the optional

MaxLogSize property in the Serverproperties file the chapter file is immediately

written to disk and the log file is truncated This means that very long transactions such as

those created by the CSV Import program can be handled without requiring excessive

amounts of disk space for the log file

When the chapter file is closed normally the log file is removed If Sentences terminates

unexpectedly then the next time that Sentences is started the log file is used to ensure the

integrity of the chapter file contents If Sentences terminated unexpectedly because of a

lack of disk space you must make more disk space available so that the chapter file can

be recovered correctly

The log file name is generated by removing the chap suffix from the chapter file name

and adding a log suffix instead Log files are binary files and cannot be read directly The

Sentences administrator must make sure that there is enough disk space available for

these files


There are several possible Clients for the Sentences Server The Server provides several

Java Servlets for different purposes For example there is an XML servlet and an

XMLSchema servlet that can be accessed to provide a CrystalReports ldquoclientrdquo with XML

data to be rendered into a Crystal Report The XML servlet can also be used to transform

the retrieved data into html utilising any javascript libraries to render graphs tag clouds

etc



or used as stand-alone desktop applications using the Java Web Start technology If a Java

Web Start application is used then a desktop shortcut can be created for subsequent

launching of Sentences client independently from a browser



No installation is required on a client computer other than the Java Runtime Environment

This includes the Java Plug-ins that browsers use to display the applet embedded in an

html page

Starting the Sentences client

The default Tomcat test server installation of Sentences and the default Web Archive file

for deployment to a Web Application Server are both configured with a ldquowelcomerdquo html

page launchhtml

To open this page start your Web browser and navigate to the root context of the

Sentences web application The address of your server depends on your configuration

53



If you are running Sentences Enterprise Edition in local mode (with the client and server

running on the same computer) the default address is

httplocalhost8090Sentences

This will be automatically redirected to the welcome page at

httplocalhost8090Sentenceslaunchhtml

If you are running the Sentences Enterprise Edition in Web mode (with the client and

server running on different computers) the default address depends on your system

configuration You need to know the following details of how your systems Web server

has been configured

The hostname (or IP address or networked server name) of the Web server

The port your Web server is listening on for Sentences HTTP connections

The servlet context for Sentences on your Web server

For example the Tomcat Web server as configured by the Sentences installer uses the

name Sentences as the servlet context and is configured to listen for Sentences requests

on port 8090

If you wish to identify the Sentences server by its IP address you would specify the

address in the URL For example if the IP address is 123123123123 the URL for

accessing Sentences would be

http1231231231238090Sentences

If the Sentences server you wish to specify is a computer named myserver on a local

network the URL for accessing Sentences would be

httpmyserver8090Sentences

If the Sentences server you wish to specify is a computer named servermyispcom on a

distant network the URL for accessing Sentences would be

httpservermyispcom8090Sentences

All of the above assumes that the Web server for Sentences is listening on port 8090

which is the default port with which Tomcat is installed If the default HTTP port of 80 is

used the port number (8090 in the examples above) does not need to be specified See

ldquoAdditional optional parametersrdquo for details of how to configure the ServletPort and

ServletContext parameters for the Sentences client

Java Runtime Environment Plug-in

Before you can run the Sentences client you must have the Java Standard Edition

Runtime Environment (JRE) installed and enabled

The launchhtml page uses a javascript library to detect whether the client machine has a

suitable JRE installed It will be able to automatically install or upgrade the JRE version

or give the user instructions on how to do this

If the client machine has a suitable JRE then a link will be provided to launch the

Sentences client using Java Web Start technology This will install a shortcut to the

desktop for future use without a browser This does not prevent the user from using the

link each time if they wish

Security and certificate acceptance

Application digital certificates

The Sentences Personal Edition and the Sentences Test Server application are both

digitally signed to authenticate that the software is genuinely from Lazysoft Ltd

54



On Windows the User Account Control mechanism may prompt you to confirm running

the application You may also be asked to confirm access through the firewall to the Java

Runtime Environment

Java Applet Security

The first time you access a Sentences client either as an applet or an application you must

accept the digital certificate for Sentences The Java Runtime Environment (JRE) displays

a warning dialog You will be asked to confirm that you wish to run the application

Depending upon the Operating System you may be offered the ability to ldquoAlways trust

content from this publisherrdquo which we recommend so that you are not asked to confirm

each time you run the application

Using the Java Console tool

Useful debugging information is displayed in the Java console tool

Activating the Java Console on Windows systems

To display the Java console tool each time you start Sentences start the Java Control

Panel from the Windows Control Panel The Advanced tab expand the Java Console

item and select Show console Click OK or Apply The next time you start Sentences in a

browser the separate Java Console messages window is displayed

Activating the Java Console on Unix Linux systems

You can display the Java Console on Unix Linux systems by entering a command at a

shell prompt or by entering a URL in a Web browser

Using a shell prompt type in the following command

usrjavabinControlPanel

where usrjava is the directory in which the JRE is installed

With a web browser use the following URL

fileusrjavaControlPanelhtml


Errors reported at the Sentences client

If the connection between the Sentences server and the Sentences client is temporarily

interrupted or if the Sentences server is not readily available the client cannot

communicate properly with the server and Sentences displays an error message in the

client Message Log The most common messages are described below

Error 1222 Your server connection has expired

This error message continues Please select the Refresh command from the File menu to

continue

Sentences displays this message when the ProfileTimeout or PendingTimeout limit

configured in the Serverproperties file has been passed or when the Sentences server

has been stopped and restarted while a Dataform remained open on a client and an

attempt to save the data on an open Dataform fails

After you select the Refresh command you must re-enter any data that was on an open

Dataform

Error 1265 The Sentences server has not been found

This error message continues Please contact your administrator If you receive this

message at a Sentences client you should contact the person in your organisation who is

responsible for running the Sentences server and report this error

55



This message is displayed when the Sentences server cannot be found It usually means

that the server has been shutdown

If this message is displayed you must restart the Sentences server and select the Refresh

before continuing to work with Sentences (see ldquo Shutting down and restarting the

Sentences serverrdquo)





This message is displayed when the Sentences Servlet has not been configured correctly

for example an entry for MainServer does not exist in the webxml file

If this message is displayed you must check your servlet configuration settings (see

ldquoSentences servlets and web server securityrdquo) and then restart the Sentences server (see

ldquoShutting down and restarting the Sentences serverrdquo)

Error 1267 The Sentences database is not available




This message is displayed when the Sentences servlet cannot start correctly The most

common causes of this error are that the Sentences servlet has stopped without shutting

down correctly or that the Sentences server has detected two or more chapter files with

the same internal identifier In both of these cases you cannot start Sentences and you

must check the trace file for more details

Sentences not shut down correctly

When a user opens a profile that uses one or more chapters on a particular file server

Sentences creates a databaselock file in each Chapters directory This file is deleted

automatically only when the Sentences server that created it is shut down If the server is

not shut down correctly the databaselock file remains and you cannot start the server

If the Sentences server has detected a databaselock file the trace file displays information

similar to the following

gtgtgtgtgt Servlet initialization error ltltltltlt

comsentencesapiexceptionsLazyServerConflictException 10016 A lock file

(databaselock) already exists in the Chapters directory CSentencesData40

Another Sentences server process or stand-alone process may be using this

database Check for other running processes If there are none remove the lock

file from your Chapters directory and re-start

If you see this trace file message you should shut down the Sentences server and then

check the chapters directory to see if a file named databaselock is present If you have

specified more than one location for your chapter files you must make sure that you

search all of the possible locations

Note A file named databaselock is always present while the Sentences server is

running

The Sentences backup command may also report the error 10016 shown above This

means that the backup process has found a databaselock file in the chapters directory

specified in the error message This error may occur even if the databaselock file is in a

chapters directory not used for the applications you are backing up

If you find one or more databaselock files present when the Sentences server is not

running you should delete them and then restart the Sentences servlet (see ldquoShutting

56



down and restarting the Sentences serverrdquo) You may also need to consult the

documentation for your Web server and your servlet container You must not delete a

databaselock file while the Sentences server is running

You can determine the validity of a databaselock file by checking the timestamp

indicating when the file was created If the files timestamp shows that it was created

before the last time you re-started Sentences then it can safely be deleted

Duplicate chapter files

This error is also displayed when the Sentences server detects duplicate chapter files

Duplicate files usually have different system names but are recognised as duplicates

because they have the same internal identifier

If the Sentences server has detected two or more chapter files with the same internal

identifier these files are listed in the trace file The trace file displays information similar

to the following


comsentencesapiexceptionsLazyDBException 10189 The chapters

CSentencesData40Human resources datachap and CSentencesData40Human

resources databchap are duplicates



message you should contact the person in your organisation who is responsible for

running the Sentences server and report this error

This message is displayed when there has been an attempt to access functionality that has

been disabled in the Serverproperties file For example if you have disabled access to

XML output by setting XMLAccess=false in the Serverproperties file this message is

returned if you attempt XML access In addition the trace file contains a message such as

Access to XML is forbidden

Error 1272 A connection error has occurred

This error message continues Please contact your administrator quoting the code

[codenumber] If you receive this message at a Sentences client you should contact the

person in your organisation who is responsible for running the Sentences server and

report this error quoting the code number displayed

This message is displayed when a client-server connection problem other than those

specified by errors 1265 1266 1267 or 1268 occurs The code quoted is a HTTP

response code that describes the error that has occurred HTTP error codes are widely

documented including on a number of Web sites and administrators should check this

documentation for help in identifying the cause of the problem

This error is also displayed at the client if the SentencesLicensetxt file is missing or

corrupted

Contacting Technical Support

If the recovery information given for the error messages listed above does not resolve

your problem or if you receive a different error message you should contact

supportsentencescom

Before contacting Technical Support please review the configuration information in this

chapter and make sure you have access to the following files

Serverproperties launchhtml

senthtml

and that you also have access to any trace files

57

Security considerations



You should be aware of the security implications of running applications over the Web or

over internal systems using Web communications protocols There are a number of ways

in which Sentences helps you to minimise any security risks These include an automatic

check of the HTML page host using different profiles for different users and limiting

access to Sentences servlets Security considerations for servlets are discussed in

ldquoSentences servlets and web server securityrdquo You can also set passwords to protect

chapter files (see ldquo Password-protected chapter filesrdquo)

Automatic check of HTML page host

To enhance the security of Web-based access to the Sentences server Sentences

automatically checks that the web page has been loaded from the same server as the

Sentences applet used by the client

Error 1403 The Sentences client must be loaded from the same host

as its HTML page

This error message is displayed if Sentences finds that the web page has not been loaded

from the server on which the Sentences servlet is running

Using database views for enhanced security

An additional level of security is afforded by changing the combination of chapters in

different profiles as described in Creating database views using profiles and chaptersrdquo

You can create different html start pages for different users or groups of users to open

different profiles and each would have the FixedProfile parameter set to True This

would prevent users from accessing a profile they were not entitled to use

In addition you can use the security features of your operating system or web server (or

both) to limit user access to each of these html files by granting or denying

permissions or by requiring a password

Sentences user security reference

This section gives reference information that may be useful for system designers system

administrators and user administrators

Version 40 of Sentences introduces a User Security Model Whilst those familiar with

User Security will be familiar with the terminology used there are several subtle

differences between User Security partially defined by SQL standards and those in

Sentences

Sentences uses a Role based system where Users are granted abilities through Built-in and

Custom Roles Privileges are granted to Roles not Users Users are given Roles This

abstraction makes the maintenance of Users easier and more efficient

Users and roles

There is only one built-in User in the system System Administrator is the only user who

has the ability to perform any function There is only one System Administrator and

System Administrator privileges cannot be granted to any other user

User Entities have the names used to authenticate with The also have the following

associations

bull (User display name Text)

This is the name displayed in the client rather than the username used to log in with

58



bull (User password Password)

bull (User locked Yes)

Whether the user has been locked out This can be either because of too many incorrect

login attempts or set manually by a User Administrator

bull (User last profile Profile)

The last profile used by the user is stored for use next time they use Sentences If the

client does not specify a default profile then the last profile used by the user is loaded

bull (User force password change Yes)

When creating a new User or resetting the User they are automatically forced to change

their newly assigned password The User Administrator can manually set or unset this

association

Associations inherited from Role

bull (Role role Role)

Any number of Roles can be assigned to the User As Roles can be assigned to other

Roles hierarchies of Roles can be created

bull (Role description Role)

Each Role can be given a description Users inherit this association which can then be

used if the User represents an Application rather than an individual

bull (Role fixed profile Profile)

Each Role can specify a profile which is the only profile that is available to the users with

that Role They will not be prompted to choose a profile and their Sentences Explorer will

not include menu items to change edit create or delete profiles

bull (Role edit option Edit Option)

Each Role can be given an Edit Option

The edit option specifies what parts of the database can be edited by users The possible

values are Schema Query Data and None


parameter the default setting is Schema

If the edit option is set to Data or None users can create edit and execute queries but

they cannot save any changes they make to queries

The built-in Roles are

bull Profile Editor

A Profile Editor can view create drop and alter any Profile

bull Chapter Editor

A Chapter Editor can view create and alter any Chapter

Edit Option Editing actions allowed





59



bull Schema Editor

A Schema Editor can create drop and alter any Type or Query

bull Data Editor

A Data Editor can insert delete and update any Instances

bull Sandbox User

A Sandbox User can use the Sentences Sandbox functionality for testing purposes

bull Scheduler

A Scheduler User can manage server processes to be run at scheduled times and dates

bull Transaction Visibility User

A Transaction Visibility User can set a Timestamp that determines the visibility of

committed transactions

bull User Administrator

The User Administrator Role allows access to Manage Users and Roles

When new Users are created they are assigned a default set of Roles These defaults can

be customised See the User Security Reference section for details

Only the System Administrator or User Administrators (Users with the User

Administrator Role) can Administer Users This is done either by opening the Profiles

Profile or from the File menu by selecting Administer Usershellip

bull Public

The Public Role allows anonymous access to Sentences

Anonymous access to Sentences

By default Sentences requires users to authenticate themselves with a user name and

password in order to use the system There is however a mechanism available to allow

anonymous login This has to be enabled on the server before any requests by a client will

be granted See the User Security Reference section for details of how to enable

anonymous login on the server

Each client needs to specify the anonymous login as a parameter See the Client

properties section for details

If a client has requested anonymous login and the server is set to allow it then the user

will automatically be logged in with the role of Public The privileges assigned to Public

can be changed in the same way as any other Role

Creating a new role

It is likely that you will wish to create several roles for groups of Users to give them

access to one or more Sentences Profile The access may be read-only or grant them the

ability to make data or schema updates

Roles can be organised into a hierarchy so that basic abilities can be layered and built up

To create a new Role follow these steps

1 In the Sentences Explorer select Administer Users hellip from the File menu

If the menu option is disabled this could be because you have editors open All

editors must be closed before you can change to the Profiles Profile where Users

are administered

The menu item will also be disabled if you are not logged in as a user with the

User Administrator Role

60



2 Once the Profiles Profile has open select the Role Entity Type in the schema

pane and open a Dataform by selecting Default Dataform from the View menu

3 You must enter a Name for the Role

4 You may optionally add any other Roles that you wish this Role to inherit from

5 You may optionally enter a description for this Role

6 You may optionally enter preferences for this Role

7 You may optionally select an Edit Option and Fixed Profile for this Role

8 Select the Privileges tab

9 You may add individual profiles or select All Profiles to the View profile list

10 You may select whether or not users with this role can create or drop (delete)

profiles

11 You may add individual profiles or select All Profiles to the Alter profile list

12 You may select whether or not users with this role can create chapters

13 You may add individual chapters or select All Chapters to the Alter Chapter list

14 You may select whether or not users with this role can use the Transaction

Visibility functionality

15 You may select whether or not users with this role can use the Sandbox

functionality

16 To set schema and data privileges on one of the Profiles from the View profile

list (including the All Profiles item) select it and either double click it to open its

child dataform

61



17 The first page of the child dataform is for Schema Privileges You may select

whether the user can create and drop types

18 You can add individual types to the list of types that can be altered This includes

two built-in items for All Entity Types and All Association Types

19 You may select whether the user can create and drop queries

20 You can add individual queries to the list of queries that can be altered This

includes the built-in item for All Queries

62



21 The second page of the child dataform is for Instance Privileges

22 There are three lists for granting permission to Insert Delete and Update

individual instances or you can select the built-in item All Instances

23 Apply and close the child dataform and save the New Role Dataform

Creating a new user

To create a new User follow these steps




are administered



2 Once the Profiles Profile has open select the User Entity Type in the schema


3 You must enter the identifier that the user will use to log in into the User field

Note that this is different to the name displayed in Sentences

4 The default Roles assigned to new users will be displayed You can add or

remove any roles for this user

5 If this user represents an application you may enter a description

6 The privileges tab is the same as for Roles It is possible to define specific

privileges here but usually privileges are assigned via the role(s) that are

assigned to the user See the previous section for how to assign individual

privileges

7 Select the User tab

8 You must enter a display name for the user

9 All other properties can be left with their default values

10 Select save to save the new user

11 Once you save the user a dialog will open for you to enter the initial password

for that user This will be a one-time password and the user will be forced to

change it when they first log in

63



12 You may choose to generate a random password by selecting the Generate

Random button

13 Ensure that you make a note of the password as it will not be visible in the

system afterwards

Resetting a locked user

If a user fails to log in more than the allowed number of times (See the User Security

Reference section for details) they will be locked out

A User Administrator can unlock a user This clears the locked flag and allows you to

specify a new one-time password and force the user to change password when they next

log in

To reset a User follow these steps




are administered




pane and then locate the user in the data pane and select them

3 Open the context menu for the user and select Reset User The Reset user dialog

will be opened

4 Enter a new one-time password or generate a random password by selecting the

Generate Random button Ensure that you make a note of the password as it will

not be visible in the system afterwards

5 Select Reset

6 The user will be unlocked given the new password and have the force password

change property set to yes

System Administrator Lockout

If any Sentences User forgets their password and locks themselves out the System

Administrator can reset their password If the System Administrator forgets their

password the following mechanism allows them to reset without having to re-create the

entire Profiles database

The mechanism allows the System Administrator to enter the original password that is

encrypted into the Licence file and force a new password to be set This is only possible

with physical control over the installation The trigger for this reset action is to place an

64



empty text file in the system chapter directory (or the first chapter location if one is not

specified) with the name resetadminpassword

The procedure is to

1 Shut down the server

2 Create the empty text file named resetadminpassword and place it in the

system chapter directory

3 Start the server again

4 Log in as System Administrator with the password encrypted in the license file

5 Enter a new password when prompted

6 The resetadminpassword file will be removed automatically

Privileges

Relational Database Standards for Security use a set of privileges to grant access to view

update and delete schema and data Sentences follows this standard where appropriate but

includes some additional functions specific to the Sentences database architecture

Privileges exist to

View individual Profiles

View all Profiles

Create Profiles

Drop Profiles

Alter individual Profiles

Alter all Profiles

Create Chapters

Alter individual Chapters

Alter all Chapters

Allow transaction visibility

Allow sandbox mode

For each individual Profile granted View privileges (or all Profiles) there are Further

Schema and Data Privileges

Schema Privileges exist to

Create Types

Drop Types

Alter individual types

Alter all Entity Types

Alter all Association Types

Create Queries

Drop Queries

Alter individual Queries

65



Alter all Queries

Data Privileges exist to

Insert individual Instances

Insert all Entities

Insert all Associations

Delete individual Instances

Delete all Entities

Delete all Associations

Update individual Instances

Update all Entities

Update all Associations

See the section on creating a new Role for details of how to set these privileges

A userrsquos view of an associative database is defined by the profile that they are using A

profile defines a set of chapters and the sum of their contents is the userrsquos view A user

may have multiple profiles and a chapter may appear in zero one or many profiles As a

result of this division of a database into chapters can be used to support modular database

design

An existing mechanism for defining visibility of and access to schema and data is to

combine chapters into different profiles for different sets of users

Combining chapters example

Let us imagine you have a human resources database You wish to provide an application

for general Human Resources personnel to view employee information You also wish to

provide an application for managers to maintain employee appraisal information

You could design your database with one chapter to hold the core schema for your human

resources and another to extend that schema for sensitive appraisal information

With this modular approach you can then create two profiles The first only includes the

core schema and does not have any target chapters for changes and is thus read-only The

second profile would include both schema chapters and a data chapter as the target for

appraisal data

It is possible to use privileges to limit visibility and access of schema to achieve the same

result and you must assess which is the more appropriate for your situation A modular

design of combining chapters is easier to maintain whilst User roles and privileges allow

greater flexibility

The current user

The currently logged in user is shown in the title bar of the Sentences Explorer

Sentences Queries and the Sentences API have been extended to include functions to

retrieve the current user and evaluate whether they have been granted particular roles

This allows the database designer to adapt the behaviour to different users or roles

bull GetCurrentUserID()

This function returns the username of the currently logged in user the identifier they use

to log in with

66



bull GetCurrentUserName()

This function returns the display name of the currently logged in user

bull CurrentUserHasRole(ltrole namegt)

This function returns whether or not the currently logged in user has been granted the role

specified by the passed parameter

Combining chapters example continued

In the human resources example from above we would only wish team managers to have

access to appraisal information for their team The visible appraisal information could

either be filtered by manager id name or role

In this situation it is more likely that you would use Sentences Business Rules to describe

and enforce the desired behaviour See the section on Business Rules

User security parameters

The Serverproperties file

The following parameters in the Serverproperties file are used by the User Security

System

bull AnonymousLoginAllowed

You may use this truefalse property to specify whether the Server will allow requests to

log into Sentences anonymously Even if the client requests an anonymous login unless

this property is set to true anonymous logins will not be granted

bull MaxLoginAttempts

You may use this property to set the number of attempts that will be allowed before the

user is locked out The default is 3

bull MinPasswordLength

You may use this property to set the minimum number of characters to be entered as a

password The default is 9

bull DefaultRoles

You may use this property to set the Roles that a User is given when created The default

installation of Sentences has default roles Profile EditorChapter EditorSchema

EditorData Editor

If Custom Roles are created these can also be used in this list of default Roles

Client properties

The following parameters are used in the Applicationproperties file for the Personal

Edition and in the client HTML applet or JNLP configuration file for Enterprise Edition

Clients

bull AnonymousLogin

You may use this truefalse property to specify whether the Client should connect to the

server as the Public User without asking for login credentials from the user This will only

be honoured if the server has been configured to allow this

bull BackgroundColour

You may use this property to specify a background colour to be used for the Login Screen

if you are customising it for your application or set of applications For example a value

of ldquoFFFF40rdquo would make the background a Yellow background

bull LogoImage

67

Servlet access to Sentences


You may use this property to specify a Logo to be used for the Login Screen if you are

customising it for your application or set of applications For example a value of

ldquologogifrdquo would use that GIF image

bull LogonTitle

You may use this property to specify a Title to be used for the Login Screen if you are

customising it for your application or set of applications For example a value of ldquoACME

Applicationrdquo would use that as the title


In many situations the best way for users to access the Sentences server is by running the

Sentences client applet in a Web browser

It is also possible to access the Sentences server directly using a servlet A number of

different servlets are supplied with Sentences which are listed below Because of security

considerations some of these servlets are disabled when you install Sentences Security

considerations are discussed in Sentences servlets and web server security

URL patterns and Servlets available in Sentences

The following table lists of the URL patterns that correspond to various Sentences

features and shows the status of each servlet on installation The URL patterns marked as

always enabled are essential to Sentences and cannot be changed All the other URL

patterns are listed in the Serverproperties file and you can change their status by

changing the corresponding access parameter from false to true or from true to false

You should always check the Serverproperties file for an up-to-date list of theURL

patterns and servlets currently available

68



URL pattern Servlet name Enabled by default Sentences feature

MainServer Main Always Access to Sentences from

the Sentences client applet

SavedXML

XmlSavedRespon

se

Always XML export requested by


ApiServer Main Yes Access to Sentences from

user-written programs using

the Sentences client API

Statistics Stats Yes Sentences server statistics

Chapter ChapterStats No Sentences chapter

statistics

Spatial Spatial Yes Data for the spatial view of

a Sentences chapter

DTD XmlDtd Yes

Export of XML DTDs

generated by Sentences

Schema XmlSchema Yes Export of XML Schema


XML XmlOutput Yes Export of XML documents


ImportXML XmlInput Yes Import of XML documents

Backup Backup Yes Enables online backup

Sentences servlets and web server security

The Sentences client applet is loaded from an HTML page which means that the

administrator of a Sentences Web site can apply security constraints to the relevant

HTML page to make sure that only authorized users can access Sentences data and that

each user is restricted to appropriate profiles

Users who access Sentences data using the Sentences API or the XML import and export

features do so directly by communicating with a servlet and so any security controls

applied to an HTML access page does not apply to them

Sentences addresses these security problems by introducing distinct URLs for different

kinds of database access The effects of this approach are

Individual features can be enabled or disabled by setting the corresponding access


Web site administrators can use the security features of their web servers to place security

constraints independently on each feature in some cases down to the level of a profile or

even an individual query within a profile

Web site administrators can use web server security features to control access to the URL

patterns used by the servlets listed above In some cases such as XML export the full

URL includes a profile name and a query name which allows the administrator even

more detailed control by restricting access to specific URLs

69

Uninstalling Sentences


For information on how to restrict access to a specific URL on your web server using

security constraints please consult your web servers documentation

Enabling and disabling servlet access

A full list of servlet access features showing which ones are enabled and which ones are

disabled on installation is given above (see URL patterns and Servlets available in

Sentences )

To enable or disable servlet access for a particular feature you must edit the


For each servlet that you want to enable you must change the corresponding access

parameter from false to true For each servlet that you want to disable you must

change the corresponding access parameter from true to false


To uninstall Sentences on Windows platforms and the Tomcat Web server installed with

it use the AddRemove Programs option in the Windows Control Panel

After running the uninstall procedure you must make sure that you delete the

ltSentences_homegt directory using the Windows Explorer

You can uninstall Sentences on Unix Linux platforms by running the UninstallSentences

script which can be found in ltSentences_homegtUninstaller or by deleting the

ltSentences_homegt directory

71

Entities and associations

Introducing the associative model

Chapter 2


This chapter is an introduction to the associative model for database designers who

want to work with Sentences More detailed information is available in the book The

Associative Model of Data by Simon Williams available from wwwsentencescom

Sentences is the first database product to implement the associative model of data

which is radically different from the relational model of data which currently

dominates the database market This chapter looks at some of the basic concepts of

the associative model including

bull entities and associations

bull values

bull types and instances

bull contrasts with the relational model


The associative model of data allows you to record information about independent things

in the real world (entities) and about their interactions (associations) An entity represents

a thing in the real world that has a discrete independent existence In contrast an

association represents a link or interaction between two other things each of which may

be an entity or an association An association represents a thing in the real world which

does not have an independent existence but is always dependent on other things

Some examples of entities and associations may help you understand the differences

between them Houses people bicycles and buildings are all examples of entities

Customers husbands and headquarters are all examples of associations A person may

fulfil the role of being a customer or of being a husband but even if that role comes to an

end the person remains a person

Take an imaginary company called Medway Furniture that has its main offices in

Riverbank House Riverbank House could be designated as the headquarters of Medway

Furniture But should Medway Furniture move away or go out of business Riverbank

House would not necessarily cease to exist It would merely cease to be the headquarters

of Medway Furniture The associative model sees Riverbank

House as a building entity and Medway Furniture as a company entity but it sees

Medway Furnitures use of Riverbank House as its headquarters as an association It

would be incorrect in the associative model to represent headquarters as an entity

because it does not have the necessary quality of independent existence

Any thing in the real world that can be described in terms of a link between two other

things can be represented in the associative model as an association The sentence John

Smith is a customer of Medway Furniture describes the interaction between a person

entity called John Smith and a company entity called Medway Furniture The phrase

is a customer of describes the nature of the interaction and in the terms of the

associative model defines an association

72



Figure 2-1 A simple association

In Figure 2-1 entities are shown as ellipses and associations as arrows The diagram

illustrates that in the associative model an association has three parts The first part is

referred to as its source here John Smith and the third part is referred to as its target

here Medway Furniture The middle part of the association here is a customer of is

referred to as the verb of an association Every association in the associative model must

have this source verb target structure It is the similarity between this structure and the

subject verb object structure of a common English sentence that gives the product

Sentences its name

Similarly when John Smith orders a table from Medway Furniture this too can be

described in an association

Figure 2-2 A more complex association

The diagram in Figure 2-2 shows a more complex association and illustrates one of the

strongest features of the associative model Associations are not only links between

objects in the associative database they are objects in their own right The is a customer

of association had an entity as its source and an entity as its target while the orders

association has another association as its source In the associative model an association

may be used as the source or the target of an association as easily as an entity

Since the source or target of an association may be an association the associative model

can have many associations nested within each other to whatever depth is necessary We

can write out a list of associations of increasing complexity to illustrate this For greater

clarity subordinate associations in nested groups are enclosed in parentheses there are

commas separating the source from the verb and the verb from the target and each verb is

in italics for example (source verb target)

bull John Smith is a customer of Medway Furniture

bull (John Smith is a customer of Medway Furniture) orders 6ft mahogany dining

table

bull ((John Smith is a customer of Medway Furniture) orders 6ft mahogany dining

table) on 14th June 1999

John Smith

Is a customer of

Medway Furniture

John Smith

Medway

Furniture

6 foot

mahogany

dining table

Is a customer of

Orders

73

Entities and values


bull (((John Smith is a customer of Medway Furniture) orders 6ft mahogany dining

table) on 14th June 1999) at price pound350

Sources and targets in the associative model are reusable This means that one association

or entity can be the source of many associations or can be the target of many

associations

Entities and values

Entities and associations are the two kinds of real world things that we want to record

information about in a database There are other things in the real world that we do not

need to record additional information about

Data items of this kind are known as values Numbers dates and times in the real world

do not have any qualifying attributes of their own and so in the associative model they

are treated as values

Look again at the last two examples of nested associations given above





The date 14th June 1999 and the price pound350 are examples of things that you do not

need to record any data about apart from the fact that they exist and so may be treated as

values

Since values by definition do not need to be defined or described by associations values

can only be used as the targets of associations and never as their sources Apart from this

restriction the behaviour of values is very much the same as the behaviour of entities

The distinction between entities and values is implemented in Sentences using the

datatypes mechanism Defining a group of data items as values in Sentences has far-

reaching consequences and in many cases the majority of data items in a database are not

values

Types and instances

So far this chapter has looked at examples of individual entities values and associations

The associative model generalises entities values and associations to entity types value

types and association types

Entity value and association types are used to develop the schema for an associative

database They are the main building blocks of associative database schema design

Any individual entity value or association is an instance of its respective type If you

create an entity type that is the source of a number of association types then any entity

that is an instance of that entity type may be the source of one or more associations that

are instances of the corresponding association types An individual entity does not need to

have all or any of the associations implied by the association types but if they do exist

they conform to the association types characteristics

The following diagram shows an example of an associative schema design

74

Comparing the relational model and the associative model


Figure 2-3 An associative schema

This diagram shows a schema design made up of entity types value types and association

types Using the same (source verb target) notation as before this schema could be

written out as follows

Person is a customer of Company

(Person is a customer of Company) orders Product

((Person is a customer of Company) orders Product) on date Date

((Person is a customer of Company) orders Product) at price Amount

Company has headquarters at Building

(Company has headquarters at Building) pays monthly rent Amount

This schema conforms to the principles of the associative model It has six association

types two value types (Date and Amount) and four entity types Some association types

in this schema have an entity type for their source and others that have an association type

for their source The Amount value type is the target of more than one association and the

Company entity type is the source of one association type and the target of another

Comparing the relational model and the associative

model

The associative model offers a different set of building blocks for schema design from

that offered by the relational model The principal building blocks of the relational model

are relations and domains while the building blocks of the associative model are entities

types value types and association types

Relations (also referred to as tables) are sets of rows that behave in accordance with the

rules of the database model For example each row in a relation must be unique and every

column must have a distinct name Domains are sets of values from which the values in a

column may be drawn An example of a domain is days of the week

In a relational database every table must ave a defined primary key and may include

foreign keys A primary key is one or more columns whose values are such that each row

can be uniquely identified A foreign key is one or more columns that serve as a primary

key in another table Foreign keys are used as a method of linking rows together to

implement many-to-one associations If you want to model many- to-many and one-to-

Is a customer of

On date

Person

Date

Amount

Product

Company

Building

Has

headquarters at

At price

Pays monthly rent

Orders

75



many associations in the relational model you must provide additional linking tables as

these types of association cannot be modelled directly

The associative model does not use keys In the associative database every entity or

association has a hidden surrogate that is assigned when it is created This is a unique

internal identifier which is never changed You can even change an entitys visible name

without affecting its underlying hidden surrogate

Because the use of surrogates has done away with the need for keys it is easy to

implement many-to-many and one-to-many associations as well as many-to-one

associations in the associative model narrowing the gap between the business model and

its implementation

Structural comparisons

The following statements are an attempt at a simple mapping of relational building blocks

to their associative counterparts These statements are generally true but there may be

exceptions in certain cases

bull A relational table that has no foreign keys among its primary keys can be modelled in an

associative database as an entity type that is the source of one or more association types

In other words an entity type that is the source of one or more association types is

equivalent to a table that has no foreign keys as primary keys It is likely that some parts

of the relations that would have appeared in columns in that table can be modelled as

association types having this entity type as their source

bull A relational table that has one or more foreign keys among its primary keys can be

modelled in an associative database as an association type

In other words an association type is equivalent to a table that has one or more foreign

keys as primary keys In a relational database data about customers would be recorded in

a Customer Table and data about shops in a Shop Table To combine data about shops

and customers in one table in the relational model you need to construct a ShopCustomer

Link Table This link table would use two foreign keys the primary keys from each of the

source tables as its own primary keys In an associative database an association type

with the (source verb target) of (Person is a customer of Shop) achieves the same

result

bull A domain in a relational database can be modelled in an associative database as a value

type which by definition has no association types Alternatively an entity type that is the

source of no association types is also equivalent to a domain

An associative database can use the same value type in many situations where a

relational database would require separate columns in different tables The simplest

example of this would be the use of dates One single Date value type can be used as the

target for associations indicating start date end date invoice date or date of birth which

would all require separate representations in the relational model Furthermore a single

instance of a date value such as 25th January 2001 would only be recorded once as

associations based on different association types could all make use of the same data

bull A column heading in a relational table can be modelled as the verb of an association

type

In other words the verb of an association type is equivalent to a column heading in a

relational table This restates what we have seen about the use of dates Column headings

in relational tables do not necessarily define the domain of the permitted values in the

column but often do give an indication of what the domain is An associative database

could easily contain a series of association types with verbs such as Start Date and End

Date all pointing to the same Date value type as their target

76

LazyView - Using Sentences to view relational databases


bull Both the relational and associative models use datatypes as part of the definition of a

domain

Datatypes are used in relational databases to determine the kinds of entries permitted in a

domain The associative database uses a similar mechanism for similar purposes although

the internal implementation of datatypes in Sentences is very different

LazyView - Using Sentences to view relational

databases

The LazyView Tool has been re-written and whilst some of the content from the previous

LazyView Guide is relevant all necessary information is included in this guide

You can use the Sentences LazyView chapters to view data in one or more relational

database alongside data from Sentences chapters in one integrated profile

LazyView chapters

Data from a relational database is accessed using a special kind of Sentences chapter file

A LazyView chapter can be part of a profile in the same way as an ordinary chapter

although it cannot be defined as the target chapter for schema data or query changes

You can create a number of LazyView chapters that each represent a different relational

database or instance and include them all in the same Sentences profile Although you

can add data to the Sentences database which includes a LazyView chapter this data is

always written to a native Sentences chapter and never to the LazyView chapter itself

This means that any data you add is only available when viewed through the Sentences

interface It is currently never written back to the relational database and is not available

when viewing data using the relational databasersquos native interface

Relational schema and Sentences schema

Before you can model a relational database in Sentences you must have a thorough

understanding of both Sentences and the associative model and of the relational database

you are working with

Relational databases are based on tables keys columns and rows while the Sentences

associative database is based on entity and association types and instances Despite these

fundamental differences the inbuilt flexibility of the associative model means that it is

relatively straightforward to create an associative schema in Sentences that can be used to

model the schema of a relational database

This modelling is achieved by mapping entity and association types in Sentences to

columns in the relational database Much of the mapping process has been automated but

to use LazyView successfully you must have a thorough understanding of the table

structure of the relational databases you wish to use and in particular of the ways in

which tables are linked to one another by the use of foreign keys

In general the preferred way of working with LazyView is to construct a new Sentences

schema to represent the schema of an existing relational database

Representing relational structures in Sentences

The following sections suggest how to map relations in relational databases to entity types

and association types in Sentences

Relational tables and columns

In relational databases objects are typically represented by primary key columns of tables

and the attributes of objects are typically represented by the non-key columns in a table

77



In Sentences an object is represented by an entity type and its attributes are represented

by association types As association types in Sentences have three elements in them the

correspondence between an association type and a non-key column is not exact

For example consider a relational table listing employees which has a primary key

column named Employee and has Department and Telephone number as non-key

columns In Sentences Employee Department and Telephone number would all be entity

types The relationships between these entity types would be represented by association

types which have the entity type representing the tablersquos primary key Employee as their

source and an entity type representing a non-key column as their target These

association types could be Employee works in department Department and Employee

has telephone number Telephone number

A Sentences association type specifies not only a source and a target but also the nature

of the association which is referred to as the association verb When mapping data from

relational tables to Sentences types it is therefore necessary to map the association verb as

well as the source and target In the case of an association which has a primary key as its

source and a non-key column as its target the association verb is mapped to the same

non-key column as the target This apparent duplication is necessary to prevent any

ambiguity

Views

Views are utilised in two main ways in a Relational Database They can be used as a read-

only subset or aggregation of data for the production of reports or analysis and they can

be used to control access and visibility of data

Views created for the purpose of inserting and updating data will generally be of no

interest to you when using LazyView to interrogate information If you do not have

access to the base table but only through a view then you may need to map that view to

obtain the data but views do not usually define a primary key or foreign keys and you

may have to specify them manually

Tables and views with no primary key

LazyView has the capacity to modify primary and foreign key definitions because this

information is not available directly available with some database connections

Note that the previous documentation on the LazyView tool stated that primary key

definitions were not available with a JDBC connection to a Microsoft Access database

Since then some JDBC Drivers do support this ability

Many relational databases allow you to construct read-only views (as simplified

selections of columns from one or more tables) which are treated as tables Unlike tables

views do not generally have primary or foreign keys defined for them and you should

create alternative key column definitions for columns in views so that they may be

mapped to types used as sources for associations

Any changes you make to these definitions in LazyView only effect the way in which

LazyView interprets the data in relational tables None of these changes is written back to

the original relational database files and the existing database definitions are not altered in

any way

It is very important that you understand the structure of the relational database and in

particular the way in which tables are related to each other before you make any changes

to the primary and foreign key definitions If you make any changes to key definitions

that contradict the logic of the relational database then the data you access with

LazyView may be meaningless

78



Tables with a foreign key

In relational databases connections between tables are often represented by using the

primary key column of one table as a column in another table This is known as a foreign

key In Sentences relational columns are represented by entity types A primary key

column that is used as a foreign key in another table is mapped to one Sentences entity

type That entity type (like all entity types in Sentences) can be used as the source of

association types whose targets represent non-key columns in the table for which it is the

primary key The same entity type can be also be used as the target for an association type

when performing its function as a foreign key with the second tablersquos primary key as the

source of the association

The important difference is in the way that the association verb is mapped In cases where

the target of an association is a non-key column the association verb is mapped to the

same column as the target In cases where the target of an association is the primary key

from another table the association verb is mapped to the foreign key column in the same

table as the association source is taken from For example a relational database may have

two tables named Employees and Departments

The columns of the Departments table include

bull Department_ID (the primary key)

bull Department_name

bull Location

The columns of the Employees table include

bull Employee_ID (the primary key)

bull Employee_name

bull Department_ID_fk (a foreign key which represents the primary key in

the Departments table)

In Sentences these six columns could be represented by five entity types

bull Department_ID


bull Location

bull Employee_ID

bull Employee_name

There is no need to represent the foreign key Department_ID_fk as an entity type in

Sentences

The relations in the two tables could be represented by a series of association types

including Department_ID located at Location and Employee_ID works in

Department_ID

Both of these association types use the same Sentences entity type for

Department_ID even though in one case this entity type is the source and in the other

case the target of an association

The association verb located at which links the primary key to a non-key column in the

same Departments table would be mapped to the same Location column as the Location

entity type

The association verb works in which links the primary key to a foreign key column would

be mapped to the Department_ID_fk column in the Employees table and not to the same

column as the target type (which is mapped to the Department_ID column in the

Departments column)

79



There is a restriction on the use of foreign key columns You cannot create an association

in Sentences in which the source maps to a foreign key column and the target maps to a

primary key column You may only create association in which the source maps to a

primary key column and the target maps to foreign key column or to a non-key column

Defining your own foreign keys

Some relational databases may have connections between tables but they are not defined

in the Metaschema Other external data sources like an Excel Workbook may also not

contain Foreign Key Reference information In these cases it is possible to add missing to

Foreign Key references These are termed User Defined Foreign Keys Whilst you can

add edit amend and delete User Defined Foreign Keys you cannot do this with the

Foreign Keys defined in the External Data Source Metaschema

The wizard page for refining table and column choices includes a section that displays the

available Foreign Keys and allows you to create user-defined Foreign Keys

Figure 2-4 Foreign key definitions in the Mapping Wizard

Foreign Keys defined in the External Data Source Metaschema are marked with a lock

icon to indicate that they cannot be altered

To create a User Defined Foreign Key follow these steps

1 In the LazyView wizard select the Createhellip button

2 The Create Foreign Key Reference Dialog will open

3 Select the table you wish to reference The primary key of that table will be

shown

4 Select the column(s) to match the primary key from this table If the primary key

of the referenced table is compound then you must select the matching columns

in the correct order

Figure 2-5 Creating a foreign key definition

80



There is a facility for the dialog to attempt to automatically match columns based on their

column and table names If the schema is named such that incorrect selections are being

made then you may uncheck the option

There are several limitations imposed when creating User Defined Foreign Keys

bull You cannot create duplicate Foreign Key References

bull You cannot create a Foreign Key Reference if one exists in the opposite direction

bull The datatypes of columns must match their relevant primary key column datatypes

bull Whilst a self-referencing foreign key can be created for a table it cannot reference itself

with any of its primary key columns

Tables with composite keys

Some relational tables use a composite primary key (a key that uses more than one

column) An example of this would be an Employees table that used the two columns

Employee_ID and Department_ID as a composite key Each of these columns would be

represented in Sentences by an entity type and the composite key itself would be

represented by an association type in the format Employee_ID works in department

Department_ID Each of the non-key columns of the table would be represented by entity

types The status of each non-key column as an attribute of the composite key would be

represented by an association type which has the association type representing the

composite key as its source An example of this would be

( (Employee_ID works in department Department_ID) telephone number

Telephone number)

Tables with self-referencing columns

In some relational tables a column may represent the same data as is represented by the

primary key column For example an Employees table may contain an Employee_ID

column and a Manager_ID column to designate which manager each employee works for

The data in both of these columns is Employee_ID data as each manager is an employee

The Manager_ID column should be declared in the relational database as a foreign key

The relationship between these two columns could be represented in a Sentences schema

by defining two entity types Employee_ID and Manager_ID where Manager_ID is

defined as a subtype of Employee_ID

Tables representing subtypes

In some relational databases information about a subtype of a certain object is shown in a

separate table which has additional columns representing attributes of the subtype

In Sentences the entity type mapped to the primary key of the subtype table should be

defined as a subtype of the entity type mapped to the primary key of the original table

Tables representing additional information

In some relational databases attributes for a particular object are shown as columns in

two different tables which share the same primary key In Sentences there is no need to

define a separate entity type for the second tablersquos primary key as there is no practical

limit to the number of associations that may be created with the same source entity type

81



LazyView chapter setup

This section describes the practical procedures for using LazyView

Installing a JDBC driver

To use LazyView you must install the appropriate JDBC driver software for each

relational database you wish to access and make sure that the driver is available to your

Sentences server You must also know the details of how to connect to each relational

database Generally this includes

bull Server Hosting the RDBMS (and port if not the default)

bull Database instance (if applicable)

bull Database name

bull RDBMS User Name and Password

Certain RDBM Systems allow other options such as integrated security and secondary

servers for failover

The JDBC driver is often supplied as a Java archive (JAR) file and you should place this

file in a directory that is accessible to your Sentences serverrsquos classpath

When using the default installation of Sentences Version 40 with Tomcat 41 the

suggested location for the JAR file containing your JDBC driver is

ltSentences_homegtTomcat4webappsSentencesWEB-INFlib

When using the default installation of the Sentences Personal Edition the suggested

location for the JAR file containing your JDBC driver is

ltSentences_homegtresources

You must restart the Sentences server after making any changes to the JAR files available

to it

Indexing the relational database

When you retrieve data from relational database columns using LazyView mappings to

Sentences entity and association types indexed columns show better performance than

columns without indexes We therefore recommend that if you experience slow

performance you build or rebuild the indexes for the relational database columns that you

wish to connect to with LazyView

Java memory and stack requirements

If you wish to use LazyView to access large amounts of data from a relational database

you may need to make more memory resources available to the Java

Virtual Machine For details on how to do this please see the section on the lazystart

script file in the Sentences Userrsquos Guide

Mapping a large Relational Schema can also lead to a large number of Sentences Types

being generated In order to maintain a large Schema the Java stack size may need to be

increased The default stack is 1MB for Linux Unix systems and 512KB for Windows

A stack size of 1MB is sufficient for most large Schemas and this is set explicitly when

using the Tomcat test server To change the stack used see ldquoTomcat memory

configurationrdquo ldquoConfiguring server utilitiesrdquo and ldquoWeb Start configurationrdquo

Adding a LazyView chapter to a profile

The New Profile Wizard will allow you to create a Profile that includes a LazyView

Chapter to connect to a Relational Database For details see the section on Creating a

new LazyView profile using the wizard If you have more advanced requirements then

you can manually create or edit a profile containing LazyView Chapters

82



To create a LazyView chapter that represents a relational database follow these steps

1 In the Sentences Explorer select New profile or Edit profile from the File

menu

2 Start creating a chapter in the normal way by selecting New on the Edit Profile

dialog

3 Define a name and a location for the chapter and select the LazyView chapter

check box on the New file dialog and click OK

4 The Chapter will be added to the Profile and itrsquos Connection properties will be

opened in a dialog

Figure 2-6 Manually specifying LazyView chapter details

5 Select the Database Vendor and JDBC driver and then either select an existing

connection string or enter a new one Any connection strings previously used for

that Vendor in LazyView Chapters is included in the drop-down list

6 If necessary enter the user name and password that are required for

authentication with the RDBM System

7 Most of the time you will require a Dynamic Lazy View Chapter but if you

intend to import a snapshot of the data rather than connect dynamically then

select the Static mode

8 Define the chapter or chapters to be used as the target for schema data or query

changes This cannot be a LazyView chapter

9 Save the profile You may wish to give the profile a new name

The dialog will inform you if the particular JDBC Driver is not available This is usually

due to the relevant Java Archive file not being available to the server on the classpath

Once you save the profile Sentences will attempt to connect to the Relational Database

using the connection properties you have entered If there are any problems making this

connection the reason will be displayed in the Message Log For example

Error 1752 Opening connection Adventure Works rdbms

commicrosoftsqlserverjdbcSQLServerException The TCPIP connection to the

host has failed javanetConnectException Connection refused connect

Dynamic and static LazyView chapters

A Static LazyView Chapter is intended to be used for capturing a snapshot of Relational

Database data Any subsequent changes to the Relational data will not be visible so the

83



data can be updated or re-imported later but the intention is that the data is mainly

referential and does not change often or for performance reasons the reference data can be

held in a local Sentences database

Most of the time you will want to use a Dynamic LazyView Chapter that connects in

real-time to a Relational Database Note that there is a cache of data in Sentences to

improve performance which can be adjusted to balance performance with timeliness

In both cases the Relational Schema will be mapped to Sentences Schema but with a

Static LazyView the data (or a subset of the data) will be imported into a standard

Sentences Chapter file the target chapter for data changes This means that if you

subsequently change the Mode of the LazyView Chapter you must be aware of the

consequences

If the LazyView Chapter was Static and you had previously imported a snapshot of the

data then changing the Mode to Dynamic will have the effect of displaying duplicates of

everything (assuming nothing has changed since the snapshot was taken) You can then

remove the data chapter and see just the dynamic data

If the LazyView Chapter was Dynamic then changing the Mode to Static will mean that

no data will be present You will then have the option to import a snapshot of the data into

a standard Sentences Chapter

Optional connection properties

Some relational databases require that additional properties such as the name of a

database are specified when connections are made to them using a JDBC driver

You can specify these properties in a LazyView connection by appending them to the

connection string The syntax for these depends upon the Database Vendor and the

specification followed by the JDBC Driver manufacturer so consult their documentation

for details

For example to append additional connection string properties for an Oracle My SQL

connection you append

property_name1=value1ampproperty_name2=value2hellip

but for a Microsoft SQL Server connection it would be

property_name1=value1property_name2=value2hellip

Using an existing LazyView chapter

After you have created a LazyView chapter and defined the connection settings for it in

one Sentences profile you can use the chapter in another profile

You can do this by editing the profile that includes the LazyView chapter and saving it as

a new profile or by creating a new profile and selecting the LazyView chapter from the

Add chapter dialog list

The Connection properties dialog for the LazyView chapter is only available after you

save the profile to which you have added it

Copying an existing LazyView chapter

To copy an existing Lazy View Chapter follow these steps

1 In the Sentences Explorer select External Data Sourceshellip from the Tools

menu

2 If there are more than one LazyView Chapters included in the profile then select

the one you wish to copy

3 Click on the Copy LazyView Chapterhellip button

84



4 A Copy LazyView Chapter dialog opens and you can amend any of the

properties including a new name for the copied chapter

5 Click OK to make a copy and refresh the profile

Creating a mapping definition

Once you have a Profile containing a LazyView Chapter you are able to start the

Mapping Wizard to create a mapping definition This definition will be saved with the

LazyView Chapter It will include

o Your selection of which Catalogs Schema Tables and Columns you wish to

map

o Any alternative naming or alternative datatypes for generated Sentences Schema

to remove unwanted duplication and facilitate reuse of the same Sentences

Schema where appropriate

o Choices where the primary key of a table is the entire foreign key to another

table (The choices are whether to represent this as a subset or a subtype)

Your profile will need a target for schema changes to be able to create a Mapping and

generate the resulting Sentences Schema

If the LazyView Chapter is operating in Static Mode then you will be able to specify a

limit to the number of rows to import on any one table Your profile will need a target for

data changes to be able to import a snapshot of the data

Depending upon the size of the Relational Database Schema it may take a while to make

your selections and choices You can save the definition at any point in the Wizard and

return to it later

To create a new Mapping Definition follow these steps


menu

2 If the dialog informs you of restrictions due to a lack of target schema chapter or

target data chapter you can click the Edit Profile button to make the appropriate

changes

3 You will not be able to continue if there are no LazyView Chapters included in

the profile

4 If there is more than one LazyView Chapter in the profile then select which one

you would like to create a Mapping Definition for Otherwise just that LazyView

Chapter will be shown

5 If there is no existing Mapping Definition for that LazyView Chapter then select

Create Mapping Definition to open the Wizard

6 If there is an existing Mapping Definition then select Re-create Mapping

Definition You will be asked if you wish to use the existing definition as a

starting point or create a completely new one from scratch

7 The Introduction Page of the wizard outlines the steps to be taken Select Next

and wait for the available Relational schema to be read

8 The first page shows three lists Catalogs Schema and TablesViews From here

you can select the items you wish to map If you are unsure you can proceed to

the next step to see more details and remove items later

9 Select Next The second page shows the selected Tables and Views on the left

hand side and when you select each one the column and foreign key details are

shown on the right hand side See the screenshot below

85



Select tables and columns

10 The list of tables and views on the left allows you to

Look at View definitions

See whether a table or view has a defined Primary Key

See whether any of the columns or keys are invalid

Select or deselect individual tables and views

Select All None or Only Tables

Figure 2-7 The LazyView Mapping Wizard ndash Selecting tables and columns

11 The Selected TableView columns on the right allows you to

Alter the primary key sequence or assign one if there is none defined (only

mandatory fields can be assigned an alternative primary key sequence) See the

section ldquoTables and views with no primary keyrdquo for more details

Change the Sentences Datatype that this column data will be converted to For

example the database may define the table as a Timestamp but if you know that

it only contains Dates you can change the datatype to Date

Select and deselect individual columns

Select All or None of the columns in one go

The button on the end of each row and the View Sample Data button below the

table will open a dialog that shows you a preview of the data in the relational

database

86



Figure 2-8 Previewing sample data from the RDBMS

You may alter the number of individual values that are returned Note that some kinds of

Relational Column Datatypes do not allow use of the Min and Max functions

12 Also shown on the right is a summary of any Foreign Key references This will display

whether the Foreign Key is available to map to an Association Type or not For

example if it links to a table that you have chosen not to map then the Foreign Key

cannot be used other than importing the raw data as a normal column (or columns)

If Foreign Keys are missing you can create and edit User-Defined Foreign Keys here to

link your tables and views See the section on defining your own foreign keys for details

13 At the bottom of this page are several options that you can choose

Use fully qualified names for Entities and Foreign Key Association Verbs

This means that the schema generated will include the Catalog and Schema

names to ensure that every Column and Foreign Key Reference is mapped to a

unique Sentences Type This is unchecked by default as it more common that

columns in different tables with the same name hold the same kind of data and

can be represented by a single Sentences Type

Convert Names to Proper Case This allows the automatic conversion to

proper case names with spaces between words from databases where the schema

names are all uppercase or Camel Case

Substitute spaces for underscores and full stops When generating Schema

names this replaces any full stops or underscores with spaces

Re-use existing Entity Types If possible reuse the same Entity Types

otherwise append a incrementing number to the name For example Date01

Date02 Date03hellip

Use NOT NULL Constraints This honours the constraint by making the

resulting Sentences Schema mandatory

Group Entity Names for Datatypes This allows two columns to be mapped to

the same Entity Type despite them not having exactly the same datatype For

example two text columns called Description but of different lengths can be

mapped to the same Entity type With this option unchecked the wizard would

insist that the columns are mapped to different Entity Types Similarly two

decimal columns with different precision can be mapped to the same Entity

Type

87



List of Name Translations This allows you to select a named list of

Translations to apply to column and table names For example you might wish to

replace all occurrences of ldquoInfordquo with ldquoInformationrdquo

You can create new Translation Lists and Edit existing ones If you use a

Translation List for a mapping then the name of the list used is saved with the

mapping definition and re-used if you re-run the mapping wizard

See the section Creating and Editing Translation Lists for details of how to create and edit

Translation Lists

14 Select Next to move onto the next page If there are any invalid columns or

tables or none selected you will not be able to move to the next page

SubsetSubtype choices

15 If there are no choices to be made then the page will not be displayed and you

will be taken directly to the next page

16 This page allows you to make choices as to how the schema is mapped for two

specific scenarios Tables where the primary key is the foreign key to another

table and Columns that you may or may not wish to represent with the same

Entity Type

Figure 2-9 Choosing subsets and subtypes

17 The list shows tables where the entire primary key is a foreign key to another

table You need to use your knowledge of the data and schema to determine

which of the two kinds of relationship the tables should have because the

Relational Schema cannot record this The screenshot above shows an example

where we know that a Sales Person does not exist in its own right as a particular

type of Employee It will not necessarily remain a Sales Person throughout its

life So in this case Sales Person is a subset of Employee rather than a subtype

18 Select Next to move onto the next page

New and existing Sentences schema conflicts

19 The next page lists all the columns that you have chosen to map and informs you

of any conflicts that must be resolved before you can continue It also allows you

to perform actions on more than one Entity Type to be generated at once such as

changing all Timestamp datatypes to Date datatypes

88



If we did not previously select the ldquoGroup Entity Names for Datatypesrdquo

option then we may end up with some Columns mapping to the same Entity

Type that have different Relational Datatypes In many situations we will be able

to map the different relational columns to the same Sentences Entity Type

despite having different precision and length because Sentences can

accommodate such variation

By default we map simple column data to Value Types where possible If part of

a Primary Key then the Entity Type cannot be a Value Type because it will need

to be the source of Associations So another reason an Entity Type might be in

conflict is when some columns are part of a Primary Key and others are not This

is resolved by setting all columns to generate Non-Value Types

If you are re-creating the mapping or are adding a new LazyView Chapter to an

existing Profile then there may be existing Schema with the same names as

Schema that is to be automatically generated by this wizard

There are thus two main kinds of conflict that may prevent you from continuing

Columns from different tables may be mapped to the same Entity Type in

Sentences These must have compatible datatypes

Entity Types to be generated may already exist These must also have compatible

datatypes

In addition another conflict that may prevent you from continuing is where there

are more than one mapping LazyView chapter in the profile and the target Entity

Type is already mapped in another LazyView definition

20 The filter section of the page will show if there are Entity Types to be generated

from multiple Relational Columns that have the same names but different

datatypes (or the same datatypes but different value type flags) You can filter

the list to just show these mappings by clicking the button underneath the

message


that already exist but have incompatible datatypes You can filter the list to just

show these mappings by clicking the button underneath the message

22 The filter section of the page will also show if there are Entity Types to be

generated that already exist and have mapping(s) in other LazyView definitions

It would be unsafe to delete and re-create these Entity Types as the other

mapping(s) would be broken You can filter the list to just show these mappings

by clicking the button underneath the message

89



Figure 2-10 The LazyView Mapping Wizard ndash resolving mapping conflicts

Filtering mappings

There are several ways to filter the mapping columns The three kinds of conflict

mentioned above can display only the affected columns by selecting the relevant ldquoShow

the affected column(s)rdquo button

In addition you may enter a name or an SQL datatype to filter the displayed mappings If

you enter several words in the Name filter then they must all appear in either the Type to

be Generated column or the Existing Type column If you enter several words in the

SQL Datatype field then rows with the SQL Datatype containing any of them will be

selected

Finally you can select the Show All Columns button to restore the full list

Resolving conflicts

There are several ways to resolve these conflicts You need to use your knowledge of the

data and schema to determine which method(s) to use

23 It may be that two or more columns are mapped to the same Entity Type but one

will be the source of associations and others are not In this case you may set all

column mappings to generate non-value Entity Types

To do this select all the mapped columns you wish to change (by selecting the

checkboxes next to the icon on each mapping) and select the Set As Non-Value

Types button

24 It may be that two or more columns are mapped to the same Entity Type but

require different Datatypes You may look at a sample of the data by selecting

the button that opens the sample data dialog From this or other knowledge of the

data and schema you may be able to change one or more of the generated

datatypes to match thus allowing the same Entity Type to represent all columns

90




checkboxes next to the icon on each mapping) select the desired Datatype from the

drop-down list and select the Set Datatype button

It may be that the datatype you have selected is incompatible If so then you will receive

a warning dialog such as below

Figure 2-11 Resolving mapping conflicts

In a few cases it may be that you need to override the datatype like this For

example if you are certain that a textual field only contains numeric data


should be distinct Entity Types In this case you may rename the Type to be

generated to have unique names You may either double click in the cell for the

Type to be generated or select it and press F2 Edit the name and press Enter

To facilitate making the Entity Type names unique this page also provides the ability to

o Prepend the selected Types with their Table names

o Add a Prefix

o Add a Suffix

o Reset the names to those originally generated

When changing the names of several columns at a time you have the option of also

renaming the Association Type verbs that are targeted on each Type at the same time

Select the Checkbox next to these options to enable this feature

26 It may be that a Type to be generated already exists but that the datatypes are not

compatible (or one is a value type and the other is not) In this case you may either

delete the pre-existing Entity Type or modify the one to be generated to match

To delete the pre-existing Entity Type(s) select all the mapped columns you wish to

delete the existing type for (by selecting the checkboxes next to the icon on each

mapping) and select the Delete Existing Schema button

Note that it is unsafe to delete pre-existing schema that was generated from a different

mapping definition to a different database because those mappings will be lost You will

be warned if such a situation exists and given the option to cancel the action

In addition to necessary conflict resolution you may also wish to modify several

column mappings at a time This page also provides the ability to

o Include or exclude several column mappings at once

o Delete all pre-existing schema that is safe to delete

91



o Filter the columns shown by name

o Modify datatypes for several column mappings at once

If a relational schema designer has chosen to store a number in a character

column you may specify a Number Datatype Sentences will attempt to convert

the characters into numbers for you

If a relational schema designer has chosen to store a date or time in a character

column you may specify a Date Time or Timestamp Datatype If the date or

time format is not one of the standard ones built into Sentences then you can

define additional formats that will be used to convert a textual representation into

a date or time These additional formats are added to the Serverproperties file by

the System Administrator Here is an example set of etries

DateFormat1= ddMMyyyy

DateFormat2= dd-MM-yy

DateTimeFormat1= yyyy-MM-dd HHmmssSSSZ

DateTimeFormat2= yyyy-MM-dd HHmmssSSS

TimeFormat1=HH~mm~ss

TimeFormat2=HHmm

27 Once all conflicts have been resolved select Next to move to the next page

Summary of schema to generate

28 This page shows a tree of the Schema that is about to be generated when you

select Finish It is still possible to rename individual items in the tree by

selecting them and pressing F2

29 If you are importing a snapshot of static data then you can choose to enter a

value for the maximum number of rows to import This will limit the amount of

data and is useful if you wish to obtain a sample of the data to investigate offline

92



Figure 2-12 The LazyView Mapping Wizard ndash summary page

30 Once you have reviewed the summary select Finish to generate the mapping

definition and schema and import the data if appropriate

Processinghellip

31 As the wizard generates the mapping schema and data it shows you itrsquos progress

Figure 2-13 The LazyView Mapping Wizard ndash processing page

93



If data is being imported then there are additional steps in the process

32 Once complete the Results are displayed Select Close to close the wizard

Figure 2-14 The LazyView Mapping Wizard ndash results page

When types are generated the description field is populated with the catalog schema

table and column or foreign key that led to its generation

The output from a mapping are also saved to a file in the Trace directory with the name

LazyViewMapping_ltmilliseconds timestampgttxt

Creating and Editing Translation Lists

When performing the mapping from an external data source to Sentences you may wish

to automate some of the re-naming of schema For example some of the abbreviations

used in the external data source can be expanded to more meaningful names in the

Sentences Schema

To facilitate this the mapping refinement page of the LazyView wizard allows you to

specify a Translation List to use when generating the mapping You can edit these lists

and if you use a list the mapping definition remembers this if you choose to re-run the

mapping

If two translations match a particular column name then the longer more specific

translation will be used For example with ADDR_=ADDRESS_ and

DESPADDR_=DESPATCH_ADDRESS_ the latter will be used

Creating a new Translation List

From the mapping refinement page of the LazyView wizard follow these steps

1 Select the New Listhellip button The New Translation List dialog will open

2 Enter a name for the list

94



3 You may enter as many translations as you wish You can specify whether each

translation is case-sensitive or not This applies to the From word or phrase not

the To word or phrase

4 You may optionally add one or more exclusions

An example would be where you may enter a translation for Id =gt Identifier

This would replace ProductId with Product Identifier and Holiday with Ho

Identifier day By making it case-sensitive Holiday would not be erroneously

replaced

This does not stop NewIdea being replaced with New Identifierea so an

exclusion for Idea could be added

5 Select Save to save the list If the name you have specified is already in use you

will be prompted to change it to a unique name Once saved that list will be set

as the Translation list to use when generating the Mapping Definition

Editing a Translation List


1 Select the Translation List you wish to edit from the drop-down list

2 Select the Edit Listhellip button The Edit Translation List dialog will open

3 You may add or delete any translations or exclusions

4 Select Save to save the changes to that Translation List or Cancel to cancel the

changes

Figure 2-15 LazyView Mapping Translation List

95



Importing or updating static data

When using a Profile containing a Static LazyView Chapter you can choose to initially

import no data to simply view the schema generated If you are happy with the mapping

then you may wish to subsequently import all or part of the data If the LazyView Chapter

was originally operating in Dynamic mode and you have changed to Static mode then you

will also wish to perform an initial Import

There are several strategies when taking a static snapshot of RDBMS data You may

import the data once and never need to update it again You may wish to import a sample

of the data for experimentation You may know that only new data is added and choose to

periodically update the data or you may know that data is added changed and deleted and

need to keep a record of when those changes happened Finally you may wish to treat the

data as transient and periodically discard the previous snapshot and replace it with an

entirely new one

To accommodate these different strategies there are four types of data update that can be

performed on a Static LazyView chapter

You may already have a complete snapshot of data that you wish to update with the latest

RDBMS data This is a Standard Update in which a note is made of when there is a) no

change b) an addition or c) a target changes Any data no longer in the RDBMS data is

also deleted

You can choose to incrementally update the data without noting these changes and

without deleting any old data This is the second kind of update called an Incremental

Update In addition to this simpler and faster behaviour you can also choose to only add

data since the last update date You can specify date fields to use in each table such that

only rows with dates after the last update date are added For example a Date Created

column Each time a data update is performed the last update date is recorded

The third Replace Data update replaces all data To do this Sentences deletes the old data

chapter and creates a new blank one This update method assumes that the data is

transient This method is faster than the Standard Update method You can optionally

choose to limit the number of rows that are imported as a simple way to test the mapping

with a sample of the data For details of how to choose date columns see Selecting date

columns to limit incremental data updates

The final method Replace Limited Data is intended to import a subset of the data as

defined by a set of Sentences Queries Each set of related tables can have a Sentences

Query assigned to it which is used to limit the rows imported For details of how to create

and assign limiting queries see Creating and assigning limiting queries for a data import

96



Figure 2-16 LazyView Data Update Wizard

To Import or Update the Static Data follow these steps


menu



changes


the profile


you would like to import or update data for Otherwise just that LazyView


5 There is only a single page when importing or updating Static data

6 Select which option for updating you require

7 If you choose to completely replace the existing data then you can additionally

specify a maximum number of rows to import on any one table Again this is

intended to allow you to sample the database

8 Select Finish to start the import Progress is shown similar to that when

originally creating the mapping

Steps when updating the data

Steps when replacing the data

97



9 Once imported the results are displayed Select Close to close the wizard

The output from an Update are also saved to a file in the Trace directory with the name

LazyViewUpdate_ltmilliseconds timestampgttxt

Recorded updates

For each Table we record

the instances that were unchanged

the instances that were added

For each Association mapped from a simple column or a Foreign Key reference we record



the instances where the target was changed

We do not record when the previous target is orphaned

Any remaining instances that were not annotated as such are deleted These would be

found by using the time slider mechanism

Each time an update is performed a new Rdb Update Timestamp instance is created It

is the target of each of the three kinds of association to record these changes The Options

dialog (Select Options from the View Menu) includes a checkbox to determine whether

or not to show the Lazy View Update instances

Selecting this option will display the System Entity Type called Rdb Update

Timestamp and display the individual updates in the data pane

98



Selecting date columns to limit incremental data updates

When choosing to update Static LazyView data incrementally you can choose to specify

date fields to specifically limit the new rows imported to those since the last update date

The last update date is recorded after each importupdate

To choose the date columns follow these steps


menu


the profile


you would like to view the Mapping Definition for Otherwise just that

LazyView Chapter will be shown

4 Select Choose Date Columns for Updateshellip and a Dialog will open showing a

list of tables Each table will display the alternative date columns that you may

choose to limit data updates

5 You can click the Select Defaults button to automatically select columns that

have ldquomodifiedrdquo ldquoupdaterdquo or ldquocreaterdquo in their name (selected in that order)

6 You can click the Clear choices button to deselect all columns

7 You can scroll down the list of tables and manually select or deselect date

columns

8 Once you have made your choices click OK to save your choices

Figure 2-17 Choose Incremental Update date columns

Creating and assigning limiting queries for a data import

The Replace Limited Data data update choice allows you to replace the current data with

a new data chapter and import a limited ldquosubsetrdquo of the RDBMS data The data are

limited by the use of Sentences Queries for each table or set of tables

99



The External Data Sources dialog provides the abililty to create and assign these

queries To view the mapped tables and their limiting queries follow these steps


menu


the profile




4 Select Import Limited Datahellip and the dialog in Figure 2-18 will open showing

the Database Tables and their limiting queries The button will only be enabled

for Static LazyView chapters

The dialog shows each table (and their parent tables) together with the common

type that they are rooted on their row count their limiting queries and the count

of rows that would be imported using the limiting query Both counts can be

refreshed with the Refresh row countshellip button These counts will be saved

with your choices


5 You can edit an existing limiting query by clicking on the Edit Queryhellip button

6 You can create a new query by clicking on the Create Queryhellip button A new

query with the name ldquoltEntity Typegt SQL Limiterrdquo and if one already exists

that one will be edited instead so you canrsquot accidentally create duplicates

Creating limiting queries

Figure 2-19 Limiting query example

100



A Sentences query can be created to limit the rows imported by translating the query

constraints into an SQL statement If a forward request is made mandatory this will

translate to an IS NOT NULL constraint If we add a Selection node then this will be

translated to a WHERE clause For example in Figure 2-19 we limit the countries

imported by saying the country code must be 6009 (United Kingdom) The Selection can

include all operators and functions used in Optimisation Queries If a forward or inverse

request is used that represents a foreign key then an SQL JOIN will be performed

Unlike Optimisation Queries we cannot bind to instances because there are none Instead

using a dynamic profile we need to make a note of all pertinent codes such as 6009 =

ldquoUnited Kingdomrdquo for Country Code and 0 = ldquoMalerdquo 1 = ldquoFemalerdquo for Gender Code

All tables related by foreign keys that are part of their primary key must be linked For

example CUST_CUSTOMER CUST_CRDT_CHECK and CUST_INTEREST are

related through the primary key CUST_CODE of CUST_CUSTOMER If we were to

create a limiting query for CUST_CUSTOMER so that only say Men in the UK were

sampled then we would wish to limit the other two tables at the same time in the same

way Otherwise unneeded data would be imported from the other two tables that could

never link to the CUST_CUSTOMER table

Memory requirements and timeouts

Importing or updating static LazyView data can require a large amount of memory The

performance when importing or updating data is significantly improved by ensuring

Sentences has enough available memory

For relational database tables with large amounts of data LazyView will request the data

in smaller amounts rather than all at once For such large tables this may still take a long

time depending upon the database vendor and communication speeds between the

Sentences server and the Database server

You can adjust the Import Timeout value and memory allocation See ldquoServer propertiesrdquo

for details

Combining databases

A Profile can be used to combine two or more seemingly disparate databases by including

a LazyView Chapter for each database They can be on RDBM Systems from different

Vendors on different Servers All that is needed are the privileges to read the Relational

Schema and Data

Making entity types equivalent

Sentences has the ability to mark two Entity Types as equivalent For details see the User

Guide This mechanism is of particular use when combining databases if you suspect that

two tables hold the same data It will allow you to view the data in an integral way and

identify duplicates or produce aggregate statistics and information

Display name queries

A feature introduced in V40 is the Display Name Query For Details see the section on

Display Name Queries

For data viewed through a LazyView Chapter Display Name Queries are particularly

useful when the main Entity Types such as Employee are represented by a unique

identifier rather than useful information like names If the Employees tables from two

different databases store the names in two separate ways Display Name Queries and

Entity Type equivalence can be used to form a unified list of recognisable entities rather

than identifier data

101



Viewing existing definitions

The current Mapping Definition is saved with each LazyView Chapter and can be viewed

in detail from the External Data Sources Dialog

To view a Mapping Definition follow these steps


menu


the profile




10 Select View Mapping Definitionhellip and a Dialog will open showing the

Database Details and how the available schema has been mapped

11 The first dialog shows the Database details User Details and a table of Catalogs

You can drill-down into more details for Schema Tables and Views and

individual Columns and their properties

Checking for schema changes

The checkbox Check schema before actions on the External Data Sources Dialog will

examine both the Relational and Sentences Schema to see if there have been any changes

since the Definition was created

This includes useful information such as the creation of new Relational Tables and

changes in datatypes

The process of checking can take a long time so by default the schema is not checked

every time

Using LazyView to view data

For Static LazyView Chapters once the data is imported there is no difference in

behaviour between the snapshot data and data entered into Sentences in the usual way and

stored in Sentences Chapters The Static LazyView mechanism is another way to populate

a Sentences Database

Once set up data obtained dynamically will appear and interact with other Sentences data

as if it were stored in Sentences Chapters There are a few special situations that you need

to be aware of when using dynamic LazyView Chapters Firstly the speed of connection

and the particular RDBM System may impact the perceived performance of Sentences

and secondly some limitations that do not normally apply to Sentences will be present due

to the RDBM Systems limitations

Performance

When Sentences displays trees of data it determines whether that tree node has any

children (either forward or inverse associations) and displays a plus sign to indicate that

the tree node can be expanded Because of the differences between how Sentences and an

RDBMS retrieve data it can be quite expensive to calculate whether or not to show a plus

sign when the data is from a dynamic LazyView Chapter

See Determining if child associations are present for details of how to change whether a

Profile attempts to determine if child associations are present

See also the section on LazyView Query Optimisation below

102



Large database fields

Associations in Sentences are always two-way If you can navigate from source to target

then you can navigate from target to source All Sentences datatypes can be searched and

sorted

Relational Databases have self-imposed limitations on these kinds of operation For

example you cannot perform a ldquoLikerdquo function on database columns with large datatypes

like XML You cannot even test for equality if you have an instance of XML that you

wish to find the ldquoparentrdquo of

This limitation hinders Sentences ability to show inverse associations dynamically for

such datatypes

CLOB and NCLOB (Character Large Objects)

NVARCHAR LONGVARCHAR LONGNVARCHAR

SQLXML

BLOB (Binary Large Objects)

LONGVARBINARY BINARY

LazyView Query Optimisation

Sentences queries work very efficiently with Sentences data in the chapter structures that

have been developed in tandem With a dynamic LazyView chapter the translation to the

relational schema can lead to inefficiencies simply due to the differences in data

structures

Static LazyView profiles do not have the same problem as the data is all stored in native

Sentences chapters

With a dynamic LazyView profiles a Sentences query based on an entity type will select

each instance of that Type in turn and apply selection criteria to see whether it should be

included in the results When this translates to a Relational SQL statement all instances

are returned which can take a long time In the relational world joins to other tables and

WHERE clauses limit the initial number of items returned For this reason there is a query

optimisation mechanism built into LazyView that allows an optimised Relqtional SQL

statement to be constructed for each LazyView chapter

The mechanism for this is to create a Subset of an entity type that is mapped to Relational

Schema and tell the subset that it is not a standard subset but an optimisation for a

LazyView chapter This is done by selecting the LazyView chapter that it should be used

in The Sentences query that is defined for the subset is then used to construct an SQL

statement that is used to optimise the instances returned When the subset is included in a

Query (either a normal Query or an Update Query) then the optimised SQL is passed to

the LazyView chapter to be used instead of the plain dynamically constructed SQL This

can have significant improvements on the performance

The best improvement will be seen on the data request node but this functionality is not

limited to that node

Optimisation Queries

The query used to construct SQL will be transformed by taking each request node and

applying a table join andor a predicate where clause if appropriate

Forward and Inverse Requests will lead to joins to other tables if they are the result of a

Foreign Key Mapping

Nodes set as required will translate to IS NOT NULL predicates

Nodes bound to instances will translate to equality predicates

103



Nodes bound to other nodes will translate to predicates linking columns in different

tables

Selection expressions will be parsed into equivalent where clauses Only functions that

translate to an equivalent SQL function can be supported Supported functionality

Sentences Supported SQL Equivalient

AND Yes

CASE No

COALESCE Yes

CONCAT (||) Yes

CurrentUserHasRole No

DEFAULT Yes COALESCE

EXISTS Yes IS NOT NULL

Datatype Constructors No

Entity Type Constructors No

Datatype Functions No

Average Yes AVG

Count Yes

CountDistinct Yes COUNT( DISTINCT ltcolumngt)

FIRST No

LAST No

MAX MIN Yes

Median No

StdDev No

StdDevSample No

Sum Yes

GetClientParameter No

GetCurrentUserID No

GetCurrentUserName No

GetParameter No

GetState No

HasState No

IF THEN ELSE Yes CASE WHEN THEN ELSE END

LIKE Yes

NOT Yes

OR Yes

PriorResult No

VOID Yes NULL

XOR Yes (c1 AND NOT c2) OR (c2 AND NOT c1)

== Yes =

= Yes ltgt

lt gt gt= lt= Yes

- + Yes (divide multiply subtract add)

Derived Types attached to the query node that are independent from the main data request

tree will be available as references to be used in such Selection nodes

Functions that do not have an SQL equivalent such as GetCurrentUserID() will be

evaluated and used in expressions for these independent derived types If a Selection

references any other derived type then that selection will not be able to be used to form a

predicate where clause

The property dialog of a Subset used for LazyView Optimisation allows you to select the

LazyView chapter that it should be used to optimise for because there could be a choice

104



It also allows you to request the actual SQL that will be executed which is useful when

developing the optimisation

LazyView reference

This section gives reference information that may be useful for system designers and

administrators

LazyView parameters in the Serverproperties file

The following parameters in the Serverproperties file are used by LazyView

bull LazyViewCacheTime

You may use this property to specify a default cache timeout for all LazyView

connections The time is defined in seconds and the default value is 10 LazyView always

checks for data in the cache before retrieving information from the database If this

parameter is set to 10 then if a requested data item is in the cache and is less than 10

seconds old the cached data is used and new data for this item is not retrieved

bull LazyViewShowSQL

You may use this property to specify whether or not the SQL statements being submitted

to the RDBMS should be output to the console This would allow for investigation of

lower level behaviour if assessing performance for example

bull LazyViewMultiLineTextThreshold

You may use this property to specify the limit at which textual columns are given a Multi

Line format in Sentences The number of characters has a default of 75 Any textual

columns less than this value will have a Single Line format

bull LazyViewResultSetCacheSize

You may use this property to specify the number of concurrent result set caches to hold

There will be an RDBMS limit to the number of open result sets allowed due to memory

constraints The default size is 1000

bull JdbcQueryTimeout


data dynamically or executing a query in a dynamic LazyView profile The default value

is 5 seconds Setting a value of zero will disable the timeout altogether

bull JdbcImportTimeout


LazyView data import The default value is zero Setting a value of zero will disable the

timeout altogether

bull JDBC Connection Specifications

For each Database Management System Product a specification is required to form the

vendor-specific JDBC Connection Strings There are eight possible values required

1 Jdbc1=The vendor and product name

2 Jdbc1Drivers=A list of drivers (the first will be the default to use)

3 Jdbc1Protocol=the protocol up to the server or service specification

4 Jdbc1Database=the string that is immediately after the server specification

and before the database name followed by a | followed (optionally) by a string

that might mark the end of the database name If no second string is specified

then the rest of the connection string is regarded as the database name

5 Jdbc1Port=the default port number if applicable

105



6 Jdbc1Service=true - if there is no serverport section and the database

name is a service system name file etc

7 Jdbc1Security=the string that is immediately before the integratedSecurity

property followed by a | followed by a string that might mark the end of the

integratedSecurity property This is only applicable to MS SQL Server

8 Jdbc1Instance=the string that is immediately before the instance name

followed by a | followed by a string that might mark the end of the instance

name If no second string is specified then the rest of the connection string is

regarded as the instance name This is only applicable to MS SQL Server

These values need to be repeated for each Database Product you wish to connect to The

second set of properties will be Jdbc2 Jdbc2Drivers Jdbc2Protocol

Jdbc2Database Jdbc2Port Jdbc2Service Jdbc2Security and Jdbc2Instance The

third set will be Jdbc3 and so on

Here are examples of two kinds of Oracle Specifications

Jdbc4=Oracle Thin

Jdbc4Drivers=oraclejdbcdriverOracleDriveroraclejdbcdriverOracleDriver

Jdbc4Protocol=jdbcoraclethin

Jdbc4Database=|

Jdbc4Port=1521

Jdbc5=Oracle OCI 8i


Jdbc5Protocol=jdbcoracleoci8

Jdbc5Database=|

Jdbc5Port=1521

Jdbc5Service=true

107

Database modelling in Sentences

Sentences database design

Chapter 3


This chapter looks at database design on a more practical level and shows some of

the ways in which Sentences implements the concepts of the associative model It

follows on from Chapter 2 Introducing the associative model which described the

concepts of the associative model of data and listed some points of comparison

between the relational model and the associative model

This chapter also introduces the range of user interface design possibilities that are

available in Sentences


In the schema design stage a database designer must decide which of the database

building blocks should be used to represent each element in the real-world system If you

have experience of relational database design and you are now approaching database

design in Sentences for the first time the theoretical points for comparison given in

Chapter 2 Introducing the associative model should help you choose the most suitable

associative model building blocks

Database design skills

Database design involves two activities problem analysis and schema design In the

analysis phase the structure of data in the real-world system under review - the problem

domain - is studied and recorded The analyst discovers how different data elements

relate to each other and how they may be dependent on each other If the analysis stage is

carried out accurately and thoroughly the schema design stage is usually straightforward

A thorough understanding of the real-world system is as important in the associative

model as it is in the relational model Someone skilled in relational schema design should

find that their analytical skills are equally relevant to the associative model

Choosing entity association or value types

Something modelled as an entity type must have an existence independent of other types

in the problem domain In contrast elements modelled as association types are dependent

on their sources and targets As you cannot create association types until you have first

created a number of entity types to be used as sources and targets there is a tendency to

model too many elements as entity types

As a practical test remember that every entity instance must have a name but an

association instance does not have a name If you cannot easily name instances of a given

type this suggests that this type should be modelled as an association Take care not to


If you are unsure about which entity type should be the source for a particular association

type it is useful to remember that associations are dependent on their source This means

that if the source entity type is deleted the association type is also deleted

Value types are a special kind of entity type Value types are used for numerical values

and similar data Any type that is configured as a value type cannot be the source of an

association type but can only be used as the target type

As with any other type of software design it is important that your schema design is a

faithful model of the real-world activities you wish to describe

108






enabled with the server property Check Value Visibility This additional check is disabled

by default See ldquoServer propertiesrdquo for details

Creating verbs for association types

The verb of an association type is used as its name and appears as its field label in the

Dataform It is important that wherever possible you use an active form of the verb rather

than a passive form You should also take care to use the singular form of the verb in an

association type name

It can be useful to include the source type name when you create an inverse verb as this

prevents ambiguity For example the association type Course start date Date could

have the inverse association Date course start date Course

If you have associations with duplicate names (duplicate verbs) either you need to revise

your structure or you need to use more precise verbs (verbs based on the target not on

the English language verb)

For a multiple Association Type you can specify a plural form to be used in Dataforms

and folders in the Data Pane The singular form will still be used for individual

association instances

Modelling one-to-many association types

You can easily model one-to-many association types in Sentences When you want to

create a one-to-many data structure model the one element as the source and the

many element as the target

Iterative design and prototyping

Although detailed data modelling is essential for the design of quality applications

Sentences is a very effective prototyping and iterative development tool You can easily

design a small scale application schema as a prototype for testing and improvement It is

good practice to type in small amounts of test data to verify your structure as you build

Sentences associations can be optional or mandatory It is generally more convenient at

the design stage to create all associations as optional After you have verified your design

you can convert optional associations to mandatory ones as required

Designing for change

You should create a schema that takes account of changes that take place in the real-

world system For example a business unit always requires a manager irrespective of the

name of the person fulfilling the role of manager Your schema should reflect this fact and

take account of possible changes of personnel Schema A (shown below) makes the role

dependent on the person fulfilling it

Schema A

Person fulfills Role

Business Unit utilises (Person fulfills Role)

Schema B (shown below) gives an alternative structure in which the role is not dependent

on the person fulfilling it

Schema B

(Business Unit utilises Role) fulfilled by Person

109

Sentences user interface design options


Modelling behaviour common to multiple types

The associative model has two mechanisms that can be used to support the abstraction of

behaviour common to more than one type in a schema and to support the simultaneous

grouping and separation of instances of related types

bull Supertypes

are used for permanent groupings and indicate that all instances of the type are implicitly

instances of the supertype The reverse is not true An example of the use of a supertype

would be modelling Mammal as a supertype of Primate

bull Subsets

are used to describe a group whose membership is transitory An example is customers

with negative credit which is a subset of customers that depends on the customers

account balance

There is more information about using subsets and supertypes in Chapter 5 Working

with Sentences and in Chapter 6 Advanced techniques

Using instance-specific association types

You can define an association type that has an instance rather than a type as its source

This allows you to add an additional piece of information relating to only one instance

rather than to all the instances of a type For example in a customer relationship

management system you may wish to record the golf handicap of only one customer You

can do this in Sentences by adding an instance-specific association type for example Bill

Smith golf handicap of golf handicap

For more information see Instance-specific association types This association type

does not exist for other customers in your database

If you later decide that an instance-specific association type is relevant for other instances

of the same type you can change the associations source to the type for example to

Customer golf handicap of golf handicap In this case Sentences preserves the

original data you entered

Using chapters and profiles

A users view of an associative database is defined by the profile that they are using A

profile defines a set of chapters and the sum of their contents is the users view A user



design Profiles also define the chapters to which updates are applied (see Profiles and

chapters and Creating database views using profiles and chapters )


When you develop your database application using Sentences you have a number of

different user interface design options each of which has its own advantages and

drawbacks In general if you are able to devote more time to development you can

achieve a greater degree of control over the user interface It is possible that you may

want to use more than one type of interface for your Sentences application

The range of available options include

bull using the standard Sentences Explorer and Dataform interface

bull using custom Dataforms

110



bull using the Dataform Query or Picker applets in HTML pages and using JSPs

bull using an XML-based interface

bull using the Sentences client API

bull using the Sentences End User Application Server This allows you to design an HTML5

web application interface

A range of user interface options are presented in the Application Suite examples supplied

with Sentences Enterprise Edition These are described in detail in the Application Suite

Guide

Using the Sentences Explorer and Dataform interface

The simplest user interface method for a Sentences application is to use the Sentences

Explorer (see ldquo Using the Sentences Explorerrdquo) and the base Dataform (see The

Sentences Dataform)

The advantage of this method is that it requires very little effort as you are using

Sentences as supplied The base Dataform is available as soon as you have designed your

schema and always keeps up with schema changes The drawback of this method is that

you have little or no opportunity to customise the user interface Even so this method is

suitable for many applications

Using custom Dataforms

If you want to restrict the associations presented to your application users you can use the

Query Editor to define a custom Dataform (see Creating a custom Dataform ) You can

also define a custom Dataform as the default Dataform for a type (see The base

Dataform and the default Dataform)

You can give different groups of users different default Dataforms by using different

schema chapters for the profiles of each group (see Creating database views using

profiles and chapters )

Although this method of interface design does give you a little more control than using

only the Sentences Explorer and the base Dataform using custom Dataforms does require

maintenance of your application to ensure that your custom Dataforms keep up with

schema changes

Using applets in HTML pages and using JSPs

You can deploy a Sentences Dataform a Sentences Picker and a Sentences Query using

Java applets For more information see The Dataform applet The Picker applet and The

Query applet

Each applet appears on an HTML page and you have control over the appearance of the

applet and the page Deploying an applet in this way to allows your users to view or

create or edit data in your Sentences database without giving them access to Sentences

Explorer features

You can customise your Web page interface even further by using Java Server Pages

(JSPs) JSPs allow the combination of static HTML content with dynamic information

retrieved from a Web server that differs with each page request The Sentences

Application Suite contains examples of user interfaces developed with JSPs

Developing applets and the Web pages used for their deployment does give you much

more control over user access but requires additional time and effort for creation and

maintenance

111



Using an XML-based user interface

Sentences includes extensive support for data interchange using XML This means that

you can add and retrieve Sentences data without using the standard Sentences user

interface (see ldquoSentences and XMLrdquo)

You can use the query editor to define XML documents and XML DTDs (see The Query

Editor and XML ) and add and retrieve data using servlets (see Servlet access to

Sentences )

If you export data from Sentences in the form of XML documents you can format it with

a stylesheet and display the data on an HTML page There are a variety of commercial

tools available to make this task easier

This method of developing a user interface clearly gives you much more detailed control

over presentation but at the same time demands a much greater effort on your part and

involves the use of third-party tools You should be aware that the XML Standard is still

evolving and therefore some of the tools and technologies used with XML are still under

development

Using the Sentences client API

If you are an experienced Java programmer you can create programs to submit queries

and receive data using the Sentences client API Using the API allows you to use any

available presentation technology such as Java Server Pages (JSPs) or servlets For more

information see Chapter 10 Customising Sentences and also refer to the Javadoc

documentation in the Doc directory of your Sentences installation

This approach gives you complete control over presentation and over update logic for

your Sentences data but entails some development effort

Using the Sentences HTML5 Interface

The Sentences End User Application Server (SEUAS) currently in Beta is a client to

the Sentences Server that can be deployed as a separate web application End Users can

connect to the SEUAS from any HTML5 compliant browser without the need for any

browser plugins or a Java Virtual Machine on their client device

You can create and customise an EUA definition for each Sentences profile This

definition is used by the SEUAS to generate an application suitable for end users You

can specify which Entities Reference types and Reports are exposed to the user

About tree displays in Sentences

The Sentences Quick Tour

113

Chapter 4


This chapter explains the basic layout and appearance of the principal parts of the

Sentences client user interface the Sentences Explorer the Dataform and the Query

Editor

Detailed information about using these Sentences features can be found in Chapter

5 ldquoWorking with Sentencesrdquo Chapter 6 ldquoAdvanced techniquesrdquo and Chapter 7

ldquoSentences queriesrdquo

The topics covered in this chapter include

bull tree displays

bull the Sentences Explorer user interface

bull the Dataform user interface

bull the Query Editor user interface

bull the Message Log user interface


Tree structures are a common representation of hierarchical relationships in computing

They generally comprise a number of elements or nodes that are linked together in such a

way that any node may have no more than one predecessor and any number of successors

The predecessor of a node is called its parent and successor nodes are called children

The node that is the origin of a particular tree and as such has no parent is known as the

root It is customary to place the root at the top of a tree diagram

In Sentences both the schema and the data of the database are represented in the Explorer

as tree structures Tree structures are also used in the Query Editor The tree structure is a

useful graphical metaphor of the relationships between entities and associations even

though the Sentences database is not hierarchical The structure of the Sentences database

actually resembles a net more than a tree as its component elements can be linked to each

other in multiple ways In addition associations in Sentences are not links between

different nodes in a hierarchical tree they are nodes in their own right For more

clarification on the use of entities and associations in Sentences see the section ldquoEntities

and associationsrdquo

The Sentences Explorer quick tour


114


Figure 4-1 The Sentences Explorer

With the Sentences Enterprise Edition the Sentences Explorer runs as either a Java applet

in a web browser or as a Desktop application (see ldquoRunning the Sentences clientrdquo ) In

the Sentences Personal Edition the Sentences Explorer runs as a stand-alone application

The Sentences Explorer has its own toolbar menubar and status bar and is divided into

two panes with the schema displayed on the left and data displayed on the right The

information in each of the panes is shown in a tree display

The following sections look at the various parts of the Sentences Explorer

The Explorer Menu bar

The Sentences Explorer menu bar provides access to a number of pull-down menusThe

menu names and the groups of commands on each menu are listed below

menu namehellip has commands abouthellip

File

Create a new profile or open edit delete and refresh existing

profiles reload data based on Positioner and Filter settings

log out or change password

Edit Edit data and view the selected itemrsquos Properties

View

Change the current Explorer display display additional

database information change user preferences and session

options

Schema Edit and build your schema create and edit Display Name

Queries

Query Use queries and work with query results

Tools

Access to tools for User administration Server configuration

External data sources Diagram editing Text file imports and

the End User Application

Help Help topics Tutorial and support information



115

Some menu commands are only available when certain items are selected in the Explorer

Some menu commands are not available in certain Sentences editions or may be disabled

for certain users For example if the FixedProfile parameter in the applet or jnlp

definition has been set to yes the profile commands are not available

A full list of menu commands is given in Appendix A lsquoMenus and Commands summaryrsquo

The Explorer Toolbar

The Sentences Explorer toolbar is located beneath the menu bar The toolbar buttons give

rapid access to some frequently used commands

Button Description Action

Open Profile use the Open Profile dialog to open a profile

Refresh Profile refresh the data in the current profile

Stop stop retrieving data from the server

Create entity type create a new entity type

Create association type create a new association type

Create query create a new query object

Properties

open the properties dialog for the selected entity

or association open the Query Editor for the

selected query

Cut cut the selected item

Copy copy the selected item

Paste paste the selected item

Delete delete the selected item displays the delete

impact dialog

Dataform

open the Dataform for the selected entity type or

entity instance or association instance

New tab opens a new Sentences Explorer tab on the

selected item

New tab on target

opens a new Sentences Explorer tab on the target

of the selected association

close tab closes the current tab

Positioner valuefield data entry field for the Positioner tool

Filter value field data entry field for the Filter tool

reload data

reloads data using current Positioner and Filter

conditions displays the results of a selected query

help displays help

Copying and Pasting

Any items you cut or copy from the Sentences Explorer Dataform or Query Editor are

held on the operating system clipboard and can be pasted into Sentences or other

applications However you can only paste a Sentences object into the same instance of

Sentences from which it was cut or copied If you paste a Sentences object into another

application or into another instance of Sentences you are only pasting the text

representation of the Sentences object without its unique internal identifiers

Dataform Tables can be copied (using the context menu on the first column) and pasted

into another application such as Microsoft Excel Similarly a range of cells copied from

Excel can be pasted into a Dataform Table providing the datatypes of the columns are

compatible



116

Finding data

For more information about locating data in the Sentences Explorer and using the

Positioner and Filter tools see the section ldquoLocating data in the Sentences Explorerrdquo

Sentences Explorer tooltips

The Sentences Explorer includes tooltips in a number of places If you position your

mouse pointer over the objects listed below you can see a brief explanation of the object

as follows

Position of mouse pointer Tooltip displayshellip

over the toolbar icons a brief explanation of the tool command

represented by the icon

over an association type in the

schema pane

the association typersquos name its cardinality

settings (see ldquoCardinalityrdquo ) and where

appropriate the LazyView connection name and

mapped column or key

over an entity type in the schema

pane

the entity typersquos name and its datatype and

where appropriate the LazyView connection

name and mapped column or key

over an entity instance in the data

pane

the name of the type and name of the instance

and the datatype of the instance (the instance

datatype is not shown if it is identical to the

name of the entity type or if it is ltNonegt)

over the profile schema tab list of the chapters used for schema data and

query changes in the current profile

over a query in the schema pane a list of the queryrsquos parameters and any default

parameter settings

Tree displays in the Sentences Explorer

The Sentences schema tree shown in the Explorer schema pane is made up of all the

entity types association types and values types in the current profile For convenience

these are displayed in the All types folder and Core types folder

The name of the profile is displayed on the schema pane tab Although it is not displayed

as the root node in the schema pane the profile is the parent of all the entity and value

types in the profile Subsequent levels open up below and to the right Moving ldquodownrdquo

the schema means moving away from the root

The data pane displays all the available instances for the association or entity type

selected in the schema pane Each instance functions as the parent node for the display of

all the associations that it takes part in as either source or target

Nodes and icons

Any instance or type displayed in the Explorer is a node in the tree display and can be the

parent of other nodes For example a node representing an entity type is the parent of all

the associations that it takes part in as either source or target

Each kind of node has its own distinctive icon In the schema pane entity types are

represented by magenta cubes value types by magenta discs and association types by

magenta arrows Yellow cubes discs and arrows represent subsets Arrows pointing down

and to the right represent forward association types in which the parent node is the source

Arrows pointing up and to the left represent inverse association types where the parent

node is the target



117

The shapes of the icons used in the data pane match the shapes used for the corresponding

types however they are all coloured cyan rather than magenta

Any association or association type is automatically the parent of its source and target

Source and target nodes are displayed when you double click an association type or

instance or when you select Show source and target from the shortcut menu

Yellow folders in the schema and data pane are used for collections of multiple instances

of the same type of things such as subset and supertype relations between entity types or

multiple associations

The Data Pane can display Page Nodes in the results These Pages are equivalent to the

pages generated in a Base Dataform They are a way of organising associations into

groups See ldquoUser Preferencesrdquo to turn display of Page Nodes in the Data Pane on and off

The Data Pane can display Inactive instances For details of inactive instances see

ldquoInactive instancesrdquo See ldquoUser Preferencesrdquo to turn display of Inactive instances in the

Data Pane on and off

Schema and data pane features

The schema and data pane in the Sentences Explorer share a number of commonfeatures

such as icons and tabs

Schema and data pane icons

The schema and data pane icons are shown in the following list

Icon Description

folder for groups of similar items

has subset or subtype of used for multiple associations

superset of or supertype of used for subset query used for multiple

inverse associations

has subset or subtype of also shows equivalence also shows

custom datatypes

subset of or supertype of also indicates subset query

entity type (magenta)

value type (magenta)

association type (magenta)

inverse association type (magenta)

metatype (magenta)

subset entity type (yellow)

subset value type (yellow)

subset association type (yellow)

inverse subset association type (yellow)

entity instance (cyan)

value instance (cyan)

association instance (cyan)

inverse association instance (cyan)

icon with a mark to the right indicates source of association type or

instance

icon with a mark to the left indicates target of association type or

instance

query



118

Expand node and collapse node buttons

The tree display in both panes of the Sentences Explorer is nested For example

association types are displayed beneath the entity type which is their source An expand

node button [plus sign (+)] is used to show that there are more nested nodes that can be

viewed The expand node button changes to a collapse node button [minus sign(-)] when

you expand the node

The expand node button is displayed in the Sentences Explorer schema pane next to type

nodes that are the sources of any association and in the data pane next to an instance that

has an association instance or an instance-specific association or where the entity type of

which it is an instance is not the source of any association type but only a target

You can double-click a type or instance to display all the associations that it is used in

either as a source or as a target

An association type that is not the source of a further association type does not show the

expand or contract symbol However you can double-click on an association type name

to display its source and target or select Show source and target from the shortcut

menu

Sentences Explorer drill-down

The tree display in both panes of the Sentences Explorer is recursive This means that you

can start navigating at any node and follow any chain of entities and associations through

the schema and data The practice of navigating through the schema and data by

selectively expanding nodes is known as ldquodrill-downrdquo Drilling down gives you

unrestricted access to data by alternative routes as you can follow chains of entities and

associations by clicking on successive source or target nodes

There is no limit to the depth that you can drill down although the data displayed

becomes repetitive at some point

Sentences Explorer tabs

Explorer tabs appear at the top of the data and schema pane The default tab for the

schema pane is the current profile which is the parent node for all the types in the schema

The name of this tab is fixed

When you position your mouse pointer over the profile schema tab Sentences displays a

list of the chapters used for schema data and query changes in the current profile

The default tab in the data pane displays the name of the type that is currently selected in

the schema pane and therefore changes with each selection If no type is selected in the

schema pane the data pane default tab displays the profile name

You can modify the display in the schema pane and the data pane by selecting a different

object to be the temporary root of the current display This can aid viewing when working

with a large database You can highlight any object and create a new view based on it or

in the case of associations and association types based on the target Each view is

displayed on a separate tab page in the schema or data paneThese views are temporary

and are not saved



119

Figure 4-2 Example of Sentences Explorer tabs

You can use the blue arrows on the toolbar or the Create Tab commands on theView

menu to create and remove tabs

The root tab in the schema pane always shows the name of the current profile Any

schema type can be made the root of a new tab If the selected item is an association or an

association type you can open a new explorer tab on the items target You can open as

many tabs as you need

The data pane always shows the instance data for the active schema pane selected type

When you switch between schema tabs open data pane tabs are closed and are not saved

Tabs can also be removed using the Remove Tab command which is on the tab shortcut

menu and on the View menu or by clicking the Remove Tab toolbar button You cannot

remove the original default tabs

The schema pane

The schema pane is used to develop and display the structure or schema of your

Sentences database This pane displays entity value and association types The data pane

is used to display specific information about the entity value and association instances in

your database



120

Figure 4-3 The Sentences Explorer Schema pane

The left-hand schema pane always shows the schema folders Core types Core queries

All types and All queries

All the types queries in your schema are always listed in the All types and All queries

folders respectively The Core types and Core queries folders are convenient ways of

displaying the most frequently used types and queries

When you select schema in the schema pane the instances are requested and displayed in

the data pane If you are not concerned with viewing the data you can hide and show the

data pane by selecting Data Pane Alt-D from the View menu

Finding schema

With large schemas the Schema Filter can be used Typing into the filter text box at the

bottom of the schema pane will limit the schema displayed as you type Unlike the

Positioner and Filter tools you cannot use wildcards but you can enter multiple words

The schema folders will have a filter icon next to them when they are not showing the

entire contents

The Core types folder

The Core types folder displays a selection of entity types most central to your schema

When you create a new profile you can choose to select the types for the Core types

folder yourself or you can allow Sentences to select the types automatically

If you allow Sentences to select types automatically then any entity type which is the

source of an association which is itself the source of a further association is displayed in

the Core types folder When you allow automatic selection for the Core types folder if

there are no association types in the current schema that are sourced from association

types then nothing is displayed in the Core types folder

If you choose to make the selection for the Core types folder manually you can select an

entity type by checking the Display in core types folder check box on the General page



121

of the Properties dialog Alternatively right-click on an entity type and select Display in

Core types folder from the shortcut menu

The Core queries folder

The Core queries folder displays a selection of queries most central to your schema

There is no automatic selection option for the Core queries folder You must always

choose the queries that you want to display in the Core queries folder

To display a query in the Core queries folder right-click on a query name in the schema

pane and select Display in Core queries folder from the shortcut menu

The All types folder

The All types folder contains all the entity and value types in the current profile

including those in the Core types folder You can build your database schema by adding

entity types and association types in the All types folder Association types are displayed

beneath their source entity types and inverse associations are displayed beneath their

target entity types You can use the expand node buttons to drill-down through the

schema

The All queries folder

The All Queries folder displays a list of all the queries in the current profile

You can also execute a query in the Sentences Explorer Select a query name and choose

Execute Query from the shortcut menu or from the Query menu The results are

displayed in the Explorer data pane

The data and properties pane

Figure 4-4a The Sentences Explorer Data Pane

The data pane displays the entity value and association instances that make up the data

in the database The characteristics of the entities and associations are determined by the

properties of the corresponding association types and entity types

The display of data is always nested allowing easy movement from entities to

associations In the data pane you can drill down from an entity to an association and

from there to another associated entity without any practical limit The data displayed







122

Figure 4-4b The Sentences Explorer Data Pane - Table view

If enabled in the user preferences you can view the data as a table rather than a tree of

data This limits you to viewing only singular Association Types The TableTree view is

changed by selecting the icons on the tab In the above case to the right of Group

company

Figure 4-4c The Sentences Explorer Schema Properties Pane

If enabled in the user preferences you can view the peoperties of the selected schema in

the right hand pane This allows you to quickly view and amend schema propertiesScroll

bars

The Sentences Explorer displays horizontal and vertical scroll bars automatically

whenever the amount of data to be displayed in either pane is too large for the space

available

The Status bar

The status bar is at the bottom of the Sentences Explorer window On the left-hand side is

a status indicator which displays either Workinghellip or Ready

In the centre is a display of the number of instances displayed This display does not

appear if there are more instances on the server which have not yet been loaded on to the

client In this case the Morehellip prompt is displayed at the end of the list of instances in

the data pane



123

On the right-hand side of the status bar is a server connection indicator The indicator next

to the server name is green when you have a valid server connection

Divider bar

The schema pane and data pane are separated by a divider bar You can drag the divider

bar to any convenient position in the Sentences Explorer Click the upper left facing

arrow to hide the schema pane and display only the data pane Click the lower right

facing arrow to hide the data pane and display only the schema pane

You may also use F8 to select the divider bar and then use the left and right arrows to

move it Use the Tab key to deselect the divider bar

Shortcut keys

Sentences windows menus and dialogs support keyboard shortcuts and accelerators The

shortcut key character is indicated with an underscore in menu listings Press Alt and the

shortcut key to use the accelerator Sentences also uses standard shortcuts On Windows

the Ctrl key and on Mac OS X the Command key ( ) are combined with the keys C V

and X for copy paste and cut respectively

Sentences specific shortcuts are

Ctrl+D default Dataform

Ctrl+P Properties dialog

Ctrl+N New Profile dialog

Ctrl+C Open Profile dialog

F6 toggle between schema and data panes

You can press the Tab key to move between fields in any Sentences window or dialog

You can use the up and down arrow keys to select menu items and you can use the Esc

key to close a menu You can use the left and right arrow keys to move the cursor in

editable fields and you can use the Home and End keys to go to the top and bottom of

lists of data Using the Page Up and Page Down keys to page through the displayed data

If there is more data in the database than Sentences can display in the current pane the

Morehellip prompt is shown Double-clicking the Morehellip prompt or pressing the Page

Down when the Morehellip prompt is highlighted retrieves more data items (see ldquoDemand

loading of datardquo )

All the available shortcut keys are listed in Appendix A lsquoMenus and Commands

summaryrsquo

Display Session Options

There are several options that you can choose from that last for the duration of the

session after which they revert back to their defaults

To view the Session Options select Session Optionshellip from the View menu or select

Optionshellip from the status bar context menu



124

Figure 4-5 The Session Options dialog

You may want to see which objects in your Sentences database are stored in which of

your profile chapters and you may want to be able to distinguish between different

objects that have the same display name You can do this by displaying the internal

identifiers that Sentences uses for chapters and other objects

There are three possible settings for the Options dialog None (the default) Chapter

numbers and Chapter numbers and Object IDs If you select Chapter numbers

Sentences displays a number next to each item displayed in the Sentences Explorer

representing the database chapter in which that object exists for example [2] The number

corresponds to the position of that chapter in the available chapters list in the Edit Profile

dialog

If you select Chapter numbers and Object IDs Sentences displays next to each item

displayed in the Sentences Explorer a number representing the chapter file followed by a

number representing the object in the chapter files (its surrogate) for example [22097]

The storage chapter location is significant for entities and associations but not for values

as they are stored in all the chapters in a profile For this reason Sentences displays a large

number above 32000 as the chapter number for values



125

Figure 4-6 Sentences Explorer view with Chapter numbers and Object IDs option

selected

The Session Options also include options for using the Sandbox functionality (see

ldquoSandbox Modesrdquo) and setting the Transaction Visibility timestamp (See ldquoTransaction

Visibilityrdquo)

Support information

You can view a list of currently set parameters and other information useful for technical

support and diagnostic purposes in the Support Information pages

To view this information select About from the Help menu and then click Support

Information The information is divided into three sections as shown in Figure 4-7

Figure 4-8 and Figure 4-9

Figure 4-7 General support information page



126

Figure 4-8 Client parameters information page

Figure 4-9 License information page

In the Enterprise Edition the Support Information display shows the Chapter Version

and Communications Version numbers (which are internal references for support

purposes only) a list of any client parameters that have been set (see ldquoUserdefined

parametersrdquo ) and a list of certain applet parameters if they have been set (see ldquoSentences

applet parametersrdquo ) In the Personal Edition application parameters are shown instead of

applet parameters (see the Personal Edition Supplement for details)



127

Explorer shortcut menus

Figure 4-10 An example of a shortcut menu

When an object is selected you can display a shortcut menu by clicking the secondary

button on your mouse or by pressing Shift + F10 on your keyboardEntity types

association types entities associations queries and parameters displayed in the Sentences

Explorer all have shortcut menus associated with them

The command options on these menus are taken from the Schema menu the View menu

and the Edit menu The keyboard shortcuts available with each command are also

displayed on the shortcut menu The commands available differ from time to time

according to the circumstances

If the selected item is a hyperlink in the data pane the shortcut menu includes a Follow

Hyperlink option

There are separate shortcut menus available for each of the system folders and for queries

The Dataform quick tour


128


The Dataform is Sentencesrsquo unique dynamic format for creating editing and browsing

data Dataforms are created automatically from the Sentences schema and display the

associations sourced from a type

A typical Dataform is shown in Figure 4-11

You can open the Dataform for an object by selecting Default Dataform from the

shortcut menu or by pressing Ctrl + D or by clicking the Dataform button on the toolbar

Figure 4-11 A typical Dataform

Different kinds of Dataform

Sentences can create a Dataform which automatically displays all the associations sourced

from a specified type This is known as the base Dataform You can use the Query Editor

to design and save a custom Dataform that may only display a selection of the available

associations for that type A custom Dataform can include associations that use the

specified type as their target You may define either the base Dataform or a custom

Dataform as the default Dataform for a type

For more details see ldquoThe base Dataform and the default Dataformrdquo

If a dataform contains fields which are calculated then it will by default automatically

refresh these calculations whenever a field is changed This ldquoauto-refreshrdquo function can be

turned off by unchecking the box at the bottom of the dataform

You can open a Dataform on an entity type and use it to create new associations This is

known as a Create Dataform You can also open a Dataform on any instance which can be

used to update existing associations This is known as an Update Dataform For more

details about Create Dataforms and Update Dataforms see ldquoCreate and update

Dataformsrdquo



129

You can often open a new Dataform from a field on an open Dataform using the shortcut

menu for the field In most cases changes you make in these Dataforms do not effect the

original Dataform For more details see ldquoParent Dataforms and child Dataformsrdquo

You can display a Dataform from the Explorer or from another Dataform and you can

also configure a Dataform to run in its own Java applet so that it can be displayed on its

own or as part of some other suitable web page For more details see ldquoThe Dataform

appletrdquo

Title bar

The Dataform title bar always displays the name of the source object of the associations

being displayed This source object may be an entity or an association On a Create

Dataform the title bar is always New xxx where xxx is the name of the entity or

association type

Dataform tabbed pages

The associations displayed on a Dataform may be distributed on two or more tabbed

pages as illustrated in Figure 4-11 If the type or instance for the Dataform has subsets or

supertypes or has an equivalent type the base Dataform has multiple pages one for each

of these related types If you create instance-specific associations they are displayed on a

separate tab when the Dataform for that instance is displayed For more information see

ldquoSubsets properties pagerdquo ldquoSupertypes properties pagerdquo and ldquoEquivalence properties

pagerdquo

The base Dataform displays the source object as an instance of its own type an instance

of any of its supertypes an instance of its superset type an instance of any of its

supersets subset types or an instance of its equivalent types simultaneously The base

Dataform creates a tabbed page for each of these types for which one or more associations

exist A custom Dataform creates tabbed pages as required for the association types

selected for it You can also add Page nodes in the Query Editor to create additional

tabbed pages on a custom Dataform (see ldquoPage Nodesrdquo )

For example the Dataform shown in Figure 4-11 above is from the Human resources

example application in which Employee is a subtype of Person and Resource is a

subset of Employee Employee Resource and Person are each the source of

association types The result is that these three related source types are each represented

by tabs on the Dataform

Further examples of the way using subsets and supertypes affects the display of the

Dataform are given in Chapter 6 ldquoAdvanced techniquesrdquo (see ldquoDataform tabbed pages

with subsets and supertypesrdquo )

Labels and fields

The Dataform displays two objects a label and a field for each of the source objectrsquos

associations The label is based on the verb of the association and the field is where you

can create or update the target for the association

The presentation format of the target field is based on the Format settings in the

Properties dialog for the target object For example a multiple association (an

association that permits more than one target for the same source) is displayed on the

Dataform with a multiple line entry field

The labels of mandatory associations are marked with an asterisk () on theDataform

Sentences does not allow you to save a Dataform if you do not supply a value for a

mandatory association



130

Ellipsis button and picker lists

Some Dataform fields have an ellipsis button to their right You can use this button

to select a target from a list of existing target type instances

Figure 4-12 A picker list from a Dataform ellipsis button

When you click the ellipsis button Sentences displays a picker list showing all the

available instances of the associationrsquos target Every picker dialog includes the Positioner

and Filter tools to help you select the target you need If there are more target items than

can be displayed the picker list includes the Morehellip prompt

Dataform shortcut menus

Figure 4-13 A Dataform shortcut menu

The Query Editor quick tour


131

The options in the shortcut menu from a Dataform field allow you to open additional

Dataforms to view or create instances

Sentences uses the association verb and target type names and the current target instance

name as the names of the shortcut menu options The available options include viewing a

Dataform for the current association viewing a Dataform for the current target instance

creating a new association creating or selecting a new target and deleting the current

association If the target is a hyperlink the shortcut menu includes a Follow Hyperlink

option


Figure 4-14a The Query Editor

A full description of the Query Editor including details of how to create and edit queries

is given in Chapter 7 ldquoSentences queriesrdquo This current section describes the main

features of the Query Editor window

Figure 4-14b The Query Editor - Properties



132

Rather than open a dialog to edit the properties of each request node the right hand pane

now contains a Schema tab and a Properties tab When you select different query nodes

the appropriate properties are displayed in the right hand properties tab Note The Query

Editor used in Sentences version 1 is now referred to as the Set Query Editor If you need

information about using set queries and the SetQuery Editor please contact

supportsentencescom

Query Editor menu bar

The Query Editor menu bar contains the following menus

Menu namehellip has commands about

Query saving a query and query properties

Edit adding request nodes derived type nodes and sort and

selection nodes

closing binding and hiding nodes editing expressions

standard editing actions query node properties

View expanding and collapsing the request or result tree

Parameter creating and using parameters

Results execute a query export a CSV file export DTD export or

view XML results export XSL stylesheet

Dataform testing a custom Dataform

Help accessing help information

Query Editor toolbar

The Query Editor has the following buttons


Execute execute (run) the query


Save save the query

Properties

view or edit the properties for the

selected node




Delete

delete the selected item displays

the delete impact dialog

Dataform

display the default Dataform for the

selected item

Custom Dataform

display the custom Dataform for

the selected item

Expand Tree expand all the nodes in the tree

Collapse Tree collapse all the nodes in the tree

Expand Node expand the current node

Collapse Node collapse the current node

Query Editor icons

The icons used in the query request tree for nodes are similar to those used in the schema

pane for association entity and value types



133

Similar icons are used in the query result both in the query results pane of the Query

Editor and in the Sentences Explorer Query result icons are always displayed in green to

distinguish them from database instances

Icon Name

query name

entity type node (magenta)

association type node (magenta)

value type node (magenta)

forward or inverse request node in a recursive closure loop

derived type node

page node

result entity (green)

result value (green)

result association (green)

expression

selection node

sort node

transitive closure node

Error

Query pane

The query pane occupies the top left hand side of the Query Editor window This is where

you build your query by creating a query request tree

Schema pane

The schema pane occupies the right hand side of the Query Editor window This pane

contains a copy of the contents of the All types folder from the Sentences Explorer

schema pane After you start building your query the Query Editor schema pane displays

only those types that could be used at the currently selected query node You can drag and

drop or copy and paste the entity and association types you need to use in your query

from here

Results pane

The results pane occupies the bottom left hand side of the Query Editor window When

you execute your query the results are displayed here If the query takes longer than a few

seconds then a progress panel appears to show you when the query started the duration

and how many instances have been processed so far The instances are a count of root

items even if they have subsequently been excluded from the final results but gives you

and idea of progress if you know how many items there are in total

Query Editor status bar

The status bar is at the bottom of the Query Editor window and has two parts the status

indicator which usually says Ready and an item counter

The item counter indicates the number of items in the query results set currently loaded in

the data pane which may be less than the total number in the database (see ldquoDemand


The Message Log


134

Query Editor divider bars

There are two divider bars in the Query Editor window a horizontal bar between the

query pane and the results pane and a vertical bar between these two panes and the

schema pane

You can drag the divider bar to any convenient position in the Query Editor Click the

arrows on the divider bars to snap them to the appropriate edges of the Query

The Message Log

Sentences displays a message in the Message Log whenever it is unable to complete an

action you requested The message that Sentences displays should help you identify and

resolve the problem For example if you try and save a Dataform without giving a value

for a mandatory association field Sentences displays the Message Log with a message

reminding you to complete the mandatory field

Sentences displays the Message Log when an error occurs anywhere in Sentences

including the Explorer the Dataform and the Query Editor

You can view the Message Log at any time by selecting Messages from the View menu

Sentences messages are classified in three groups Errors Warnings and Information

and you can use the check boxes on the message log display to select which kinds of

messages you wish to see

Figure 4-15 The message log

You can copy the text of messages from the message log by using the Copy command on

the shortcut menu for the message log You can then paste the message text into another

application using the appropriate commands for your systemEditor window

Profiles and chapters

Working with Sentences

135

Chapter 5


This chapter describeshow to work with Sentences to design create and use a

database

The topics discussed in this chapter include

bull working with profiles and chapters

bull using the Sentences Explorer

bull locating data in the Explorer

bull properties datatypes and formatting

bull working with the Dataform

bull working with the Dataform Picker and Query applets

bull data exchange with external formats


A Sentences database is highly flexible being made up of chapters which are files in

which data is stored and profiles that define which chapters are visible to usersThis

flexibility means that you can control access to certain kinds of data in your database by

excluding or including the chapter containing that data in a particular profile

Both the structural schema information and the data content of a Sentences database are

stored in chapter files User access to the database is through a profile which is a selection

of one or more of the database chapters Different users may use different profiles with a

different selection of chapters to access the same database (see ldquoCreating database views

using profiles and chaptersrdquo )

Updates and changes to the schema or data information in a database are stored in

chapters that you specify when you create or edit a profile (see ldquoUsing the Edit Profile

dialogrdquo ) Using separate chapters for schema data and query changes allows you to

separate schema information from data information in your database and to create

different views for different users and therefore this is strongly recommended For more

details see ldquoUsing multiple profilesrdquo 0 and ldquoCreating database views using profiles and

chaptersrdquo

In addition to the chapters defined as changes chapters a profile may contain other

chapters The schema and data information in these chapters is available to

Sentences and is displayed and used in the profile but any updates and changes are made

only to the defined changes chapters

All the commands concerned with managing chapters in a profile including creating

adding removing and defining changes chapters are accessed through the Edit Profile

dialog

Data and schema updates

All data or schema changes made using the Sentences client are updated to the database

as soon as they are executed This means that when you select Save or Delete in any

Sentences Explorer dialog or select Save Save amp Reset or Save amp Edit in the

Dataform your changes are applied to the database immediately



136

You must select the Save command to save queries when you are using the Query Editor

Any Dataform that has an Apply or an Apply amp Reset button is known as a child

Dataform Changes you make in a child Dataform are only saved to the Sentences

database when the parent Dataform is saved (see ldquoParent Dataforms and child

Dataformsrdquo) In some circumstances the server may not accept the update (see

ldquoTransaction processing in Sentencesrdquo)

If you make changes in the Dataform and close the Dataform without clicking on Save

the changes you made are not saved Sentences displays a warning message if you close a

Dataform that contains unsaved selections

Chapter file locations

You can place your database chapters in one or more defined locations The possible

locations must be listed in the Serverproperties file under the ChapterPathList

property (see ldquoThe Serverproperties filerdquo) The first location listed for this property is the

location you selected for chapter files when you installed Sentences This is the default

location for all chapter files including the system chapters

The defined locations may be on one or more computers which can be accessed as local

or network drives When you create a new chapter you must specify the location from the

drop-down list in the New Chapters dialog The directory path names that appear in this

list are based on the paths as viewed from the computer running the Sentences server

System chapters

Sentences uses three system chapters Metaschemachap Schedulerchap and

Profileschap When you install Sentences these chapters are placed in the location you

specify for chapter files You can move these files to another location but if you do so

you must specify the new location under the SystemChapterPath property in the

Serverproperties file You must shut down the Sentences server before you move the

system chapters

Metaschemachap contains information that is internal to Sentences It does not contain

any user-visible or user-modifiable data You should not delete this file or attempt to

modify it in any way If this file is deleted accidentally Sentences creates a new copy of

this file when the Sentences server starts up

The Profiles database and the Profiles profile

The system chapter Profileschap contains information about all the profiles in your

Sentences installation Do not delete this file or attempt to modify it in any way If this

chapter file is deleted accidentally Sentences creates a new copy of it when the Sentences

server starts up A new copy of profileschap created by Sentences does not contain

any information about your profiles In this situation use the Edit Profile dialog to create

all the profiles you need including the example profiles included in a default Sentences

installation

Sentences includes a system profile named Profiles that is hidden from users by default

This profile contains one chapter Profileschap and constitutes a profiles database

This profile can be addressed using the Sentences API

To make this profile visible to users and to view the profiles database in the Sentences

Explorer you can set the optional applet parameter ProfileProfileVisible to Yes (see

User-defined parameters) You cannot give the name Profiles to a profile that you create

and you cannot delete the Profiles profile if it is visible

Sentences 40 extends the Profiles database and profile to include User Security details

As a User Administrator you may open the Profiles Profile to administer users by

selecting Administer Users from the Tools menu



137

The Profiles profile now includes two additional queries The first is used to export the

Users and their privileges This can be used in conjunction with the original two queries

for exporting chapter and profile information

Another new query identifies Chapters that have been orphaned Orphaned Chapters are

no longer used by any profiles This is useful when housekeeping the chapter directories

System administrator passwords

With the introduction of a User Security model the System Administrator requires an

initial password which must be changed at first login to the system

For the Personal Edition this is hard-coded as ldquoSys Adminrdquo For the Enterprise Edition

each license file contains itrsquos initial encrypted password

If the System Administrator looses their password then the only way to regain access is to

delete the Profiles profile This will restore the original password that came with the

license file but you will loose all your chapter profile user role and privilege

information

It is advisable to use the built-in queries to regularly back-up the profiles database The

individual user passwords will not be exported in plain text

Using multiple profiles

You can create multiple profiles that use different selections of chapters from the same

database A userrsquos view of the database is defined by the sum of all data and schema

updates in the chapters of their profile and therefore different users can have different

views of a single database You can use the profile mechanism to customise different

Sentences views for different users For more details see ldquoCreating database views using

profiles and chaptersrdquo

Profile and chapter commands

The Sentences Explorer File menu includes commands for creating opening editing and

deleting profiles

Command name Action

New Profile displays an empty Edit Profile dialog

Open Profile displays the Open Profile dialog

Edit Profile displays the Edit Profile dialog with details of

thecurrent profile

Delete Profile displays the Delete Profile dialog

Refresh Profile closes and reopens the current profile

You can export a database and the profiles it contains and import the chapters that make

up the database using server commands For more details see ldquoExporting and importing

databasesrdquo

Profile and chapter constraints

You must be aware of the following constraints in the use of profiles and chapters

bull A schema definition specifies separate changes chapters for schema data and query

information Users can only save updates to the database if the definition of the current

profile includes an appropriate changes chapter For example if the profile definition does

not specify a query changes chapter users cannot save any changes they make to queries

(see ldquoChanges chaptersrdquo)



138

bull When the FixedProfile parameter in the jnlp or javascript definition is set to ldquoyesrdquo

the profile commands on the File menu are not available and users cannot change their

Sentences profile (see ldquoSentences Applet Parametersrdquo)

bull The EditOption parameter in the jnlp or javascript definition can restrict a userrsquos

ability to change parts of the database For example when the EditOption parameter is

set to data users cannot save changes to the schema even if a Schema changes chapter is

specified in the Edit Profile dialog (see ldquoSentences Applet Parametersrdquo)

bull You cannot open or edit a profile if one or more of the chapter files used in the profile is

no longer available for example if it has been deleted from disk In this case you can

create a new profile with valid chapter files and give it the same name as the profile that is

no longer valid and this overwrites the previous invalid profile information

The Open Profile dialog

Figure 5-1 The open profile dialog

All the profiles available are shown in the Open Profile dialog The list of available

profiles is controlled by the Profileschap file on the Sentences server

You can only use one profile in any Sentences session at any time Opening a profile

closes any previous profiles However you can run more than one Sentences session at a

time

You can open the Open Profile dialog by selecting the Open Profile command on the

File menu or the Open Profile button on the Sentences Explorer toolbar

Creating a new profile

To create a new profile select New Profile from the File menu Sentences displays an

empty copy of the Edit Profile dialog See the section below for details

Creating a new profile with the profile wizard

Version 40 introduces a New Profile Wizard to assist with the repetitive task of creating a

new Profile with one data chapter and one schema chapter set as the appropriate targets

for data schema and query changes

The wizard also helps with the creation of Profiles that can dynamically or statically

connect to Relational Databases

Creating a new standard profile using the wizard

To create a new standard Profile follow these steps



139

1 Select New Profile Wizardhellip from the File menu The New Profile wizard will

open The default choice is to create a Standard Profile so you can leave this

unaltered

2 Enter a name for the new profile

3 If you select Show Advanced to view the advanced properties you will see that

the profile name you have entered is used to generate the default name for the

schema and data chapter

4 You may optionally enter a description

5 The Core types folder displays a selection of the types in your schema The

selection of types for this folder can be manual or automatic To choose

automatic selection check the Generate core types automatically checkbox To

choose manual selection leave this checkbox unselected

6 Determining whether a tree node has any children can be quite a time consuming

process so for very large databases you have the option for a Profile to assume

that child associations are present and always show a plus sign To choose to

assume that child associations are present unselect the checkbox

7 Select Finish to create the new profile

Creating a new LazyView profile using the wizard

To create a new LazyView Profile follow these steps


open

2 Select External Data




140

If you select Show Advanced to view the advanced properties you will see that









process especially for dynamic LazyView profiles For these and very large

databases you have the option for a Profile to assume that child associations are

present and always show a plus sign To choose to automatically determine

whether a tree node has any children select the checkbox

7 Select Next to progress to the next page



141

The second page allows you to enter details of the database you wish to connect to

8 Select the Database Vendor There may be several different database versions for

each vendor

9 Enter the Server name where the database is located If you have connected

successfully to that database before then the drop-down list will contain the

server and you can select it from the list

10 Enter the Database name If you have connected successfully to that database

before then the drop-down list will contain the name and you can select it from

the list

11 For Microsoft SQL Server only you have the option of selecting Integrated

Security If so then your Windows credentials will be used to connect to the

database

12 If Integrated Security is not available or desirable then enter the username and

password that will allow you access to the database

13 By default once a LazyView Profile has been created the LazyView wizard will

be opened for you to define the mapping between relational database and

Sentences You may optionally deselect the checkbox if you do not wish to

perform the mapping immediately

If you select Show Advanced to view the advanced properties you will see that the

profile name you have entered is used to generate the default name for the Lazy View

chapter



142

14 You may optionally change the Lazy View chapter name

15 You may optionally choose an alternative JDBC Driver

16 You may optionally change the port number used to connect to the database if it

is not the default one shown If you have connected successfully to that database

before then the drop-down list will contain the ports used previously and you

can select it from the list

17 The option choices dictate whether you would like to connect statically or

dynamically to the database For details see the LazyView - Using Sentences to

view relational databases section

18 You can click on the Test Connection button to test your connection parameters

If you do not the connection will be tested when you select Finish

19 Select Finish to create the profile and launch the LazyView Import Wizard (if

requested) or Back to return to the previous page

The Edit Profile dialog

Figure 5-2 The edit profile dialog

The Edit Profile dialog is displayed when you select either New Profile or Edit Profile

from the File menu When you select New Profile the Edit Profile dialog is displayed

with no information When you select Edit Profile the Edit Profile dialog is displayed

with the settings for the current profile

Using the Edit Profile dialog

The Edit Profile dialog is shown in Figure 5-2

bull Profile name

Enter a name for the profile in the profile name field You can refer to a named profile in

the jnlp or javascript definition for the Sentences client applet in the start up pages for



143

other Sentences applets and when using the Sentences API Because of this you should

make sure that profile names do not include any special characters that need to be

represented by escape sequences in HTML which may not be interpreted correctly by

Sentences

Note The name Profiles is reserved for the system profiles database and cannot be used for

user-created profiles (see ldquoThe Profiles database and the Profiles profilerdquo )

bull Renaming a profile

You can change the displayed name of a profile by entering a new name in the Profile

name field Sentences does not actually rename the profile but creates a new profile with

the new name you have entered If the new name is the same as that of an existing profile

the existing profile is overwritten

If you only change the case of a profile name when you edit it this does not create a new

profile

You can reset the profile definition used on a client to be the same as the current saved

version of the profile by selecting the Refresh command on the File menu or by clicking

the Refresh button on the toolbar

bull Profile description

You can optionally enter a description for the profile that will appear in the Open Profile

dialog

Chapters

The chapters field lists all the chapters that are available in a profile (the available

chapters) The schema and data information in all the available chapters is displayed and

used in the profile

Changes to schema data or query information are saved in the specific chapters defined

for schema data and query changes

Changes chapters

Use the Edit Profile dialog to set the active chapters which Sentences uses for updating

changes to the schema data and queries of your database These are known as the

Schema changes Query changes and Data changes chapters

Although you may use the same chapter for more than one of these change chapters using

separate chapters makes it easier to create different profiles for different users

A user may save changes to the database only if the appropriate changes chapter is

defined in the Edit Profile dialog This means that if a Schema changes chapter is not

specified users cannot save changes to the database schema and if a Data changes

chapter is not specified users cannot save changes to database data If a Query changes

chapter is not specified users can create new temporary queries and run them in the

Query Editor and make temporary changes to existing queries butthey cannot save any

of these changes

Generate Core types automatically

The Core types folder displays a selection of the types in your schema (see ldquoThe Core

types folderrdquo ) The selection of types for this folder can be manual or automatic To

choose automatic selection check the Generate core types automatically checkbox To


Determine if child associations are present





144

the tree node can be expanded This can be especially time consuming when using a

dynamic LazyView Chapter

For this reason you can opt for a Profile to assume that child associations are present and

always show a plus sign (unless the absence of children can be easily determined using

Metaschema)

Saving a profile

When you make any changes to a profile you can either save the changed profile or

modify the current profile to use the changed settings for your current Sentences session

only or discard all your changes

After you make any changes the OK button is available Click OK if you wish to save

your changes or use your changed setting for the current session only Sentences displays

three options in a confirmation dialog

bull Yes confirms and saves all your changes to the profile

bull No modifies the profile to use the changed settings for the current session only but does

not update the saved profile

bull Cancel returns you to the Edit profile dialog

To discard your changes click Cancel in the Edit Profile dialog

Deleting a profile

To delete a profile select the Delete Profile command from the File menu Sentences

displays the Delete Profile dialog

Highlight the profile you want to delete and click the Delete button Sentences displays a

confirmation dialog Click Yes to delete the profile

Deleting a profile does not affect the chapter files used in that profile in any way The

chapter files still exist on your hard disk and can still be used in other profiles

Working with chapters

Add chapter

Figure 5-3 The Add Chapter dialog

To add a new or existing chapter to the profile click the Add button to open the Add

Chapter dialog shown in Figure 5-3

To add an existing chapter to a profile highlight the chapter name in the Add Chapter

dialog You can use standard Windows selection techniques to select more than one

chapter from this list



145

Click OK to add the selected chapter or chapters to the list of available chapters for the

profile To return to the Edit Profile dialog without adding chapters click the Cancel

button

The first chapter added to a profile is set as the default changes chapter for schema data

and queries Apart from this the order in which chapters are listed in a profile has no

significance

To create a new chapter click the New button This opens the New Chapter dialog

shown in Figure 5-4

New chapter

Figure 5-4 The new chapter dialog

To create a new chapter type in the name in the New Chapter dialog and click OK This

adds the new chapter to the list shown in the Add Chapter dialog You must repeat this

action for each chapter you want to create To return to the Add Chapter dialog without

adding a new chapter click the Cancel button

You can select the physical location for your new chapter from the Location dropdown

list Locations for chapter files are only listed here if you have defined them in the

ChapterPathList parameter of the Sentencesproperties file (see ldquoChapterPathListrdquo)

If the paths defined for your chapters are very long you may not be able to view the

complete path in this dialog In this case you can resize the dialog window by clicking on

its right edge and dragging to the right

To create a chapter for use by the LazyView tool to view data from a relational database

click the LazyView Chapter checkbox on the New Chapter dialog For more

information see the LazyView Guide

Naming chapter files

When you create a new chapter the name you assign to it in the New Chapter dialog is

generally used as the basis of the chapterrsquos file name on disk Chapter files on disk have

the extension chap Sentences chapter names are case sensitive

There are no restrictions on the characters that can be used in Chapter names However if

you use a character that has a special meaning in your computerrsquos file system Sentences

automatically maps that character to an alternative character when it creates the disk file

for that chapter

The Edit Profile dialog displays a chapterrsquos logical name which is stored in the system

chapter Profileschap All profiles use this chapter to look up chapter names so when a

chapter is renamed in one profile it is subsequently visible in other profiles using its new

logical name

Rename

To rename a chapter click Rename in the Edit Profile dialog and enter the new name

Like other elements in Sentences all chapter files have a unique hidden internal identifier

which never changes Sentences identifies chapter files using these internal identifiers so



146

chapter files can be renamed and still be visible to Sentences When you rename a chapter

in the Edit profile dialog you only change the visible (logical) name of the chapter Both

the internal identifier and the disk file name of the chapter remain unchanged

Properties

Click Properties in the Edit Profile dialog to display the properties for a chapter For all

chapters Sentences displays the following information

bull Name the chapter file name

bull Chapter UID the unique internal identifier for the chapter

bull Block Size the chapter block size

bull Read-only whether or not the physical file is editable

bull Chapter Type either a LazyView or a Standard chapter

bull Chapter size the physical size of the chapter file on the server

All these fields are read only

When LazyView is installed and licensed there is an additional tabbed page which is

used to set the connection properties for the chapter For more information about the

LazyView tool which is used for viewing data from relational database tables see the

LazyView Userrsquos Guide

Checking chapters used for changes

If you position your mouse pointer over the profile schema tab in the Explorer Sentences

displays the profile name and the names of the chapters used for schema data and query

changes This is an alternative way of checking which chapters are used for changes

Deleting a chapter

If you need to delete a chapter you must first make sure that it is not used in any profile

We recommend keeping a backup copy of any chapter before you delete it You can then

delete the chapter from your disk If you delete the chapter while

Sentences is still running the chapter name is still visible in the Add Chapters dialog

until you restart Sentences

Password-protected chapter files

You can define a password to protect a chapter file Once you have assigned a password

to a chapter file it can only be accessed when the password is entered

Sentences provides a command line procedure only for setting changing and deleting

passwords This mechanism is supported by a dedicated Sentences servlet When users

wish to access a profile that includes password-protected chapter files they must first

access a specific HTML page and enter the necessary passwords before accessing the

profile

System administrators should note that the password entry HTML page is not in itself

secure and therefore server-based security measures are recommended

When you use a command line procedure that references password protected chapter files

Sentences displays a prompt requesting the password for each protected file

The Sentences API includes an interface and methods for use with password protected

chapter files

To set a password

1 Make sure the Sentences server is shut down



147

2 Open a command prompt and navigate to the ltSentences_homegt directory and enter

the command

ChapterPassword ltchapternamegt

where ltchapternamegt is the name of an existing chapter in any one of the locations

listed in the Serverproperties file under the ChapterPathList property

3 Sentences prompts you to type in a password for the chapter and then prompts you to

type in the password a second time for confirmation

4 Sentences confirms that the password has been set with the following message

The password for chapter ltchapternamegt has been changed

To change a password



the command




3 Sentences prompts you to type in the existing password for the chapter

4 Sentences prompts you to type in a new password for the chapter and then prompts

you to type in the new password a second time for confirmation



To delete a password



the command





4 When Sentences prompts you to type in a new password for the chapter press Enter

without typing in anything Repeat this action when Sentences prompts you to type in the

new password a second time for confirmation

5 Sentences displays a message asking you to confirm that this action removes the

password from the specified chapter Type in y (for yes) to confirm or n for no to retain

the password

To enter a password

1 Start the Sentences server

2 Using a Web browser access the following URL

lthostnamegtltportnumbergtSentencesPasswordEntry

where lthostnamegt and ltportnumbergt are the hostname and port number respectively for

the Sentences server

Sentences user security


148

3 Sentences displays an HTML password entry page listing the files that have passwords

Type in the correct password for each file and click the Submit passwords button

The password entry page displays the names of all the chapters that have passwords You

only need to enter passwords for the chapters in a profile you wish to access

4 Sentences responds with either Password accepted or Incorrect password for each

chapter file password you enter

5 After entering the correct passwords start the Sentences Explorer and access the

profiles in the normal way

Password-protected files and the Personal Edition

The Personal Edition cannot access any Sentences chapter file that currently has a

password assigned to it


Sentences requires you to log in with your username and password The functions you are

allowed to perform and the information you are allowed to view and update will depend

upon the privileges that you have been granted

A Sentences User Administrator will be able to change the privileges you have been

granted

Logging into Sentences

When you open a Sentences application you will be asked to enter your username and

password

The System Administrator will have set up a maximum number of times that you can

attempt to log in before you are locked out If you are locked out you will need to contact

a User Administrator to reset your password

The first time you log in (or the first time after your password has been reset) you may be

required to change your password

Changing your password

To change your password follow these steps

1 In the Sentences Explorer select Change Passwordhellip from the File menu

2 The Change Password dialog will appear You must enter your existing

password and then the new password twice to confirm

3 Select Change



149

Changing to a different user

To change to a different user follow these steps

1 In the Sentences Explorer select Logout from the File menu

2 Enter the username and password of the user you wish to log in as

3 Select Login

User Preferences

Previous versions of Sentences allowed you to change certain preferences by editing the

parameters of in a client HTML file or the Applicationproperties file for the Personal

Edition Sentences Version 40 introduces preferences specific to each user

To change your preferences follow these steps

1 In the Sentences Explorer select Preferenceshellip from the View menu

2 Amend the available preferences and select OK or Cancel when you are finished

to change or cancel your preferences

Available User Preferences

Not all preferences will be available to all users depending upon the Edition of Sentences

and whether Functionality such as LazyView are enabled

bull Veto Welcome (General)

You may use this preference to specify whether to show the welcome screen upon start-

up This preference is only applicable and available in the Personal Edition

bull Table view of data (General)



150

You may use this preference to specify whether to allow users to display results in the

data pane as a table rather than the default tree This feature is at the Beta stage for

example query results cannot be displayed as a table yet

bull Data request size (General)

You may use this preference to specify the number of results to initially show Rather

than load the entire results Sentences will show by default the first 50 results followed by

a ldquomorerdquo node

bull Executing Query Status refresh (General)

You may use this preference to specify the frequency with which the Query Editor

updates the progress of an executing query The default is every three seconds

bull Table view of data (Data Pane)

You may use this preference to specify whether or not to allow the user to change the

Data Pane between displaying a Tree of data to displaying a Table of data

bull Show pages in the data pane (Data Pane)

You may use this preference to specify whether or not to show Page Nodes in the data

pane

bull Show inactive instances in the data (Data Pane)

You may use this preference to specify whether or not to show Inactive instance in the

data pane

bull Show the properties tab in the Data Pane (Data Pane)

You may use this preference to specify whether or not to show the properties of the

selected schema in the data pane as a tab next to the data tab

bull Show the Data Tab first - and by default (Data Pane)

When the properties tab is visible (see above) you may use this preference to specify

whether or to show the properties tab or the data tab first ie to the left The left tab will

also be selected by defaultbull Automatic Foreign Key Matching (LazyView)

You may use this preference to specify whether or not to attempt to automatically match

foreign key columns to those available when creating user-defined Foreign keys in the

LazyView Mapping wizard This preference is only available if the LazyView

functionality is enabled

bull Check Relational Schema (LazyView)

You may use this preference to specify whether or not the system will check to see if the

Relational Schema has changed This will be done before viewing the current LazyView

Mapping Definition re-mapping or re-importing static data This preference is only

available if the LazyView functionality is enabled

bull Show Subsets (Schema Pane)

You may use this preference to specify whether to include Subset Metaschema

information in the Schema Pane of the Sentences Explorer

bull Show Supertypes (Schema Pane)

You may use this preference to specify whether to include Supertypes Metaschema


bull Show Equivalent Types (Schema Pane)

You may use this preference to specify whether to include Equivalent Types Metaschema


bull Show Custom Dataforms (Schema Pane)

Deploying profiles and chapters


151

You may use this preference to specify whether to include Custom Dataforms information

in the Schema Pane of the Sentences Explorer

bull Show Domains (Schema Pane)

You may use this preference to specify whether to include Business Rule Domain


bull Hide unused System Domains (Schema Pane)

You may use this preference to specify whether to hide those System Domains that do not

have Effectors in the Schema Pane of the Sentences Explorer

bull Show Business Rules (Schema Pane)

You may use this preference to specify whether to include Business Rules Metaschema


bull Include a Business Rules Schema Folder (Schema Pane)

You may use this preference to specify whether to include a Business Rules Schema

Folder in the Schema Pane of the Sentences Explorer

bull Include a State Domains Schema Folder (Schema Pane)

You may use this preference to specify whether to include a State Domains Schema


bull Include a System Schema Folder (Schema Pane)

You may use this preference to specify whether to include a Specialist Schema Folder in

the Schema Pane of the Sentences Explorer and the Query Editor This folder includes

schema for the End User Application definition Server Text Documents and Tag Clouds

bull Include a Transactions Schema Folder (Schema Pane)

You may use this preference to specify whether to include a Transactions Schema Folder

in the Schema Pane of the Sentences Explorer This preference is only available if the

Transaction Visibility functionality is enabled See the Transaction Visibility section for

details


You can deploy a Sentences database by moving all the chapters and profiles that make

up your database from your development environment to your deployment environment

For example you may choose to develop a Sentences database by running the Enterprise

Edition in local mode (with the server and client running on a single machine) and then

deploy your database on a live intranet or Web server

Important You must have a separate license for each server running Sentences

The two possible methods for deploying your database are exporting the database or

copying chapters

Exporting the database requires using a profile which includes all your chapters and then

reconstructing the profiles on the target system after import This method is explained

fully in the section ldquoExporting and importing databasesrdquo

Alternatively you can copy all your chapter files (chap files) from the

SentencesChapters directory on your development server to the SentencesChapters

directory on your deployment server You can then reconstruct all the profiles for your

database using the Edit Profile dialog There are some limitations and restrictions on

using this method This method is explained fully in the section ldquoCopying chapter filesrdquo



152

Schema and data visibility

You can create multiple profiles in a single database A userrsquos view of the database is

defined by the sum of all data and schema updates in the chapters of their profile and

therefore different users can have different views of a single database You can use the

profile mechanism and the delete mechanism to customise different Sentences views for

different users (see ldquoCreating database views using profiles and chaptersrdquo )

Exporting and importing databases

You can export your Sentences database using the Export command which creates a

database export file You can import the set of chapters from a database export file using

the Import command By default the Import command does not automatically recreate

the profile definitions for a database

Export and import operations are command line procedures and are normally carried out

by the administrator of the Sentences database The administrator must have at least

readwrite access to the computer running the Sentences Web server in order to carry out

export and import operations

A database export file contains all the schema and data information contained in a single

export profile including the chapter configuration We recommend using the file

extension lze to identify database export files

Export and import require exclusive access to the Sentences server and therefore you

must close down the Sentences server before you perform an import or an export

operation If you try to export or import a profile while the server is in useSentences

displays an error message Database in use

Benefits of exporting a database

In Sentences all schema and data changes including delete actions are treated as

additions to the chapter files This can have certain advantages as discussed in the section

ldquoCreating database views using profiles and chaptersrdquo

However it is possible that after a time the quantity of changes applied to a database may

make the chapter files very large and may possibly result in poorer performance

The export procedure consolidates data and schema updates and therefore exporting a

database and then importing it may enhance the performance of large databases

Database export and internal identifiers

Sentences uses unique internal identifiers for every schema and data element in the

database These identifiers are used in any links between chapters When you export and

import a database Sentences consolidates the details of schema and data updates creating

a new version of your database By default this new version of your database maintains

the existing internal identifiers and preserves cross-chapter links

Note In earlier versions of Sentences up to Version 21 Sentences automatically renumbered

all the internal identifiers when performing an import operation which meant that cross-

chapter links were not maintained In later versions from Sentences Version 22 you can force

Sentences to renumber by specifying the -renumber switch

To export a database you must specify a profile that includes all the schema and data

chapters that are relevant for an application You may use an existing profile if a suitable

one exists or create a new profile for this purpose



153

Default export behaviour

When you use the Export command Sentences checks cross-chapter references to make

sure all required chapters are included in the export profile and displays an error message

if a required chapter is not found By default if Sentences finds that any required chapters

are missing the export operation fails

You can change the default behaviour and run the export command even if some chapters

referenced by other chapters are not included by using the -force switch with the Export

command The result of using the -force switch may be that some of the data from the

original database is missing from the database export file

To export a database

Note The following command line examples use Windows system conventions

You must have write access to all the chapter files used in the database you wish to

export


1 Choose a profile that includes all the schema and data files that are relevant to the

application database you wish to export The profile to be exported must meet these

conditions

bull the profile must contain all of the chapters holding your data or schema

bull the profile must not include the system chapters Profileschap or Metaschemachap

bull the profile should not include any other chapters supplied with Sentences such as the

Human resources chapters New chapterchap or any of the Application Suite

chapters except under special circumstances

You may use an existing profile if a suitable one exists or create a new profile for this

purpose You may find it helpful to keep a note of the names of the chapter files used in

the profile you export

2 Shut down the Sentences server

3 Open a command prompt and navigate to the ltSentences_homegt directory

Run the following command at the command prompt

cgt Export [-force] ltprofile namegt ltpathgtltexport file namegt

where ltprofile namegt is the name of a profile recognised in

the current loginchap file and ltpathgtltexport file namegt is

the full path and the name of the database export file you

want to create and [-force] is an option switch If the profile

name includes spaces some operating systems require the

name to be enclosed in quotation marks

Note If the profile you are referencing with this command includes passwordprotected

chapters Sentences prompts you for the password for each chapter concerned (see

ldquoPassword-protected chapter filesrdquo )

Export command option switch

The Export command may include the following option switch

option switch Meaning

-force The -force switch exports a profile even if Sentences finds that some

chapters referred to by other chapters in the profile are missing



154

To import a set of chapters

Carry out the following steps to import a set of chapters


2 Make sure that no copies of any of the chapters being imported exist in any of the

chapter locations specified in the Serverproperties file If Sentences finds a chapter

with either the same name or the same internal identifier as a chapter being imported the

Import command fails

3 Open a command prompt and navigate to the Sentences server directory At the

command line prompt run the following command

cgt Import [-renumber] [-overwrite] ltpathgtltexport file namegt sect

[-location chapterNo=location ]

where ltpathgtltexport file namegt is the full path and file name for the database export

file you want to import and [-renumber] [-location] and [-overwrite] are option

switches as explained in the section ldquoImport command option switchesrdquo

During the import and export procedures Sentences displays a row of asterisks on the

command line screen Each asterisk represents 1000 lines of data that have been

processed

If the Import command fails for any reason any incomplete information is deleted If an

export or import program is interrupted by a user action the Sentences database may be

locked If you find you cannot run Sentences after a failed export or import operation

check the SentencesChapters directory to see if a file named databaselock is present

in any of your chapter file locations If you find this file delete it and then restart the

Sentences server (see ldquoShutting down and restarting the Sentences serverrdquo )

4 When the import operation ends restart the Sentences server and open a Sentences

client

Note If the profile you are referencing with this command includes password protected





155

Import command option switches

You may specify any of the following options by adding the appropriate switch to the

Import command If you do not specify any switch the default behaviour is as described

for the -preserve option

Option switch Meaning

-preserve Use the -preserve switch to import the set of chapters without

changing the existing internal identifiers for chapters and objects

and to maintain links between chapters

You may not use this switch with -overwrite or with

-renumber

-renumber Use the -renumber switch to import the set of chapters and change

all the internal identifiers for chapters and objects This means that

links to chapters outside the imported set of chapters are not

maintained

Import with the -renumber switch adds the definition of the exported

profile to the Profiles database so that it is automatically listed in the

Open Profiles dialog You may use this switch with -overwrite but

not with -preserve

-overwrite The -overwrite switch instructs the import program to overwrite any

existing profile with the same name as theprofile being imported

If you do not specify the -overwrite switch and a profile with the

same names as the imported profile already exists Sentences adds

a numeral to the end of the name of the imported profile

The -overwrite switch does not have any effect on existing

chapters and Sentences always adds a numeral to the names of any

imported chapters that have the same names as existing

chaptersYou may use this switch with -renumber but not with -

preserve

-location The -location switch allows you to specify the chapter directory for

the chapter files in the profile being imported You may specify

different locations for each chapter in the profile by giving a different

location for each chapter number All the locations must already be

designated in the ChapterPathList property of the

ServerProperties file You can check the chapter number of the

chapters in the profile being imported by opening the lze file in a

text editor

On Windows systems you should enclose the location specification in

quotation marks for example

ldquo1=Fchaptersrdquo

You may use this switch with any other switch

Visibility of imported profiles

When you import a set of chapters using the default setting (the -preserve option) the

exported profile may not be visible in the Open Profile dialog when you restart

Sentences This is because Sentences does not add the profile to the profiles database in

Profileschap when you use the -preserve option

If the imported profile is a new version of an existing profile the previous profile

definition is still available in the Open Profile dialog and can still be used This occurs

when you have exported a database to re-import it to the same system or to move an

application from a development system to a deployment system where it had previously

been deployed



156

If the imported profile is not a new version of an existing profile you must create the

profile definition You may do this using the Edit Profile dialog and selecting the

chapters belonging to the imported profile

If the imported profile is complex for example if you created a single profile to export all

the profiles and chapters of a large Sentences application it may be easier to use an XML

Import procedure to create the profile or profiles you need This procedure is described in

the section ldquoTransferring the profiles databaserdquo 7

Visibility of imported profiles using the -renumber option

If you import a set of chapters using the -renumber option switch Sentences adds the

exported profile to the profiles database in Profileschap and the profile is visible in the

Open Profile dialog when you restart Sentences

If a profile being imported with the -renumber switch or a chapter in the profile has the

same name as an existing profile or chapter Sentences appends a numeral to the name of

the imported profile or chapter for example My Data Chapter 1

Sentences recognises that the old and new profiles and chapters are different as they have

different internal identifiers due to the use of the -renumber switch

Limitation on parameters with Import command on Windows

If you are running the Sentences server on Windows and the command you use to import

a profile needs to include a more than eight parameters for example if you wish to

specify a large number of chapter locations you cannot use the supplied Importbat file

This is because of a limitation on the number of parameters that can be included in

Windows batch files

In this case you must enter the Java command with all the necessary parameters at a

command line There is no restriction in the number of parameters when using Linux

Unix

Importing a database export file from a previous version

Database export files from Sentences Version 22 and Sentences Version 30 may be

imported into Sentences Version 40 However you must ensure that you are using the

current releases of these versions before creating your export files (build 2232 or later or

build 3043 or later respectively) Please refer to the Sentences Installation Guide for

further details

If you need to import a database from any other version of Sentences please contact

supportsentencescom

Transferring the profiles database

When you deploy a Sentences application for the first time on a system other than the one

it was developed on you may wish to transfer the profiles database particularly if you

need to replicate the profile and chapter structure of a complex Sentences application The

procedures in this section explain how to do this

You do not need to use these procedures to update an application that already exists on

the deployment system

These procedures involve using Sentencesrsquo built-in XML Export and XML Import

commands to export the Sentences profiles database from one system and import it on

another system

To export the profiles database follow these steps

1 On the source (development) system make sure that the system profile Profiles is

visible in the Open Profile dialog If this profile is not available you must set the

optional parameter ProfilesProfileVisible in the jnlp or javascript definition to yes



157

(see ldquoAdditional optional parametersrdquo ) Note that if you make any changes to the jnlp or

javascript definition you may have to restart the Sentences server before the changes

become effective

2 Create a database export file as described in ldquoTo export a databaserdquo

3 In the Sentences Explorer select the Profiles profile

4 Open the All queries folder and highlight the query Export profiles

5 Select Results then Export XML Results from the Query menu

6 Select External for the DTD Reference option

7 Save the output to a file named for example profilesxml

As an alternative to these last three steps you can create an XML export file using the

following command line after stopping the Sentences server

ExportXML -doctype external -file ltfilenamegt Profiles ldquoExport profilesrdquo

You now have two files on the source (development) system the database exportfile and

the XML file of profile definitions

To import the profiles database follow these steps

1 Copy the two files (the database export file and the XML file of profile definitions)

from the source (development) system to the target (deployment) system or make them

available across a network

2 Make sure that none of the chapters in database export file exist on the target

(deployment) system in any directory that is on the chapter path list

3 Stop the Sentences server on the target system and import the database export file using

the default setting for the Import command as described in ldquoTo import a set of chaptersrdquo

You may optionally use the ndashlocation switch to place these chapters in different

directories

4 Start the Sentences server and use the Edit Profile dialog to create a new profile

named for example Profiles This must be the same name as the profile you used to

create the database export file This profile must contain only the system chapter

Profileschap

5 Use the Edit Profile dialog to create a second new profile This may have any name

you wish This profile must include all the chapters imported from the database export

file

This makes sure that details of all the chapters are recorded properly in the profiles

database After you have created and saved this new profile once it can be deleted

6 Stop the Sentences server

7 Copy the exported Profilesxml file from the source system to the target system


9 Run the following command

ImportXML -file Profilesxml

10Re-start the Sentences server

The set of profiles exported from the source system is now visible in the Open Profile

dialog

Export command troubleshooting

The Export command checks that all referenced chapters are included in an exported

database unless you use the -force switch with the command Sentences always checks

the internal identifiers of the chapters in a profile rather than the chapter names and an



158

export command may fail even though a chapter with the correct name is in the profile

Sentences display an error message similar to the following

1734 Chapter ldquoltchapter_name_Agtrdquocontains a reference to chapter

ldquoltchapter_name_Bgtrdquo which is not in profile ldquoltprofile_namegtrdquo

If this error occurs it is likely that the original chapter referenced in the profile has been

replaced by a different chapter with the same name You can check the list of other

chapters referenced by a chapter and their internal identifiers by using the

InspectChapter command with the header option (see ldquoChapter file analysisrdquo)

Copying chapter files

You can copy chapter files (chap files) from the ltSentences_chaptersgt directory on

your development server to the ltSentences_chaptersgt directory on your deployment

server provided that both installations are using the same version of Sentences You can

then reconstruct all the profiles for your database using the Edit Profile dialog You do

not need to reconstruct the profiles if you copy the Profileschap file as well as your

application chapter files but the effect of copying the Profileschap file is to delete any

existing profile definitions on the deployment server

You must shut down the Sentences server on both the source and target Sentences

installations before copying any chapter files After you restart the Sentences server on

the target installation all the copied chapters are visible in the Add Chapters list of the

Edit Profile dialog

If you copy the Profileschap file the copied profiles are also visible in the Open

Profile dialog If you do not copy the Profileschap file you can reconstruct your

profiles using the Edit Profile dialog

Restrictions on copying chapter files

If the Sentences server detects two or more chapter files that are duplicates Sentences

does not start and instead displays an error message (see ldquoErrors reported at the Sentences

clientrdquo )

The Sentences server does not identify chapter files as duplicates by their file system

names but by their internal identifiers When you copy a Sentences chapter file the copy

has the same internal identifier as the original This means that you must take great care

when copying chapter files never to allow two copies of the same file to be accessed by

the same server at the same time

Chapter format

From time to time as improvements are made to Sentences there are changes to the

internal format of the chapter files used by Sentences You can check the chapter format

used by your version of Sentences by selecting the About command in the Help menu

Click the Support Information button for a display of additional information including

details of the current chapter format

You can copy chapter files from one version of Sentences to another as long as the

chapter format is the same in both versions If the chapter format has changed you cannot

use copied chapter files You must export a profile from the earlier version of Sentences

and import the profile into the later version For more information see ldquoExporting and

importing databasesrdquo

Changing chapter file block size (single chapter export and

import)

If you wish to change the block size of a specific chapter file you can use the

ExportChapter and ImportChapter commands Both of these commands are run from a

command line For further information about block size see ldquoBlockSizerdquo

Using the Sentences Explorer


159

Both of these commands are run on a single file The commands do not use the

ChapterPathList setting from the Serverproperties file or check for the existence of

the databaselock file You must therefore use the fully-qualified path and file name

for example

DSentencesData40ChaptersMyChapterchap

It is strongly recommended that you shut down the Sentences server before running these

commands

ExportChapter command

To export a single chapter file open a command prompt navigate to your

ltSentences_homegt directory and enter the following command

ExportChapter ltchapter filegt ltexport filegt

where

ltchapter filegt is the file name of a Sentences chapter file to be exported and ltexport

filegt is the file name of the export file to be created

After you export a single chapter file in order to change the filersquos block size you must

remove the original file from any directory that is listed in the chapter file list

ImportChapter command

To import a single chapter file open a command prompt navigate to your


ImportChapter [-blocksize ltblock sizegt] ltexport filegt ltchapter filegt

where

ltblock sizegt is an optional number representing the block size in KB to be used when

creating the new chapter file

ltexport filegt is the file name of an export file created by the ExportChapter

command and ltchapter filegt is the file name of a Sentences chapter file to be created

The ImportChapter command creates a Sentences chapter file that has the same internal

identifieras the original chapter file so that references to it from other files can be

retained If you wish to use the same file name as that of the chapter file that you

originally exported you must make sure that the original chapter file is removed from the

directories in the chapter path list before running the ImportChapter command


You can use the Sentences Explorer to create your schema and to browse schema and

data You can launch the Dataform to type in data and the Query Editor to create and run

a query

Delayed display of inverse associations

In order to speed up the display of data in the Sentences Explorer Sentences postpones

the download and display of inverse association data When you expand an entity instance

node that is the target of one or more association types Sentences displays a folder for

each association type Sentences does not retrieve the instances contained in these folders

until you expand the folder itself

Display order of instances

When you select an entity type or association type in the schema pane the corresponding

entity or associations are displayed in the data pane For all entity types that are not

subsets the display order of instances in the data pane is determined by the sort algorithm

of their typersquos datatype If not all the visible instance data has the same datatype

instances of the same datatype are grouped together and then ordered by the sort

algorithm of their typersquos datatype



160

For all association types that are not subsets the display order of instances in the data

pane is determined first by the sort order of their sources and then by the sort order or if

it exists by the defined sequence of their targets Inverse associations are sorted by target

first

For all entity and association types that are subsets the display order of instances in the

data pane is determined by settings of any sort nodes in the subset query If no sort nodes

exist in the subset query the display order is determined by the sort algorithm of the typersquos

datatype

All of the display rules given above apply to the top level display in the data pane When

you expand a node in the data pane the data displayed is ordered automatically by

Sentences and this ordering cannot be changed

Refreshing the display

To refresh the display of the Sentences schema click the Refresh button on the Sentences

Explorer toolbar or select the Refresh command from the File menu

Refreshing the display also resets the clientrsquos definition of the current profile To refresh

the display of data in the Sentences Explorer data pane click the Reload Data button on

the toolbar or select Reload data from the File menu

Determining if child associations are present







Metaschema)

To change whether a Profile attempts to determine if child associations are present follow

these steps

1 In the Sentences Explorer select Edit Profile hellip from the File menu

2 To choose automatic detection check the Determine if child associations are

present checkbox Otherwise unselect this checkbox

To change whether a particular type attempts to determine if child associations are present

follow these steps

1 In the Sentences Explorer select the type for which you wish to change the

option

2 Select Propertieshellip from the Edit menu

3 Select the Retrieval Methods tab



Hiding the data pane

Sentences Version 40 introduces the ability to temporarily switch of the display of data

When you select a type in the left-hand Schema pane the right-hand Data pane displays

instances of that type If you are working on the schema design and not concerned with

the data at that moment it is useful to be able to hide the data pane

To toggle whether the data pane is visible or not select Data Pane from the View menu

Alternatively you may use the shortcut key combination of Alt+D



161

Sandbox Modes

Sentences 40 has added the ability to put the Sentences Client into a Data or a Full

Sandbox Mode Sandbox Modes are intended to be used to experiment with changes to

the database in a temporary environment where you can at any time revert back to the

state of the database before you switched to Sandbox Mode

You could add a new chapter to your profile and direct all changes to that chapter to

experiment and once finished you could remove the chapter again Sandbox Modes work

in the same way but the creation and removal of a temporary chapter is handled for you

You can quickly switch Sandbox mode on or off to compare the schema and data changes

you have made

Whilst in a Sandbox Mode any Simple Email Action Requests will not send emails

Instead a dialog will show the number of emails that would have been sent

bull Data Sandbox Mode

The main reason for using a sandbox will be when experimenting and refining an Update

Query or an Effector Query In this situation you may wish to repeatedly execute your

query and inspect the results after making small changes to the query In this case you can

use Data Sandbox Mode so that the changes you make to the query are permanent but the

changes to data can be discarded after you have finished refining the query

bull Full Sandbox Mode

A Full Sandbox Mode is also provided so that any changes to data or schema can be made

for experimentation and then all discarded afterwards

Access to Sandbox Mode

A User must be granted a specific privilege to be able to use Sandbox Mode There is a

Sandbox User Role or the privilege can be granted directly to a particular User See the

sections on User Privileges and Roles for details

Changing Sandbox Mode

Sandbox Mode must be enabled for each User as described above When enabled the

status bar of the Sentences Explorer and Request Query Editor will display the current

Sandbox Mode In addition the Options Dialog will include Sandbox Mode options

To change the sandbox mode in the Options Dialog follow these steps

1 In the Sentences Explorer select the Optionshellip menu item from the top View

Menu

2 The Options Dialog will open and if Sandbox Modes are enabled for the user the

dialog will include the three sandbox modes (Off Data and Full) The current

Mode will be selected

3 Select the mode you would like to change to and select OK

To change the sandbox mode from the Status Bar follow these steps

1 In the Sentences Explorer or Query Editor open the context menu for the

Sandbox Indicator The current mode will be disabled

2 Select the mode you wish to change to



162

Note that if there are open Query Editors that have unsaved changes you will be

prompted to confirm changing Sandbox Mode This is because the Schema will have to

be reloaded and any unsaved query changes will be discarded

Transaction Visibility

Sentences 40 now includes the ability to set a Visibility Timestamp to a point in the past

that is used to show the Profile at that time This function has no impact on performance

The current Transaction Visibility is displayed in the Status Bar of the Sentences Explorer

and Query Editors

Sentences 40 also includes the ability to browse the existing Transactions to identify a

point in time that you may wish to view See the Browsing Transactions section for

details

Access to Transaction Visibility

A User must be granted a specific privilege to be able to use Transaction Visibility There

is a Transaction Visibility User Role or the privilege can be granted directly to a

particular User See the sections on User Privileges and Roles for details

Changing Transaction Visibility

Transaction Visibility must be enabled for each User as described above When enabled

the status bar of the Sentences Explorer and Request Query Editor will display the current

Transaction Visibility In addition the Options Dialog will include Transaction Visibility

options

To change the Transaction Visibility in the Options Dialog follow these steps


Menu

2 The Options Dialog will open and if Transaction Visibility is enabled for the user

the dialog will include the current selection

3 Select either the current date and time or enter a new date and time and select

OK



163

The Options Dialog can also be opened from the Status bar context menu

Browsing transactions

The Sentences Explorer Schema Panel can contain a folder that allows you to browse all

the Transactions in your Schema You can also use the position and filter tools to narrow

your search

The information includes transactions that were aborted ndash these are transactions for which

a commit time is not set Most Transactions can have a description associated with them

but some perform many operations at once such as changing the properties of a Type and

can only describe themselves with the Type that was being modified ndash not all the changes

made

This is a useful tool if you are trying to find a significant event and set the Transaction

Visibility to view before and after it

Also available on the Options Dialog is a button that opens a dialog to show the

Transaction History This includes a summary of the first and last transaction timestamps

together with the number of transactions started and committed

Database components


164

The Transaction Schema Folder is displayed according to your User Preferences See the

section on User Preferences for details

Database components

The Sentences database includes both schema and data information The Sentences

database schema is built up of entity types and association types referred to collectively

as types The data in a Sentences database is built up of entities and associations which

are referred to collectively as instances Types and instances are introduced and explained

in Chapter 2 ldquoIntroducing the associative modelrdquo

You can work with types and instances in the Sentences Explorer and the Dataform and

also in the Query Editor These three mechanisms for viewing and working with

information are introduced in Chapter 4 ldquoThe Sentences Quick Tourrdquo

The next part of this chapter describes in more detail how you can work with types and

instances in the Sentences Explorer and the Dataform Working with the Query Editor is

described in Chapter 7 ldquoSentences queriesrdquo

Entity types and entities

The least complex data items in a Sentences database are entities which areinstances of

entity types Entity types are created and managed in the Sentences Explorer and entity

instances are created in the Dataform Entity types and association types are displayed in

the schema pane and entities and associations are displayed in the data pane For more

information see ldquoEntities and associationsrdquo

Creating entity types

To create an entity type you can either

bull click the Create Entity Type button on the toolbar or

bull right-click the All types folder and select the Create Entity Type command from the

shortcut menu or

bull select the Create Entity Type command on the Schema menu

You can also create entity types from the Create Association type dialog

Database components


165

Figure 5-5 The Create Entity type dialog

Each of these actions opens the Create Entity Type dialog Type in a name for the entity

type and click create The new entity type is added to the All types folderYou can create

another entity type or click Close to dismiss the dialog box

Entity types always appear under the All types folder in the schema pane Entity types

may also appear in the Core types folder (see ldquoThe Core types folderrdquo )

Entity type names can contain any standard alphanumeric characters including blanks

They should not contain any special characters as this may cause errors when evaluating

expressions in queries Make sure that the first character after a blank space is alphabetic

not numeric Entity type names are not case-sensitive

Sentences uses unique hidden identifiers for entity types (and for many other elements)

This means that you can rename an entity type or create an entity type with a duplicate

name without compromising the data in your database Sentences always prompts you to

confirm that you want to create a duplicate entity type when an entity type with the name

you are using already exists

You can optionally specify the Datatype to use at this time or later If you select a

Datatype other than the default of ltNonegt then the dialog will show you any datatype-

specific options to choose

If you enter an Entity Type name that contains one of the standard Datatypes (for example

ldquoDate Createdrdquo or ldquoPercentagerdquo) then the datatype will be automatically selected for you

Creating entities

Entity instances can only be created through the Dataform (see ldquoCreating an entity

instance in the Dataformrdquo )

Size of entity and value instances

Sentences has no specific limit on the size of items that can be stored as entity or value

instances although some datatypes do impose limitations (see for example the

ldquoNumberrdquodatatype )

You should be aware of the memory usage capabilities of your own system when

deciding to store large data items in a Sentences database It may be more practical to

store items such as large images outside the database and to create references to them

using the Hyperlink datatype (see ldquoString datatypesrdquo)

Database components


166

Value types and datatypes

Value types in Sentences represent things in the real world that you do not need to record

additional information about This includes for example dates times and numbers Value

types are created by assigning datatypes (see ldquoDatatype properties pagerdquo )

The distinction between value and non-value entity types is very important and is

discussed in the section ldquoEntities and valuesrdquo You should understand this distinction

fully before you make extensive use of datatypes in your database

In certain cases you may wish to record additional information about entities that are

defined as dates times or numbers Some data may be recorded in a numerical form

because you wish it to have a numerical presentation or to be sorted in numerical order

even though you do not need to perform any calculations on the data This happens when

you use a numerical format as the label of an entity for example as an order number or an

employee number

Value types and values are distinguished in the Sentences Explorer by disc-shaped icons

Because value types cannot be the source of an association you must not define any entity

type that you want to use as the source of an association as a value type In most cases the

majority of entity types can and should use the undefined datatype ltNonegt

The ImageData datatype

A new datatype has been added to Sentences Version 40 The existing Image datatype

allows you to specify images stored on the Sentences Server by name eg LazyImagesCarolHoffmanjpg

The new Datatype ImageData stores image data as bytes You can view images in the

dataform You can paste an image into an ImageData Dataform field from the system

clipboard and import them from relational databases using a LazyView Chapter

Default formats and presentations

When creating Entity Types and Association Types Sentences Version 40 introduces

several new default presentations for specific datatypes

Datatypes can now specify a default field width and a default format pattern The built-in

datatypes have the following defaults

Datatype Default Field Width

Date

Time

12

String

Number

Currency

Mixed Currency

Percentage

13

Hyperlink

Email

Image

ImageData

No default variable length

Timestamp 18

ltNonegt 30

Currency C000C-000

When an Association Type is created if its source is an Association Type then Sentences

sets the source presentation automatically to Table for Associations if it is multiple and

Nested panel if singular If a specific dataform width was set then this value is used for

the table column width and the original width is set to variable so that it takes up all the

available space or the sum of the column widths if this is less

Database components


167

Deleting types and instances

Sentences Version 40 introduces two differences in the way one or more type or instance

is deleted For dynamic LazyView chapters deletion of read-only data is not relevant and

so Sentences does not attempt to determine the impact of deleting types or instances

Otherwise the process of determining the impact is broken down into smaller

components and can be cancelled or confirmed before the results are known if it is taking

a long time to determine

This is similar to how the request to execute a query can be cancelled before the results

have been determined

Subsets of subsets

Sentences Version 40 introduces the ability to have a subset of a subset which was

previously not allowed

This is required to represent some Relational Database Schema and allow subsets to have

their own State Domains

Defining value types with datatypes

Some display formatting characteristics in Sentences are associated with datatypes that

may be assigned to a type When new entity types are created they do not have a datatype

assigned to them and their datatype property is set as ltNonegt

Datatypes are assigned using the Datatypes tab on the Properties dialog (see ldquoDatatype

properties pagerdquo ) For example in order to display a number with decimal places you

must assign the Number datatype Assigning a datatype may also determine certain

behaviour characteristics for example whether or not you can perform arithmetic

calculations with the instances of a type

When you assign one of the Sentences-supplied datatypes to an entity type you can decide

whether the type should be a value type or not using the Instances are values property

If you choose to make the type a value type instances of the type have both the

formatting and the behaviour characteristics associated with value types which are

described in more detail in the following section If you choose not to make the type a

value type instances of the type have only the formatting characteristics of the datatype

and not its behaviour characteristics

When you assign a datatype to a type you should check or clear the Instances are values

checkbox according to whether or not you wish to make the type a value type (see

ldquoInstances are valuesrdquo )

If you create an entity type with the same name as one of Sentencesrsquo own datatypes for

example Date or Time Sentences automatically assigns that datatype to the type and

converts it to a value type (see ldquoDatatype properties pagerdquo )

This does not apply to the Currency datatype You can clear the Instances are values

checkbox if you do not wish the type to be a value type

Note It is possible to create a custom datatype that is not a value datatype (see ldquoCustom

datatypes APIrdquo )

Impact of changing a datatype

Changing the datatype of an entity type or changing the setting for the Instances are

values property (see ldquoInstances are valuesrdquo ) has a serious impact on the visibility of your

data Any change you make to the datatype or to the value status of instances of any

entity type is not applied to existing instances which may no longer be visible after you

make a change

Database components


168

bull If you change from any datatype to ltNonegt existing instances remain visible

bull If you change between Number and Percentage existing instances remain

visible

bull If you make any other change between datatypes existing instances are no longer visible

bull If you change the state of the Instances are values checkbox existing instances are no

longer visible

bull Instances with different datatypes are not sorted together hence a list of such instances

may not be sorted as expected

bull Calculations in queries for example for custom dataforms may rely on the type and

instance datatypes matching and be broken by instances with different datatypes

If you do need to change a datatype where a considerable amount of data exists you may

wish to recreate the effected data and all data depending on it One method of doing this

would be to export the effected data to a CSV file and then delete the data from your

database and set the correct datatype before importing the CSV file

However this method is not always reliable and should be used with great caution

Visibility of value instances

When an entity type has ltNonegt as its datatype all the instances of that type are visible

in the data pane when the entity type is selected in the schema pane When you have

created a value type by assigning a datatype only instances with the same datatype are

visible This means that if you change the datatype of a type after you create entity

instances those instances may no longer be visible depending on the new datatype

A more strict visibility constratint can be placed upon Value Instance visibility where in

addition instances of value types are only displayed in the data pane when they are used

as targets of associations in the database As this is an expensive constraint to make it is

turned off by default To turn this additional visibility constraint on change the ldquoCheck

Value Visibilityrdquo flag in the Troubleshooting tab of Server properties (see ldquoServer

propertiesrdquo for details)

Behaviour of value types and values

In general value types and value instances behave in the same way as entity types and

entity instances with the following important exceptions

bull Two instances of a value type with the same name cannot exist they are the same

instance For non-value types it is possible to have duplicate instances that istwo distinct

instances with the same name

bull Value types and value instances can only be used as the targets of association types and

associations and they can never be the source of association types or associations

bull Value instances are only visible when they are used as the targets of associations

bull Non-value instances are associated with a particular Sentences chapter but value

instances are not A value instance exists wherever there are associations that use it as

their target

bull Although the Rename command is not available on the shortcut menu for value

instances you can replace one value with another in the Dataform

bull Value types and instances are displayed in the Sentences Explorer with a discshaped

icon

Database components


169

Creating value instances

You can only create a value instance as the target of an association in a dataform You

cannot open a dataform on a value type to create value instances

Association types and associations

Association types are more complex than entity types as they require three components

source verb and target The sources and targets of association types are typically entity

or association types but the source of an association can be an entity or association

instance For more information see ldquoEntities and associationsrdquo

Creating association types

To create an association type you can either

bull click the Create Association Type button on the toolbar or

bull right-click the All types folder and select the Create Association Type command from

the shortcut menu or

bull right-click an existing entity or association type and select the Create Association Type

command from the shortcut menu or

bull right-click an existing entity or association instance and select the Create Association

Type command from the shortcut menu or

bull select the Create Association Type command on the Schema menu Each of these

actions opens the Create Association Type dialog

Figure 5-6 Create Association Type dialog

When you create an association type you must define its source verb and target and its

cardinality properties (see ldquoCardinalityrdquo ) After you have created the association type you

can alter some of these properties and define some additional properties in the Properties

dialog (see ldquoPropertiesrdquo )

Schema and data change visibility

Some changes to schema and data such as the addition of instances to a new association

type may not be automatically reflected in the data pane of the Explorer if entities of the

Database components


170

source type are being displayed As soon as you reselect the entity type or refresh the

display all changes are displayed correctly in the data pane

Source verb and target

You must define a source a verb and a target for any association type you want to create

The source of the association type must be an entity or association type or an entity or

association instance The target of the association type must be an entity or association

type The verb defines the nature of the association between the source and the target

Source

If you select an existing type or instance before you open the Create Association Type

dialog Sentences displays the selected type or instance as the source for the new

association type You can use the displayed source or select another source from the

Valid source types folder or type in the name of a new entity type

If you type in a new entity type name Sentences prompts you to confirm that you want to

create a new entity type You cannot type in a new association type as the source

The Valid source types folder displays all the types that may be used as the source of an

association type This means that value types are not displayed in this folder

Selecting an entity instance or an association instance as the source of an association type

creates an instance-specific association type which is discussed in the section ldquoInstance-

specific association typesrdquo

Verb

The verb defines the association type and describes the nature of the association between

the source and the target A precisely named verb can be very useful in schema design

You may use the same word to name the verb and the target of an association type It is

helpful to use an upper case (capitalised) name for the target and a lower case name for

the verb for example Actor award Award When you create association instances the

name of the association type verb is preserved for example David Garrick award Best

Actor

Verb names should be singular Multiple Association Types allow you to also enter a

plural form The singular form is used when referring to one instance The verb name (or

plural form) is capitalised when it is used as a field label in the Dataform

Target

You can select a target for the association type from the All types folder or you can type

in the name of a new entity type Alternatively you may select an existing metatype from

the Metatypes folder which is a subfolder of the All types folder You cannot type in the

name of a new metatype (see ldquoMetatypesrdquo )

You must always select not type in the name of an existing type If you type in a new

entity type name Sentences prompts you to confirm that you want to create a new entity

type You cannot type in a new association type as the target

Inverse verb

You need to specify an inverse verb for the association type The inverse verb expresses

the same link as the verb but as seen from the target to the source For example if the

verb of an association type is has colour then the inverse verb might be colour of

Sentences suggests a default inverse verb based on the verb you entered usually by

adding the word ldquoofrdquo You can always type in an inverse verb of your own choice instead

of the one suggested by Sentences

Database components


171

Page

Association Types can be placed on Pages These are purely used to arrange the fields in a

Dataform (see ldquoSchema Pagesrdquo)

Cardinality

The cardinality of an association type determines whether you can have zero one or

more than one associations of a given association type for one source instance You

define association type cardinality by checking the OptionalMandatory and

MultipleSingular radio buttons

The following table shows the possible combinations of these settings

Optional Manditory Multiple Singular Number of Associations

Manditory Singular One only ndash Zero not allowed

Optional Singular Zero or One

Manditory Multiple One only ndash Zero not allowed

Optional Multiple Zero or more

Cardinality rules and data display

Sentences monitors the data you type in to ensure that you conform to the cardinality

rules that you have defined for your association types If you use the Dataform to type in

data and do not complete the field for a mandatory association Sentences displays an error

message Similarly if you try and create more than one value for a singular association

Sentences displays an error message

In some situations Sentences is unable to enforce cardinality rules In these cases the data

displayed in the Sentences Explorer does not match the data displayed in the Dataform

For example if you define an association type as Multiple and create multiple

associations for a particular source and then change the definition of the association type

to Singular the database has more targets for the association than its current definition

allows

When you view this association in the Sentences Explorer all the targets in the database

are displayed because the Sentences Explorer uses an open tree structure to display data

(In this situation the Explorer does not use the associations folder normally used to group

multiple associations)

If you try and view this association using the Dataform Sentences displays an error

message

Error 1710 Singular AT (association type name) has multiple instances

This is because the Dataform has a rigid structure determined by the schema and the

schema rules If the schema rules allow only one value then only one value can be

displayed in the Dataform

Singular inverse

When you define a new association type you can also determine whether to limit the

association from the target to the source using the inverse verb (the inverse association) in

some way Use the Singular Inverse check box to ensure that the inverse association

must be singular That means that any entity or association instance may be the target for

only one association of this type The Singular Inverse property is not available for

Symmetric association types

Database components


172

Symmetric

An association type is symmetric if the relationship between source and target is always

the same in both directions The source and target must be of the same type and the target

may not be a value type For example the association type Person is married to

Person is symmetric However the association type Person is employed by Person

is not symmetric

The Symmetric check box is only available if the source and target of an association are

of the same type equivalent types related subsets or subtypes When the Symmetric

property is selected the inverse verb is not used and the inverse verb field is not editable

Display ordering

If you select the multiple option when you choose the cardinality of the association type

you can choose to display associations as sorted or as sequenced (see ldquoSorting and

sequencingrdquo )

Instance options

bull Instances may not be created

You can create an association type that does not have any instances of its own but that

may be a supertype for other related association subtypes by checking the Instances may

not be created checkbox The related association subtypes may themselves have

instances (see ldquoSubsets properties pagerdquo )

You can create some association instances and then select the Instances may not be

created checkbox on the Association type properties dialog This forces users to choose

from a limited range of instances

bull Instances may not be deleted

Check the Instances may not be deleted checkbox to prevent users from deleting any of

the instances that are created for this type

bull Duplicate instances are not allowed

Check the Duplicate instances are not allowed checkbox to prevent the creation of

duplicate instances and to ensure that all instances are unique

Schema Pages

Schema Pages can be used to arrange Association Types into Tabbed pages on a

Dataform Association Types are automatically placed on a different page if they are

sourced on a Subset or Subtype and the Dataform Tab is given that Subset or Subtype

name Schema Pages allow any arrangement of Pages and are used as the default pages

when a Custom Dataform Query is created

To create a Schema Page you can either enter a new Page Name in the Association Type

Properties General Tab or you can select the Create Pagehellip Menu Item when a type is

selected in the Schema Pane

To organise which pages all Association Types are displayed on and the order

1 Select the Type that you wish to organise Pages for in the Schema Pane and

select Organise Pageshellip from the Schema Menu

Database components


173

The Organise Pages Dialog allows you to

bull Create Delete Rename and Reorder Pages

Use the Add Delete Rename and Move buttons at the bottom of the dialog to

change the pages used for the selected Type and their order

bull Change Association Type Pages

Select one or more Association Type select a page and click the Change Page

button to move the selected Association Type(s) onto that page

bull Reorder Association Types

Using the Move Up and Move Down buttons the order of Association Types on

each Page can be altered

bull Hide Association Types

Select one or more Association Type and set or clear their ldquoHidden on dataformrdquo

property

Database components


174

Once pages exist in the Schema Pane you can also drag and drop individual Association

Types onto different pages You can also reorder pages by dragging one onto another

If there is an empty page after you have finished organising then it will not be saved

between sessions

Metatypes

Metatypes are the categories of data that appear in the schema pane You can create an

association type that uses a metatype as its target The available metatypes are Entity

type Association type Query and Custom Dataform The instances of a metatype are

the types that are defined in the current schema

Metatypes may only be used as the target of an association and not as the source An

association type that has a metatype as its target behaves in the same way as any other

association type and may be used in queries and custom Dataforms

Using metatypes

To use a metaschema type as the target of an association select a type from the

Metatypes folder The Metatypes folder is a subfolder of the All types folder in the

target area of the Create Association Type dialog You cannot type in the name of a new

metatype

Creating associations

Associations can only be created through the Dataform (see ldquoCreating an association in

the Dataformrdquo )


You can use the Delete button on the toolbar or the Delete command on the Edit toolbar

to delete any entity or association type or instance You can delete a value type but you

cannot delete a value instance

Figure 5-7 Impact of deleting dialog for a data item

Impact of deleting dialog

Sentences displays an Impact of deletinghellip dialog which displays the items that are

affected by the delete action and prompts you for confirmation The name of the dialog

shows the name of the item you want to delete

Database components


175

Figure 5-7 shows an example of an Impact of deletinghellip dialog for a data item and

Figure 5-8 shows an example of an Impact of deletinghellip dialog for a schema item which

includes a display of the relevant part of the schema tree

Figure 5-8 Impact of deletinghellip dialog for a schema item

Internally Sentences does not physically delete any element but instead makes the

particular element invisible The delete action is recorded in the relevant changes chapter

defined in the current profile This means that you could devise an arrangement of

chapters and profiles in such a way that certain information was available in one profile

and was not available in another profile

You cannot undo Delete actions You can recreate any item that you have deleted but as

every item in Sentences has a unique internal identifier the recreated items are not

identical to the items they replace even if they share the original deleted itemrsquos name and

attributes

Implicit deletion

Sentences automatically enforces referential integrity constraints when any item is

deleted If you delete an entity instance you also delete any association that uses that

entity as its source or target and these associations are listed in the Impact of deletinghellip

window If you delete an entity type you also delete all its instances along with any

association types that use it as a source or as a target along with all the associations that

are instances of those association types

When you delete an item any other items that are dependent on it are also deleted The

following list summarises the dependencies in Sentences that are affected by a delete

action

bull An association type is dependent on its source and target whether they are types or

instances

bull An entity or association instance is dependent on its type

bull An association instance is dependent on its source and target instances

bull Instances of a subset type are dependent on the existence of the superset type

bull A schema type is dependent on another type that you have defined as its

equivalent

There is no dependency in the following cases

bull A subset type is not considered dependent on the existence of the superset type even

though instances of it are This means that you can use a type originally defined as a

subset after its superset is deleted If you delete a superset type the subset type becomes a

Database components


176

normal type and you can create instances of it You cannot re-establish a subset-superset

link after you delete the superset

bull Subtypes and supertypes are not considered to be dependent on one another

Renaming types and instances

You can rename any entity type or instance or any association type that appears in the

Sentences Explorer You can rename a value type but you cannot rename a value

instance Renaming an association type changes the verb of the association not the source

or target

The unique internal identifier of the type or instance is not affected by renaming and the

new name appears automatically wherever the type or instance is used

To rename a type or instance highlight it in the Sentences Explorer and select the

Rename command from the Edit menu or the shortcut menu Sentences displays an

editing box around the existing name You can now type in the new name When you

move to another field or press Enter your changes are saved

The Rename command is not available for value instances in the Sentences Explorer If

you need to change a value instance you must use the Dataform

Inactive Instances

During the life of an application data often becomes inactive and no longer ldquocurrentrdquo but

is still needed for historical reference More importantly the application designer may

wish to prevent the user from continuing to reference these inactive instances Sentences

provides a way to identify instances as ldquoinactiverdquo and to hide them from the user to de-

clutter the user interface and prevent their accidental use

In addition if a user does select such an inactive instance in a Dataform then Sentences

can warn them of this

To specify that an Association Type is to be used as the sourcesrsquo ldquoinactiverdquo indicator it

has an attribute on the Association Type property page in the Instance options section

Database components


177

The presence of an association instance indicates that the source (in the example above a

instance of Employee) is no longer active If there are two Association Types ndash for

example (Person inactive Flag) and (Employee inactive Flag) then either or both will

make an Employee inactive Both will have to be clear for the Employee to be active

The Data Pane will not include inactive instances by default This only applies to the root

instances When you drill down all data will be shown If the user preference is changed

to show inactive instances then they are highlighted with a suffix Inactive and the font

is in italics

The Query Editor has a ldquoShow inactive instancesrdquo checkbox for convenience to include

inactive instances in the results This is off by default and it is only the root results that

are filtered

Locating data in the Sentences Explorer


178

The Dataform pickers also default to not initially including inactive instances This can be

overridden by checking the box at the bottom

When applying a child dataform or saving a parent dataform Sentences informs the user

if they have included inactive instances Any pre-existing inactive instances are not

highlighted


When you select a type in the Explorer schema pane you send a data request from your

Sentences client to the Sentences server In response the Sentences server loads and

displays data from your database in the Explorer data pane Whenever you execute a

query or use the Positioner and Filter tools you are also making a data request

Sentences does not automatically load all the available data for a type from the server and

display it in the data pane each time you make a request This is to reduce unnecessary

network traffic between the Sentences server and client

Sentences provides a number of tools to help you locate data in the Explorer which are

described in this section

Also be aware that the visibility of instances can be affected by the Transaction Visibility

mechanism (See ldquoTransaction Visibilityrdquo for details)

Demand loading of data

The number of data items loaded at each data request can be configured using the optional

applet parameter RequestSize The default value for this parameter is 50 data items You

can change this value by adding the RequestSize parameter to the jnlp or javascript

definition (see ldquoAdditional optional parametersrdquo)

The More prompt

Whenever more data than that already displayed in the data pane is available in the

database Sentences displays a special prompt in the data pane (the

Morehellip prompt) to indicate that more data items exist in the database as shown in Figure

5-9

The Morehellip prompt appears in the Explorer data pane and in the Query Editor results

pane for the top level data request (the type selected in the Explorer schema pane or the

root node of the query) and for forward and inverse associations The Morehellip prompt



179

also appears in multiple association fields in the Dataform such as list boxes tables and

tree displays

When derived types or derivations are used in queries Sentences needs to calculate all

values before displaying the derived type or derivation result For this reason the Morehellip

prompt is not displayed for nodes used in calculating derived types or derivations The

Morehellip prompt is also not displayed for any node that includes the type referenced in the

derived type or derivation apart from those nodes directly between the derived type or

derivation and the root node of the query

Figure 5-9 An example of the Morehellip prompt

To load more data double-click on the Morehellip prompt displayed at the bottom of the

data pane or press the Page Down key on your keyboard

Each time you click the icon or press Page Down Sentences loads more data items

according to the number of items specified by the RequestSize parameter until all the

available data items are displayed at the client

The Positioner and Filter tools

The Sentences Explorer has two tools to help you locate data more quickly the

Positioner and the Filter These tools are located on the right hand side of the toolbar

They are also available on Picker dialogs in the Dataform

Figure 5-10 The Positioner and Filter tools

The Positioner and Filter tools each have a value entry field on the toolbar On the far

right there is the data reload button The Positioner and Filter both work only on the top

level of displayed data that is the data level that matches the type currently selected in the

schema pane



180

The Positioner tool

The Positioner tool locates the first data item that matches the value you entered in the

entry field Sentences clears the data display and then displays data items starting at the

first matching data item This is not the same as the ldquoFindrdquo feature found in some other

applications

To use the Positioner tool type in a value in the entry field and press Enter or click the

Reload Data button The value you choose must be a valid value for an instance of the

current type but it does not have to be a value that exists in the database For example if

the current type allows character strings for names you can type in the value P in the

Positioner field and press Enter or click the data reload button Sentences displays names

beginning with the first item that begins with that letter as shown in Figure 5-11 The

Positioner tool does not use wildcards

Figure 5-11 Sentences Explorer display with Positioner value P

If you type in a value that does not exist the Positioner displays data starting with the

first available item after the value you entered Figure 5-12 shows the result of entering

the value Ps in the Positioner field



181

Figure 5-12 Sentences Explorer display with Positioner value Ps

For associations Sentences applies the same rule to the original source entity type For

example if the current association type is ((Person customer of Store) visited on

Date) then the Position field needs a Person value since the list is ordered by Person

The Filter tool

The Filter tool locates all the data items that match the value you entered in the entry

field To use the Filter tool type in a value in the entry field and press Enter or click the

Reload Data button

Sentences clears the data display and then displays the filtered data items If there are

more items available than there is room in the data pane Sentences displays the Morehellip

prompt

Pattern matching with the Filter tool

The Filter tool is case insensitive but it does supports pattern matching with wildcards

Filter Tool Wildcard Meaning

matches any single character

matches from zero to any number of characters

| or

If you want to use any of the wildcard characters as part of your pattern you need

toldquoescaperdquo the character with a backslash as follows

Escape Characters Meaning

Represents a literal character



| Represents a literal | character

Single Backslashes are ignored



182

The Filter tool searches from the start of the value stored This means that if you want to

filter using partial string that is not at the start of the stored value you should use the

asterisk wildcard before the filter term Similarly if you want to filter using partial string

that is not at the end of the stored value you should use the asterisk wildcard after the

filter term

For example and would return band hand sand and so on and and would also return

and grand and brand The filter argument profile|chapter would return any

string that contained the word profile or the word chapter By contrast the filter

argument profilechapter would only return a string that contained both the word

profile and the word chapter

Figure 5-13 shows the result of using the filter Ven

Figure 5-13 Sentences Explorer display with Filter value Ven

Using Filtering and Positioning tools together

You can use the Positioner and the Filter tools together If you type in values in both

entry fields Sentences displays entities or associations matching the Filter value starting

at the point specified by the Positioner value

Figure 5-14 shows the result of using the Positioner value M with the Filter value Ven

Compare this result to that shown in Figure 5-13 which showed the Filter being used on

its own



183

Figure 5-14 Sentences Explorer display with Positioner value M and Filter value Ven

Reloading data

To restore your view to all the available data clear any values from the Positioner entry

field and the Filter entry field and click the Data Reload button If there is more data

available than can be shown Sentences displays the Morehellip prompt

If you highlight the name of a query in the schema pane you can use the Data Reload

button to display the results of the query in the data pane

Stopping data retrieval

When you request data from the Sentences server Sentences returns a number of data

items up to the limit specified in the RequestSize parameter (see ldquoAdditional optional

parametersrdquo ) Occasionally this data retrieval action may take a long time for example

because the RequestSize parameter is set to an inappropriately high value

The Stop button

You can stop the retrieval of data by clicking the Stop button on the toolbar

This button is only available while a data retrieval action is taking place and the message

Retrieving data is displayed in the data pane

This is shown in Figure 5-15



184

Figure 5-15 Using the Stop button

When you click the Stop button the data retrieval action stops on the server and

Sentences displays a message in the data pane

The Stop button is available in the Sentences Explorer the Diagram Editor and the

Query Editor You can only stop a data retrieval action by using the Stop button in the

same window that started it You cannot for example use the Stop button in the Explorer

to stop a data retrieval action started in the Query Editor

Sorting and sequencing

You can sort data and schema items in Sentences The Sentences default sort algorithm

which is alphanumeric and case insensitive applies to instances of types that do not have

a defined datatype (their datatype is displayed as ltNonegt) Defined datatypes each have

their own specialised sorting algorithm which are described in the datatypes section (see

ldquoDatatype properties pagerdquo )

The Sentences sequencing feature lets you define explicit data sequences in the Sentences

Explorer and Dataform You can use sequencing with a series of association types

sourced from a particular type and with a set of instances of a multiple association type If

you change the sequence of association types in the schema pane the corresponding data

items appear in the sequence you defined when the display is refreshed

Sequencing association types

The order in which associations appear in the Default Dataform is the same as the order in

which they appear in the schema pane A change in the order of association types in the

Sentences Explorer schema pane is always reflected in the Default Dataform

The default order of association types is the order in which they were created To change

this order you can cut and paste or drag and drop an association type to a new position in

the schema pane with either the same or with a different source If you change the source

of an association type any associations of that type which exist are no longer visible

Properties


185

When you use the shortcut menu command Create Association Type or use the Create

Association Type toolbar button new association types are added to the end of the set of

existing association types for their source You can create a new association type in a

specific position by using the shortcut menu command Insert Association Type Above

This command creates a new association type and positions it above an existing selected

association type from the same source

Sequencing multiple instances

You can apply an explicit sequence to the instances of a multiple association type When

you create an association type or set its properties you can select the Multiple option

which means that you can create many instances of the association for each source By

default Sentences displays multiple association instances as sorted by their targets

according to the sort algorithm of the target type

If you select the Sequenced option in the Association Type Properties dialog the

instances of the association type are always displayed in their defined sequence which by

default is the order in which they were created You can change this sequence in the

Sentences Explorer data pane using the cut and paste options This is similar to the way

you can change the sequence of association types as described earlier

The sorting algorithm applied to a set of target entities is determined by the datatype of

their entity type (see ldquoDatatype properties pagerdquo )

Properties

Several new property pages have been added to types in Sentences Version 40 and some

include additional items

Business Rules introduce two new property pages for State Domains and Business

Rules See the Business Rules section for details

Types now have another property used to display a friendlier name in various parts of the

Sentences interface See the Display Name Query section for details

On the Retrieval Methods properties page there is an additional option for whether to

determine if child associations are present or not This means that both Entity Types and

Association Types now include a Retrieval Methods properties page See the Determining

if child associations are present section for details

The Datatype properties page now includes the new ImageData datatype The Format

properties page will be affected by default field widths and format patterns See the

Database Components section for details


previously not allowed This means that the properties of a Subset have an additional

Subsets page for their subsets as well as the existing Presentation and Description pages

Subsets can have their own (and inherited) State Domains so the properties of a Subset

also include a State Domains page but not a Business Rules page

When an Associative Model is generated automatically by importing a Relational

Database Schema the description field of types is populated with the catalog schema


The Mapping property page used by the previous version of LazyView is no longer

required

You can define a number of properties for entity types and association types in the

Sentences database by using the entity type and association type Properties dialogs

These dialogs have a number of tabbed pages some of which are common to both entity

types and association types as shown in the following list

Properties


186

Property Page Appears for entity types Appears for

association types

General Yes No

Datatype Yes No

Format Yes Yes

Presentation Yes Yes

Display Name Query Yes Yes

Subsets Yes Yes

Supertypes Yes Yes

Equivalence Yes Yes

Triggers Yes Yes

Description Yes Yes

Custom Dataform Yes Yes

State Domains Yes Yes

Business Rules Yes Yes

Diagram Images Yes Yes

Default Sorting Yes Yes

Association Type No Yes

Target Parameters No Yes

Derived Target No Yes

Dataform No Yes

Retreval Methods No Yes

General properties page

Figure 5-16 The General properties page

The General properties page applies only to entity types Some of these properties are

available on the Association Type properties page

Properties


187

Display in Core types folder

If you have not chosen the Generate Core types automatically option in the Edit

Profile dialog you can select an entity type to be displayed in the Core types folder by

selecting the Display in Core types folder checkbox (see ldquoThe Core types folderrdquo )

Instance options

The following options apply to instances of this type When a type is defined as a Value

type all of these properties are disabled and cannot be changed


You can define an entity type that does not have any instances of its own but that may be

a supertype for other related association subtypes by checking the Instances may not be

created checkbox The related entity subtypes may themselves have entity instances (see

ldquoSupertypes properties pagerdquo )

You can create some entity instances and then select the Instances may not be created

checkbox This forces users to choose from a limited range of instances For example you

could define an entity type Boolean with instances True and False and then select the

Instances may not be created checkbox

Note When Instances may not be created is selected instance names cannot be generated

automatically or by a trigger See Instance name creation options below




bull Instances may not be renamed

Note Instances may not be renamed does not apply to association types and does not

appear on the Properties dialog for association types

Check the Instances may not be renamed checkbox to prevent users from renaming any

of the instances that are created for this type

Note Instances may not be renamed is automatically selected if instance names are not

being created by the user The name is automatically generated using one of the methods below




Note The Instance Options check-boxes for association types are on the Association type

properties page The options Instances may not be renamed and Instances created by

trigger do not apply to association types

Instance name creation options

Note Instance name creation options do not apply to association types and do not appear

on the Properties dialog for association types

Note Instance name creation options do not apply to value entity types The name will

always be given by the user


automatically or by a trigger

You can define an entity type that has the names of its instances generated automatically

by the system This may be used for example to automatically create invoice numbers or

order numbers in a business application

bull Instance name created by user

Properties


188

If you select this option for an entity type the user must enter a name for the Entity Type

bull Instance name created by trigger


by a trigger This may be used for maximum flexibility when generating identifiers but

requires some programming resources The other options require no programming

knowledge

If you select this option for an entity type you cannot create new entity instances by

typing into a Dataform field You must open a Create Dataform from the entity type An

entity type that uses the Instance name created by trigger option may be the source of

association types in the same way as any other entity type

For general information on triggers see the section ldquoTriggersrdquo There is a worked

example of an Order Entry application which uses a trigger to create instance names for

orders in the section ldquoDerivations examplerdquo This worked example uses a trigger named

RenameInstance which is included in the ExampleTriggersjar file in the directory

ExamplesJars

If you use XML Import to add data instances for entity types which use the Instance

name created by trigger option you must make provision for the trigger action in your

XML data structure (see ldquoXML Import and triggersrdquo )

bull Instance name created by generating a GUID


by a generated Globally Unique Identifier (GUID) The value of a GUID is represented as

a 32-character hexadecimal string such as

063a1d33-2189-49d3-969c-967d60e3dab5

The total number of unique keys is 2128 or 34times1038 This number is so large that the

probability of the same number being generated randomly twice is negligible


typing into a Dataform field You must open a Create Dataform from the entity type The

GUID is generated when you save the Dataform

bull Instance name created by incrementing ID


by a generated ID The value of the ID starts with the one that you enter here and this is

incremented each time an entity is created



ID is generated when you save the Dataform

The ldquoseedrdquo ID can be either a whole number or an alphanumeric identifier When

incrementing the ID Sentences will take the trailing numerical part of the ldquoseedrdquo and

increment this by one A decimal point or comma will be treated as a non-numerical

character

If there is no trailing numeric part then Sentences will start with a zero If the numeric

part has leading zeros then these zeros will be retained until the number is larger than the

number of digits and then the ID will increment as normal

Some examples

1 2 3 4 5 hellip

0098 0099 0100 0100 hellip

ID0098 ID0099 ID0100 ID0100 hellip

PER PER0 PER1 PER2 PER3 hellip

1234997 1234998 1234999 12341000 12341001 hellip

Properties


189

bull Instance name created by current timestamp


by using the current server timestamp



timestamp is generated when you save the Dataform

Datatype properties page

The Datatype properties page applies only to entity types

Figure 5-17 Selecting a datatype

Use the Datatype page of the Properties dialog to set the datatype for an entity type

Using datatypes allows for example input values to be checked for validity and

determine the range of formatting and presentation options that are available for instances

of a type and how instances are sorted

The use of datatypes also affects instance behaviour and visibility in that instances of

types that have datatypes assigned to them generally behave as values (see ldquoValue types

and datatypesrdquo ) You can prevent instances behaving as values by clearing the Instances

are values check box when you assign a datatype (see ldquoInstances are valuesrdquo ) This

allows you to make use of the formatting and presentation options associated with the

datatype without creating a value type

Value types and value instances are distinguished in the Sentences Explorer by

discshaped icons Because value types cannot be the source of association types you must

not define an entity type that you want to use as the source of an association type as a

value type For more information about values and value types and their relation to

datatypes see ldquoValue types and datatypesrdquo and ldquoImpact of changing a datatyperdquo

Instances are values

Check or clear the Instances are values checkbox to determine whether or not the type is

a value type and its instances are values This checkbox is selected by default for all

Sentences-supplied datatypes Clearing this checkbox means that instances have the

formatting and sorting characteristics associated with the datatype but the instances are

not values and the type is not a value type You may can also create your own custom

datatypes (see Chapter 10 ldquoCustomising Sentencesrdquo)

For more information about values value types and datatypes see ldquoValue types and

datatypesrdquo and ldquoImpact of changing a datatyperdquo

Properties


190

Assigning datatypes

To assign a datatype select a datatype from the drop down list on this page Depending

on the datatype selected other fields may be displayed on this page such as the

Maximum Decimal Places field for number datatypes The characteristics of each

datatype are described in the following sections

bull Undefined (displayed as ltNonegt)

If you do not assign a datatype the Datatype page displays ltNonegt as the datatype The

only presentation formats allowed are single-line or multi-line edit fields (using Tab and

Return characters)

Entity instances for types that do not have a defined datatype are limited to strings of

standard printable ASCII characters with a maximum string length of 64000 characters

Instances of types that do not have a defined datatype are sorted in a case-insensitive

alphanumeric order (that is 0hellip 9 Aa Bb hellipZz)

String datatypes

The string datatypes are Text Image Email and Hyperlink String datatypes are value

types but they do not support arithmetic operations

bull Text

In the Text datatype Tab and Return characters are allowed and therefore multiline

values can be created if the multiple line presentation method has also been selected

Multiple line values are only displayed as multiple lines in the Dataform In the Sentences

Explorer multiple line values are displayed all in one line and a semi-colon character is

used to mark the position of line breaks You can only use the multiple line presentation

method for singular associations and not for multiple associations

Instances of types that are defined with the Text datatype are sorted in a casesensitive

alphanumeric order (that is 0hellip 9 A B hellipZ a b hellipz)

Using the Hidden style for the Text datatype results in the display of asterisks on the

dataform instead of the actual text entered

bull Image

Sentences supports the display of JPEG and GIF image file formats When you type in the

location of an image file in a target field defined with the Image datatype the Dataform

displays the image The Sentences Explorer displays the file name or URL

Sentences can display any image hosted on any web server that it can access if the image

file is referenced by a full URL such as httplazysv04databasesimagesJanejpg

You cannot specify an image location using a file path

You can reference images more easily if you specify a location for all your image files

using the ImageURLBase parameter in your jnlp or javascript definition (see ldquoAbout the

ImageURLBase parameterrdquo) You could then use the file name on its own or a partial

URL For example if the ImageURLBase parameter was set to

httplazysv04databasesyou could refer to an image file simply as

imagesJanejpg

Instances of types that are defined with the Image datatype are sorted in a casesensitive


bull Hyperlink

When you use the Hyperlink datatype the entered value is treated as a World Wide Web

Uniform Resource Locator (URL) When such a value is opened (by double clicking or

Properties


191

by selecting Follow Hyperlink from the shortcut menu) the Web page or file to which the

URL refers is displayed

The Hyperlink datatype allows Sentences to link to a variety of electronic documents

You can use any kind of URL for the Hyperlink datatype including http for Web

page addresses mailto for email addresses and file for host-specific file names If

you are using Microsoft Outlook you can use the outlook prefix to create a URL that

links to a Microsoft Outlook folder

Instances of types that are defined with the Hyperlink datatype are sorted in a

casesensitive alphanumeric order (that is 0hellip 9 A B hellipZ a b hellipz)

The Hyperlink properties includes a default Protocol which can be set to ltAutogt

mailto http https file or specified yourself This will be used if no

protocol is entered in a dataform field

bull Email

The Email datatype is a convenient specialisation of the Hyperlink datatype with the

protocol hard-coded to be mailto

Numeric datatypes

The numeric datatypes are Number Currency MixedCurrency and Percentage All of

these datatypes support standard arithmetic and comparisons Any two Number or

Percentage instances can be used in arithmetic or compared Two Currency instances can

only be used in arithmetic or compared if they represent values in the same currency

When you select Number MixedCurrency or Percentage you must define the maximum

number of decimal places as shown in Figure 5-19

Figure 5-18 Defining decimal places for a number datatype

bull Number

The Number datatype supports storage to 17 significant digits with an optional sign

character (+-) of both floating point and integer values This datatype does not support

ldquoexponent and mantissardquo style inputs (for example 123e+10) Magnitudes smaller than

1e-16 are rounded to zero Magnitudes larger than 1e+17 are rounded to 17 significant

digits Numbers which cannot be stored exactly are rounded up or down to the nearest

exactly storable value

Instances of types that are defined with the Number datatype are sorted in numerical

order

Properties


192

Figure 5-19 Selecting the currency for a Currency datatype

bull Currency

The Currency datatype supports the use of monetary values A standard international set

of three character currency codes is used for example USD GBP and EUR The

currency datatype ensures that arithmetic can only be conducted between monetary values

in the same currency For example monetary values in queries must be of the same

currency in order to be compared

When you select the Currency datatype you need to select the currency as shown in

Figure 5-19

Instances of types that are defined with the Currency datatype are sorted in numerical

order

International considerations for the currency datatype

The way currency values are displayed on your system depends on your computerrsquos

settings and on the locale settings used by the Java Runtime Environment installed on

your computer

bull MixedCurrency

The MixedCurrency datatype supports monetary values in more than one currency Each

value entry has two parts specifying the currency and the monetary value The only

arithmetical operations that are available with the MixedCurrency datatype are either

multiplication and division by a Number datatype or an arithmetical operation with

another value that has the MixedCurrency datatype

Instances of types that are defined with the MixedCurrency datatype are sorted by

currency type and then in numerical order

bull Percentage

Value instances defined with the Percentage datatype are floating-point numeric values

Instances of types that are defined with the Percentage datatype are sorted in numerical

order

Date and time datatypes

The date and time datatypes are Date Time and Timestamp Each of them has an

internal numeric representation allowing arithmetic and comparisons to be performed

correctly For arithmetic none of them supports the multiply divide or remainder

operators For comparisons earlier dates or times are considered to be less than later ones

Properties


193

International considerations for date and time datatypes

The way dates and times are displayed on your system depends on your computerrsquos


your computer

The Sentences date and time datatypes are based on the Java formats Date and time

formats for locales other than the US are only supported by the International version of

the Java Runtime Environment

bull Date

The Date datatype represents an individual date such as September 14th 1998 The

stored value is a whole number of days since a starting date This makes it independent of

time zones and ensures that comparisons for equality can be done correctly

Sentences does allow you to enter a year using only two digits although this is not

recommended Sentences calculates the century for two digit years by assuming a century

that begins 80 years before the current date and ends 20 years after the current date

If you enter a year using only one digit or using three or four or more than four digits

Sentences accepts the year value exactly as entered Sentences does not allow negative

values for years

Sentences does not accept invalid month and day of month values including leap year

calculation

For details of arithmetic operations that are supported with the Date datatype please see

ldquoArithmetic operations with Date and Time datatypesrdquo

Instances of types that are defined with the Date datatype are sorted in chronological

order

bull Time

The Time datatype represents a time of day such as 114305 The stored value is a whole

number of milliseconds since midnight Sentences stores and displays time without any

reference to time zones or time schemes This means that a value entered as 1100AM is

always displayed as 1100AM regardless of the time zone it is displayed in

When you perform arithmetic with time values additions and subtractions wrap around

2400 For example 2300 plus two hours gives 0100 not 2500

For details of arithmetic operations that are supported with the Time datatype please see


Instances of types that are defined with the Time datatype are sorted in chronological

order

bull Timestamp

The Timestamp datatype represents single point in time with millisecond precision such

as 1998 September 14th at 114305 BST Timestamp values are displayed in the context

of the current time zone However this affects only the display not the stored value

For details of arithmetic operations that are supported with the Timestamp datatype

please see ldquoArithmetic operations with Date and Time datatypesrdquo

Instances of types that are defined with the Timestamp datatype are sorted in

chronological order

Properties


194

Format properties page

Figure 5-20 (The Format properties page

The Format properties page is available on the Properties dialog for both entity types

and association types This page allows you to define the input and output formats

displayed on the Dataform The options available vary according to the datatype selected

and according to whether the association type is singular or multiple

The default format of association types is inherited from the datatype of the association

typersquos target You can use settings on the Format page to override the default settings

Presentation

Presentation options define the display of fields on the Dataform The first field in a

dataform represents instances of the source type and the label for this field is the name of

that type All the other fields on the Dataform represent the targets of associations sharing

the same source and the labels for these fields are the association verbs

You can define presentation options using the Properties dialog opened on an entity type

or an association type Presentation options defined for an entity type are inherited by any

association in which the entity type is a target but can be overridden by options set for the

association type

The following table shows the presentation options that are available for the different

datatypes in Sentences

Properties


195

Datatype of Target Presentations for Singular

Association Types

Presentations for Multiple

Association Types

Currency

Date

Hyperlink

Image

MixedCurrency

Number

Percentage

Time

Timestamp

Single Line

Combo

Radio Button

Tree

Table for targets

Table for associations

Nested panel

Button for target

Button for association

Label

List

Checkbox

Tree

Table for targets


ltNonegt

Text

Single Line

Multiple Line

Combo

Radio Button

Tree

Checkbox

Table for targets


Nested panel

Label

List

Checkbox

Tree

Table for targets


In addition the Checkbox and Combo are supported within tables when they can be

edited

The appearance of each of these presentation methods is as follows

bull Label

The association target is represented as a non-editable field with no border and so appears

as if a label The contents can be copied

bull Single Line

The association target is represented on the Dataform by a single line editable field

bull Multiple Line

The association target is represented on the Dataform by a multiple line editable field

bull Combo

The association target is represented on the Dataform by a single line field with a drop-

down arrow that can be used to display a list of existing target instances

bull List

The association target is represented on the Dataform by a list of existing target instances

bull Tree


displayed as an expandable tree similar to the display used in the Explorer data pane

bull Checkbox

The association target is represented on the Dataform by a series of targets each indicated

by a small box and a text label More than one target may be selected

bull Radio Button

Properties


196


by a small circle and a text label Only one target may be selected In the following

definitions the term primary association refers to an association whose source is the entity

or association instance for which the Dataform is opened

bull Table for Associations

Table for Associations displays a primary association and all singular associations whose

source is the primary association The columns display the targets of the associations

concerned and the headings are the associations types The first column heading is the

type of the target of the primary association

bull Nested panel

A Nested panel displays a primary association (similar to a Single Line presentation) and

below it all associations whose source is the primary association within a nested panel

The secondary associations could themselves have any presentation including Nested

panel

bull Table for Targets

Table for Targets displays a primary association and all singular associations whose

source is the target of the primary association The columns display the targets of the

associations concerned and the headings are the associations types The first column

heading is the type of the target of the primary association

bull Button for Target

Button for Target displays a button that opens a child dataform on the target of the

singular association and its children The right-alignment format property is honoured

bull Button for Association

Button for Association displays a button that opens a child dataform on the singular

association and its children The right-alignment format property is honouredbull Disable

in-place editing

When the presentation option is set as either Table for Associations or Table for

Targets you can edit the target value directly in the Dataform table without the need to

open a child Dataform

You can disable this feature by checking the Disable in-place editing checkbox

Picker

Some Dataform fields allow you to select target instances from a list known as a Picker

launched from the ellipsis button next to the field The Picker field allows you to choose

either the List picker or the Tree picker for selecting values A List picker displays a

simple list of instances while a Tree picker displays a list of instances that can be

expanded to display associations as in the Explorer data pane

You can also select a special Calendar picker for types defined with the Date datatype

To disable the display of a picker select None as the Picker type

Style

The table below shows the different styles (for output) that are available for different


In the formats for Currency and MixedCurrency the letter C represents the currency

symbol for example pound or $ and the letter I represents the three letter ISO currency code

for example GBP or USD

Properties


197

Datatype Styles

ltNonegt ltNonegt

Currency ltDefaultgt

C0C-0

C000C-000

C0C-0

C000C-000

0C

000C

0C

000C

I 0I -0

I 000I -000

I 0I -0

I 000I -000

MixedCurrency ltDefaultgt

C0C-0

C000C-000

C0C-0

C000C-000

0C

000C

0C

000C

I 0I -0

I 000I -000

I 0I -0

I 000I -000

Date ltDefaultgt

Short

Medium

Long

Full

Number ltDefaultgt

0

000

0

000

Percentage ltDefaultgt

0

000

0

000

Text ltDefaultgt

Hidden

Time ltDefaultgt

Short

Medium

Long

Full

Properties


198

Datatype Styles

Timestamp ltDefaultgt

Short

Medium

Long

Full

SDateSTime (Short Date and Short Time)

SDateMTime (Short Date and Medium Time)

SDateLTime (Short Date and Long Time)

SDateFTime (Short Date and Full Time)

Display width

The Display width parameter specifies the width of the display field for an instance in

characters The unit for this setting is based on the width of a lower-case ldquowrdquo character

and the default setting is twenty-five characters

You can only use positive numeric values This parameter is disabled if the Presentation

method is set to Radio Button or Check box

Table column width

The Table column width field allows you to set the width for the association or entity

when it appears in a table on the Dataform The unit for this setting is based on the width

of a lower-case ldquowrdquo character The default setting if no value is specified is two-thirds of

the length specified for Display width

Display height

The Display Height parameter specifies the height of the display field in rows for multi-

line entries The default setting is six rows

Format options

The following options can be selected by checking the check-boxes on the Properties

dialog Format page for association types and entity types

bull Read only on Dataform

The Read only on Dataform option defines an association or entity that cannot be altered

by the user through the Dataform This setting is useful for association types whose

values are generated automatically by customised triggers For more information see

Chapter 10 ldquoCustomising Sentencesrdquo

bull Hidden on Dataform

The Hidden on Dataform option defines an association or entity that is not displayed on

the Dataform If you select this property there is no label or field for this type on the

Dataform and therefore no access from the Dataform for this type

If you select Hidden on Dataform then Hidden in Dataform tables is also selected

automatically

bull Inverse Hidden on Dataform

The Inverse Hidden on Dataform option defines an association or entity that is not

displayed on the Dataform in the inverse direction If you select this property there is no

label or field for this type on the Dataform and therefore no access from the Dataform for

this type in the inverse direction

The default is to hide Association Types in the inverse direction

bull Hidden in Dataform tables

Properties


199

The Hidden in Dataform tables option defines an association or entity that is not

displayed in a Dataform table If you select this property there is no column for this type

in a Dataform table


automatically

bull Right-align in Dataform fields

The Right-align in Dataform fields option defines associations or entities which are to

be displayed as right-aligned in Dataform fields

bull Right-align in Dataform tables

The Right-align in Dataform tables option defines associations or entities which are to

be displayed as right-aligned in Dataform tables

bull Allow multi-line label on Dataform

The Allow multi-line label on Dataform option allows the label of a Dataform field (the

name of the source type or the verb of an association type) to be displayed over multiple

lines

Presentation of date formats

The presentation of Date formats depends on the version of the Java runtime environment

installed on your computer The US version of Java only supports the US date format

(monthdayyear) The Internationalised version of Java supports the European date

format (daymonthyear) If you only use two digits for the year Sentences assumes a

century that begins 80 years before the current date and ends 20 years after the current

date

Presentation of time formats

The presentation of Time formats depends on the version of the Java runtime

environment installed on your computer The US version of Java only supports a 12- hour

clock format with AM or PM The Internationalised version of Java supports the 24-hour

clock format If you are using the US version of Java you can input times as for example

130PM and if you are using the Internationalized version you need to enter 1330

Restore Default settings button

The Restore Default settings button on the Format properties page allows you to reset

all the values to the defaults for the current datatype For association types the Restore

Default settings button resets all the values to the current Format settings for the

associationrsquos target which may differ from the defaults for the datatype

Properties


200

Presentation properties page

Figure 5-20a The presentation properties pages for Entity Types and Association Types

The presentation properties are used to customise the presentation of Types and Instances

in Sentences This can be in the Sentences Explorer a Dataform or XML output that has

been transformed into HTML

bull Small icon large icon

The icons specified here will be used to replace the standard icons in the Sentences

Explorer and used in any XML output You can select an image from the Image picker by

clicking on the button The available images are those in the directory of image files on

the server

bull Start of section

Note Start of section is not applicable to Entity Types

The Start of section determines whether an instance of this association should start a new

section of the XML output Each section can have a title icon and some introductory text

assigned to it

bull Section title Section icon Introductory text

Note Section title Section icon Introductory text are not applicable to Entity Types

Each section can have a title icon and some introductory text assigned to it This is

intended to be used where the child results of this item will form the section details

You can select an image from the Image picker by clicking on the button The available

images are those in the directory of image files on the server

Properties


201

Display Name Query properties page

Figure 5-20b The display name query properties page

Display name queries can be used to enhance the ldquonamerdquo of an Entity or Association by

providing an alternative based on the instances attributes A Display Name Query can use

the full power of the query mechanism to form a name This is particularly useful when

the identifier for an Entity is an ID rather than a name as when mapping relational data

into Sentences In this scenario a Display Name Query can be used to display the name

attribute of the entity and the unique ID together making the display of those instances far

more readable and intuitive

For more details on Display Name Query capabilities and how to construct them see

ldquoDisplay Name Queriesrdquo

To specify a display name query

1 Open the Display Name Query page of the Properties dialog for one type

and click on the button

2 Select the query you wish to use or ltNonegt to remove an existing display

name query and click OK

Properties


202

Subsets properties page

Figure 5-21 The subsets properties page

bull The subsets mechanism

Subsets are one of the two mechanisms that allow different types in a database to share

common features The other mechanism is Supertypes

The subset mechanism allows you to define a group of instances of a given type that

match a particular condition You may create a subset that contains all the instances of its

superset The supertype mechanism allows you to define a hierarchy of types with certain

associations common to more than one subtype

Association types sourced on supersets and supertypes are shared by the respectivesubsets

and subtypes

bull Subsets properties

The subsets mechanism in Sentences allows you to define a set of instances of an existing

type as a new type You cannot select instances to be members of a subset as subset

membership is defined by a condition that is implemented as a query You can create a

new instance which is a member of a subset by opening a create Dataform on a subset

type When you save the Dataform Sentences checks that subset instances created in this

way meet the conditions for the subset

The subset properties page includes command buttons for creating a new subset query or

for attaching an existing query to a subset definition Whenever a subset is used its

membership is determined by evaluating the condition against the membership of the

superset

You can use the subset mechanism for association types as well as entity types

A subset type has all the source and target behaviour of its superset type This means that

all association types that have the superset as their source or their target exist in the same

form for the subset A subset can be a subset of only one superset type A subset cannot

be the superset of another subset which means that Sentences does not allow subsets of

Properties


203

subsets Also a subset cannot behave as a subtype (see ldquoSupertypes properties pagerdquo ) If

subtype behaviour is required you must define the superset type as a subtype

Sentences displays the existing subsets for a type using an expandable tree display

To create a subset definition

1 Click Create to open a dialog box in which you can name the subset and then click

OK

2 Click Edit Query to open the Query Editor (see Chapter 7 ldquoSentences queriesrdquo) and

define the subset query The subset query can include a condition that restricts

membership of the subset to items that meet the condition If you do not create a subset

query all the members of the superset are members of the subset A subset that contains

all the members of its superset can be a useful tool in defining the appearance of a

Dataform (see ldquoDataform tabbed pages with subsets and supertypesrdquo )

3 Use the Query Editor to create a query and then attach it to a subset using the Attach

Query command (or the Attach Set Query command if available) on the Schema menu

Using the Attach Query command replaces any existing subset query There is also a

menu item to Detach Subset Query

The result of a subset query must be a set of instances of the same type as the superset

type For example a subset query to define the type Married Person as a subset of

Person must return a set of instances of the type Person

A subset query must always use the superset type as its root node You cannot use another

subset of the same superset type as the root node The subset query can be edited from the

Subset properties page Subset queries appear with other queries in the All Queries folder

of the schema pane and can be edited from there in the same way as any other query

(Subset set queries appear in the Subset Queries sub-folder under the Set queries folder

of the schema pane)

Sentences displays an expand button next to subset queries in the schema pane Clicking

the expand button displays details of the type to which the subset query applies

After you define the subset query the subset type appears with all the other defined types

in the All types folder of the schema pane The superset and subset are both marked as

such in the schema pane by the addition of the system associations has subset and

subset of Examples of the use of subsets and supertypes are given in Chapter 6

ldquoAdvanced techniquesrdquo

Comparison of subsets and supertypes

In general a supertype should be used when the relationship between the instances of the

type and the parent supertype is a permanent one As an example of a permanent

relationship consider a schema which defined the entity types domestic dogs wild dogs

and wolves as subtypes of a supertype called canines In this case the status of an entity

instance is unlikely to change

A subset relationship is suitable where the status of entity instance is likely to change As

an example of this consider a schema in which the entity type customers with overdue

accounts is defined as a subset of the entity type customers In this case it is expected

that an entity instancersquos membership of the subset customers with overdue accounts is

temporary

There are some relationships that are less easy to define as being either permanent or

temporary and these need to be considered on a case-by-case basis bearing in mind the

requirements of the Sentences application you are developing

The relationship between the entity types Employee and Person is an example of this

An Employee is clearly a Person but may be an Employee for as long as 40 years or

for as little as 4 weeks In a business application you may need to record significant

Properties


204

information for an Employee and for a former Employee but not for any other Person

It is possible that some individuals entered in the database as Persons may go on to

become Employees In these circumstances it is appropriate to create a schema in which

the Person entity type is a supertype of the Employee entity type This has been done in

the Human resources example application (see ldquoThe Human resources example

applicationrdquo )

Dataform behaviour with subsets and supertypes

There are important differences between the behaviour of Dataforms when using

supertypes and subsets For a description of the differences for the base Dataform see the

section ldquoDataform tabbed pages with subsets and supertypesrdquo 9

Where custom Dataforms have been defined a type and its supertypes may have different

custom Dataforms selected as their default Dataform However where subsets are used all

the subsets will use the default Dataform set for the base type For more information on

custom Dataforms see the sections ldquoCreating a custom Dataformrdquo and ldquoCustom

Dataforms with subsets and supertypesrdquo

Subsets of association types

You can define subsets of association types in the same way you define them for entity

types using the Subsets tabbed page of the Properties dialog

The name that you enter when you create the association subset is its verb name The

subset association type uses the same source and target types as its superset type

Subset association types are displayed in the Explorer schema pane with yellow arrows

Where a subset association type is the source of one or more further association types the

base dataform for the superset association type has an additional tabbed page named for

the subset association type to display those associations

Viewing subset type instances

When instances of subset types are displayed in the data pane of the Sentences Explorer

they are identical in appearance to the instances of any other types

If the subset includes all the instances of its superset then the list of instances displayed

for the subset and the superset is identical You must remember that such listings are not

duplicates They are the result of the same instance being valid for display as an instance

of a type and as an instance of a subset type

Properties


205

Supertypes properties page

Figure 5-22 The Supertypes properties page

Supertypes are one of the two mechanisms that allow multiple types in a database to share

common behaviour The other mechanism is Subsets

The supertype mechanism allows you to define a hierarchy of types with certain

associations common to more than one subtype Supertypes should be used when the

correspondence between a type and its parent is permanent and subsets should be used

where the correspondence is temporary

Association types sourced on supersets and supertypes are shared by the respective

subsets and subtypes

An entity type can be a subset or a supertype of another entity type and an association

type can be a subset or a supertype of another association type

Supersets and subtypes are created in the database schema and are stored in the schema

changes chapter Subset entity types are displayed in the Sentences Explorer schema pane

with yellow icons

The Supertypes properties page allows you to associate a type with another existing type

in a hierarchical relationship A type that is defined as a subtype implements all the source

and target behaviour of its supertype This means that all association types that have the

supertype as their source or their target exist in the same form for the subtype A type may

be a subtype of more than one Supertypes A subtype may be the supertype for further

subtypes

To define a supertype

1 Click the Addhellip button to select an existing type as the supertype

After you define the supertype the supertype and subtype are both marked as such in the

schema pane by the addition of the system associations supertype of and subtype of

Properties


206

You can create instances of a subtype directly These instances are also members ofthe set

of instances for the supertype

Using supertypes with association types

You can define supertypes for association types as well as for entity types

Both the source and the target of the subordinate association type must be either the same

as or a subtype of or a subset of or a subset of a subtype of the source or target

respectively of the supertype association type

Examples of the use of subsets and supertypes are given in Chapter 6 ldquoAdvanced

techniquesrdquo

Equivalence properties page

You can use the Equivalence properties page to define two or more types as the same

This can be useful if you wish to merge databases and for example one database uses a

type named Clients and the other uses a type named Customers The types being linked

in this way must either be both association types or both entity types If they are value

types (entity types with defined datatypes) they must both have the same datatype

If you wish to make two association types equivalent they must share the same source and

the same target

The result of creating an equivalence between two types is similar to the result of creating

a supertype-subtype link between two types Instances of each of the two types share all

the associations of both types A Dataform display for either type or any instance of either

type shows a page for each of the equivalent types

To make two types equivalent

1 Open the Equivalence page of the Properties dialog for one type and click Add

2 Select the equivalent type from the picker list

To cancel an equivalence highlight the equivalent type and click Remove

You can also define equivalent instances (see ldquoInstance equivalencerdquo )

Triggers properties page

Figure 5-24 The Triggers properties page

Properties


207

Triggers are elements of custom Java classes and methods that users can add to

Sentences A trigger generally performs an action in the database whenever a specified

action called a trigger event takes place

You can view a list of available triggers by selecting Triggers from the View menu To

use a trigger you must write your own Java code compile the code into a Java archive

(JAR) file and place the JAR file in the directory listed in the TriggerPath property in

the Serverproperties file You can then use the Triggers properties page to assign the

trigger to a particular entity or association type The detailed steps for attaching a trigger

to an entity or association type and how to edit trigger assignments are given in the

section ldquoAttaching a triggerrdquo

There are examples of how triggers may be used in Chapter 11 ldquoWorked examplesrdquo

Description properties page

Figure 5-25 The Description properties page

The Description properties page allows you to add a free text description to any entity or

association type

Properties


208

Custom Dataform properties page

Figure 5-26 The Custom Dataform properties page

You can use the Query Editor to design a custom Dataform (see ldquoCreating a custom

Dataformrdquo ) You can use the Custom Dataform properties page to delete or rename an

existing custom Dataform and to create a new custom Dataform

Sentences displays the existing custom Dataforms for a type using an expandable tree

display

When you create a custom Dataform you can either attach an existing query or launch the

Query Editor to create a new query

You can also choose which Dataform should be used as the default Dataform for the type

Properties


209

State Domains properties page

Figure 5-27 The State Domains properties page

This property page is used to view and edit the tree of User and System State Domains for

this Type By default only System and Inherited Domains that are in use are displayed

You can select the Inherited and System checkboxes to include all Domains in the tree

See ldquoBusiness Rulesrdquo for details of Business Rule and State Domain functionality

Business Rules properties page

Figure 5-28a The Business Rules properties page

This property page is used to view and edit the list of Business for this Type See

ldquoBusiness Rulesrdquo for details of Business Rule and State Domain functionality

Properties


210

Diagram Images properties page

Figure 5-28b The Diagram Images properties page

You can use these properties to specify how this Type will appear on Sentences Diagrams

by default

The available options are

bull Image Image link

You can specify either an image from the available images on the server or a URL that

specifies an image accessible from the Sentences client

bull Use default images

If you select to use default images the images specified in the ldquoPresentation Propertiesrdquo

will be used in preference to the images specified above

bull Text and Image

You can specify whether to display just text just an image or both If you choose both

then you can also specify whether to align the Text at the top bottom left or right of the

image

bull Hide border

You can specify whether to display a border around the diagram item or not by selecting

or deselecting Hide border

bull Background Colour

You can specify use of the default colour (the Sentences system colous) a transparent

background or a specific colour Click on the Change colourhellip button to select a custom

colour

Properties


211

Default Sorting properties page

The Default Sorting properties allows you to set how the Type will be sorted by default

when used in a Dataform or Custom Dataform

Sorting can use any of the nodes that will be available in the query used to display the

base Dataform You can have multiple sort nodes with different sort directions

Properties


212

Dataform (Navigation) properties page

Figure 5-28c The Dataform properties page

You can set the following properties on this dialog for both navigation to the target and

navigation to the source (if included on a dataform in the inverse direction) Only the

forward direction is described here but the same behaviour and rules apply to both

directions and can be set independently from one another

Can select lttargetgt checkbox

Select this property to allow users to select a target instance from an appropriate list of

instances

Can create lttargetgt checkbox

Select this property to allow users to create a target instance of the appropriate type

Navigation

Select the navigation behaviour for links from the target field The options are

Prohibited Default Dataform or where a custom Dataforms exists for the target type a

Specific custom Dataform

If no custom Dataforms exist for the target type a message is displayed on the dialog as

illustrated in Figure 5-28c

If navigation is Prohibited you cannot open a child dataform for an existing target

instance although you may be able to create a new child instance if the Can create

lttargetgt checkbox is selected

lttargetgt Dataform is read only checkbox

If the Dataform for the target instance is read only you may view the target Dataform but

not alter any of the fields on it

If navigation is Prohibited this option is not available

Interaction between properties

If the Navigation property is set to Prohibited then the lttargetgt Dataform is read only

checkbox is unavailable

If the association type is read only or has a derivation that is not editable (see ldquoDerivation

propertiesrdquo ) then neither the Can select lttargetgtcheckbox nor the Can create lttargetgt

checkbox is available

Properties


213

Dataform Filter properties page

AssociationTypes that are presented as a column in a table can be used as a filter when

the target is an Entity Type

The default filter can be either a specific instance or an expression

This peoperty is used as the default when creating a base or Custom Dataform that

includes the Association Type For more information see ldquoFiltering Dataform Tablesrdquo

Retrieval Methods properties page

EntityTypes only have one retrieval property

bull Determine if child associations are present

For very large databases and for Dynamic LazyView databases it is an expensive

operation to fetch not just the instances but also to check whether they have any child

associations This property can be unchecked to improve performance when knowledge of

whether the instances have children is unimportant When unchecked instance appear

with a plus sign and only when they are expanded are the children fetched If there are no

children then the plus sign is removed to indicate no child associations

Association Type properties page

Figure 5-29 The association type properties page

Properties


214

The association type properties page resembles Create Association Type dialog You can

change the properties you set when you created the association type

Changing the properties of an association type may affect the properties appearance or

visibility of association instances based on it For example changing the cardinality of an

association type from Singular to Multiple allows you to use a list input field instead of a

single line input

If you change the cardinality of an association type from Multiple to Singular after

creating multiple associations for a source entity only the last association you created can

be seen in the Dataform All the created associations remain visible in the Explorer data

pane

If you change the cardinality of an association type you should always click OK on the

Association Type properties page before you make any other changes on any of the

other tabbed pages in this dialog

For more details on association type properties please see the section ldquoCreating

association typesrdquo

Target Parameters properties page

Figure 5-30 The Target Parameters properties page

The Target Parameters properties page allows you to restrict the targets for an

association type This properties page is not displayed on an entity type properties dialog

This mechanism is only available when the target of an association type is a subset

This properties page displays a list of the possible common source associations You can

define the association from which the target for the current association type may be

chosen

For an explanation of the use of Target Parameters see ldquoTarget parametersrdquo

Properties


215

Derived target properties page

Figure 5-31a The derived target properties page - default instance

Figure 5-31b The derived target properties page - derived expression

Properties


216

The Derived target properties page is available for association types only

As an aid to data entry you can define a default or derived target for an association type

When you open a create Dataform any default targets defined for the associations on that

Dataform are displayed If the target is derived then the target may be subsequently re-

calculated

This property page combines two previous mechanisms used in Custom Dataforms for

deriving a target if none already exists when the dataform is saved or always The

simpler mechanism simply specifies an existing instance to use

On a Custom Dataform there is an additional property to make the field read-only which

does not apply to the schema properties The derived target definition set for this

Association Type will be used as the default if it is used in a Custom Dataform Query

The derived target setting may be none an instance or an expression

bull Instance

Select an instance of the target type

bull Expression

Enter a valid expression The expression is validated in the context of the query that will

be generated to make the base dataform This means that other nodes can be referenced

For further information on expressions (see ldquoUsing expressions in queriesrdquo )

If the schema subsequently changes such that the expression is invalid then no target will

be derived until the expression is updated to reflect those schema changes


Figure 5-32 The Retrieval Methods property page for Entity Types and Association Types

The Retrieval Methods properties page allows you to specify two things

For Entity Type and Association types you can specify whether the server should try to

determine whether child associations are present (usually indicated by a plus sign to show

that the instance has children)

For Association Types only you can specify the way in which association instances are

retrieved from the database These settings can influence server response times

These properties determine the default behaviour when an association type is selected in

the schema pane and when a folder is expanded in the data pane You can override this

Properties


217

default behaviour by selecting a different option from the association type shortcut menu

or the View menu The shortcut menu is also available on data pane folders for multiple

instances You can define different settings for forward and inverse instances


bull By source (forward associations) By target (inverse associations) (default)

When you select the association type in the schema pane Sentences finds all the instances

of the source or target type and then searches for associations This option provides a

good response where most source or target instances have associations If only a few

source or target instances have associations this option can provide a slow response

bull Sorted

When you select the association type in the schema pane Sentences finds all suitable

instances of the association type and then sorts them by their source or target type and

displays the first 50 instances If there are a large number of associations this can be very

slow If there are a large number of source or target instances but only a small number of

associations this option can provide the fastest response

bull Unsorted

When you select the association type in the schema pane Sentences finds the first 50

suitable instances of the association type and displays them without sorting This option

can be used to display a sample of the available associations relatively quickly or where

neither of the other options provides a good response








Operations on instances

There are a number of operations that can be carried out directly on instances in the data

pane of the Sentences Explorer

These operations allow you to make one instance supersede another and to define one

instance as the equivalent of another It is also possible to create an association type

which has an instance rather than a type as its source

Properties


218

Supersedes

Figure 5-33 The supersedes dialog in the data pane

You can replace an instance with another instance of the same type using the supersedes

command Both instances must exist in the database before you use this command After

using this command the instance that has been superseded no longer exists in the

database

Supersedes is not available for value instances

To supersede one instance by another follow these steps

1 Highlight the instance to be superseded and select Superseded by from the shortcut

menu Sentences displays the Superseded by dialog box for the instance

2 Select the name of the superseding instance from the picker list and click OK

Sentences displays the Impact of supersession dialog listing the associations in which

the instance being superseded is involved

3 Click Supersede to continue or click Close to cancel the supersedes action

When you use Supersedes with a singular association type you may create a situation in

which a singular association has multiple instances If this occurs Sentences displays an

error message when you open the Dataform To remedy this error you must view the

association in the Sentences Explorer and delete the additional instances that are no

longer required When you use Supersedes with a multiple association type the lists of

associations from the superseding and superseded associations are merged

After a supersedes action the original instance no longer exists in the database in contrast

to instance equivalence where both equivalent instances persist in the database A

Supersedes action cannot be undone

Instance equivalence

You can define two entity or two association instances as being equivalent For example

you can make the instance International Business Machines equivalent to the instance

IBM The instances must be of the same or equivalent entity type or association type but

Properties


219

may be from different data chapters Equivalent instances have identical behaviour that is

all the associations of either instance are displayed as associations of both

Equivalent instances are displayed in the Explorer data pane in an instance subfolder

labelled equivalent to Instance

Where an instance is equivalent to more than one other instance then the same behaviour

is displayed by all the equivalent instances

Equivalent instances persist in the database in contrast to superseded instances which do

not Equivalence is not available for value instances

To make one instance equivalent to another follow these steps

1 Highlight an instance that you wish to make equivalent and select Equivalents from

the shortcut menu Sentences displays the Instances equivalent to dialog box for the

instance If any equivalent instances are already defined they are displayed in the list box

2 Click Add to display a picker showing suitable instances (instances of the same or of

an equivalent type) select an instance and click OK Repeat this step if necessary to

make more instances equivalent to the selected instance

3 Click OK to close the dialog

The following table lists the buttons on the Instances equivalent to dialog box and their

meanings

Button Action

Add Displays a picker so that you can select an existing

instance to be added to the list

Remove

Removes a selected instance from the list

(The selected instance is no longer equivalent to any of

the other instances shown)

Remove All

Clears the list This has the same effect as using the

Remove button on the current instance in the dialog for

another instance

OK Implements the selected changes and closes the

dialog

Cancel Discards the selected changes and closes the dialog

You can also define equivalent types (see ldquoEquivalence properties pagerdquo)

Instance-specific association types

If you select an existing entity instance or association instance as the source of an

association type that association type applies only to that instance This allows you to add

information that is specific to a particular instance

For example in a customer relationship management system you may wish to record the

golf handicap of only one customer You can do this in Sentences by adding an instance-

specific association type for example Bill Smith golf handicap golf handicap This

association type does not exist for other customers in your database


of the same type you can change the associationrsquos source to the type for example to

Customer golf handicap golf handicap When you make this change Sentences

preserves the original data you entered

The Dataform for an instance that has instance-specific association types includes an

additional tabbed page for the instance-specific associations The title of the tab is the

name of the instance

Business rules


220

To create an instance-specific association type highlight an instance in the explorer data

pane and select Create Association Type from the shortcut menu or click the Create

Association Type button on the Toolbar

Business rules

Version 40 of Sentences introduces Business Rules

Introduction

You may define State Domains for Sentences Types Each of these Domains has a set of

States that instances of the Type can exist in together with an assumed ldquoundefinedrdquo State

The way an instances State is determined is defined in a special Query called a Predicate

Query You can define rules stimulated by changes in State that either prohibit the change

or effect further changes mandated by them

There are two sorts of change those that alter an instance from a specified state to its new

state and those that alter an instance to its new state without regard for its prior state In

the latter case there must have been some change so all we can say is that the prior state

was not previously the ldquotordquo state

change = [state to] state

Sentences utilises two kinds of Business Rule State Rules and Change Rules A State

Rule prohibits a change

state rule =

ltchangegt prohibited

[when [not] state and | or [not] state] | Always]

The rule is created to stop a particular change from happening in specified situations

A Change Rule detects when a particular change has occurred and mandates further

changes

change rule =

ltchangegt mandates ltchange actiongt [ ltchange actiongt]

[when [not] state and | or [not] state] | Always

The changes you may wish to action are as follows

Create instance(s)

Delete instance(s)

Change association target(s)

Display a message to the user

Send a simple email

Fire a Sentences Trigger

Request that an instance changes to a specified state

Sentences V40 introduces new functionality to queries to facilitate such actions Queries

that include these actions must do so in the context of a Transaction For Business Rules

such queries are called Effector Queries

Business rules


221

Independently from Change Rules you may define an Effector Query and specify that it

will be executed when an instance changes to a given State When you create a Change

Rule you specify the change actions by specifying one or more States If the Change Rule

is stimulated then the Effector Queries of each mandated state are executed

System state domains

As well as user-defined Domains Sentences has built-in System State Domains These

allow you to define Business Rules and Effectors that are stimulated by changes managed

by the Sentences Database For example when an instance of a type comes into existence

the instances System Domain Existence changes to the System State of

ExistenceExistent You could use this state change to stimulate a Business Rule that

performs further actions when instances of that type are created

The full set of System State Domains is as follows

Domain State Cause Applies

Attributes Changed The attributes of an instance have been changed

ETs ATs

Equivalents EquivalentsAdded An instance has been made equivalent to another instance

ETs ATs

EquivalentsRemoved An instance has been made no longer equivalent to other instances

ETs ATs

Existence Nonexistent An instance has been deleted

ETs ATs

Existent An instance has been created

ETs ATs

Superseded An instance has been superseded by another instance

ETs ATs

Name Renamed An entity instance has been renamed

ETs

Sequence Resequenced An association instance has been moved within a sequence

ATs

Target Changed The target of an association instance has been changed

ATs

Uniqueness Violated An instance has been duplicated

ETs ATs

You must also be aware of timing issues when these state changes will be recognised

Once an instance has been deleted or superseded it is no longer visible even in the

context of the transaction that deleted or superseded it For this reason the

ExistenceNonexistent and ExistenceSuperseded states stimulate rules and fire their

Effector Queries just prior to them being deleted or superseded so that the effector

queries still have visibility of the instance in question

Domains and states

You may define any number of Domains for each Entity Type or Association Type

Types inherit Domains and their States from their supertypes and supersets Each Domain

can have any number of States States must have unique names within any Domain

Naming

Business rules


222

You cannot name a Domain with one of the System Domain names Duplicate Domain

names are not allowed on any one type but unrelated types can have Domains of the

same name

Generally for readability when naming Domains and States domain names should be

nouns and state names should be adjectives

The undefined state

The Undefined State is a ldquocatch allrdquo that is automatically included in all Domains It is the

state that is returned if none of the other states are valid

The Undefined State can be renamed to better reflect the Domain For example if you

have a Domain Archival with only two possible states of Ready and Pending you can

add the State Ready which you can define using an expression and rename the Undefined

State to Pending Anything that is not evaluated as Ready will have the state Pending

Viewing a types state domains

To view the State Domains for a type follow these steps

1 In the Sentences Explorer select the type that you wish to view the Domains for

in the Schema Pane and open its properties by Selecting Properties hellip from the

Edit menu

2 The Properties dialog will open Select the State Domains tab

3 The tab shows a list of all user-defined domains for that type

4 By default it will also include any inherited domains and the system domains

You may hide these domains by deselecting the Inherited and System

checkboxes on the page Inherited Domains can only be edited from the type that

they belong to

State Domains that are visible will also appear on the base Dataform

To change whether a State Domain is visible on a Dataform follow these steps

1 In the Sentences Explorer open the properies of the Type with the State Domain

and select the State Domains tab

2 Select the State Domain Node and open itrsquos pop-up menu

3 Select either ldquoSet hidden on dataformsrdquo or ldquoSet visible on dataformsrdquo

depending upon the current visibility

The same property determines whether each instance state is included in the data pane

If you are displaying State Domains in the Schema Pane then this menu option is also

available from the Schema menu in the Sentences Explorer See the ldquoUser Preferencesrdquo

section for how to change whether State Domains are displayed in the Schema Pane

Creating a state domain

To create a State Domain follow these steps

1 From the State Domains tab of the types Properties select the Create State

Domain button to open a Create State Domain Dialog

2 Enter the name of the new Domain you wish to create and select OK

3 The new Domain will be created and added to the list A blank Predicate Query

and the Undefined ldquocatch allrdquo State are also created for the new Domain

Creating states

To create one or more States for a Domain follow these steps

Business rules


223

1 From the State Domains tab of the types Properties select the State Domain that

you wish to add a State to and select the Create State button to open a Create

State Dialog

2 Enter the name of the new State you wish to create and press Enter or Select

OK The Create State Dialog does not close

3 You can enter several States by typing in the names and pressing Enter

4 When you have finished adding States select Close to close the Create State

Dialog

Editing the predicate query to define states

The Predicate Query attached to each user-defined Domain is a specialised query for the

purpose of defining how Sentences determines which state an instance of that type is in

States are not set They are transient and are interpreted at a moment in time by their

Domains Predicate Query

You cannot delete a Domains Predicate Query and it does not appear in the list of

standard queries in the Sentences Explorer

To edit a predicate query follow these steps


you wish to edit and select the Edit Query button to open a Request Query

Editor

2 If you have not edited the Predicate Query before then it will contain a data

request node for the type a domain definition request node and the undefined

state definition

3 For each State you may add a state definition request node and define its

expression such that when evaluated it will indicate whether each instance has

that State

4 To add individual states select Add State from the context menu of the domain

definition node and then the desired state from the child menu

5 To add all state definition nodes for all the states not already added select Add

all State Definition Nodes from the context menu of the domain definition node

6 The expressions entered will depend on your needs In the example below we

are concerned with an employee bonus scheme and the state of an individual

Employee

Business rules


224

The states are not necessarily mutually exclusive Ideally they would be but this is not

always practical

In the above Predicate Query the Validity can be both Close to retirement age and Invalid

at the same time In this case it is the order of the predicate expressions that determines

the state If none of these conditional statements evaluate to true then the ldquocatch allrdquo state

of Undefined becomes the instances State for the Validity Domain In this example it has

been renamed to Invalid to be more meaningful than Undefined

State Domain Analysis

When designing the State Domain and its predicate query on an existing set of data it is

useful to be able to see what the current states are There is a tool to perform this in the

Query Editor

To analyse the instances for a State Domain follow these steps

1 When editing the State Domain predicate query select the State Domain

Analysis menu item from the Tools top level menu

2 The Schema tab on the right hand side will display a panel showing the progress

and then results of the analysis This may take some time depending upon the

volume of data

3 You can select the Copy Details button to copy this summary to the clipboard

4 You can use the List button against each state count to list the individual

instances in the results pane

5 You can use the Query button against each state count to open a new query that

will return only instances with that state This is inteded to be used to manipulate

those instances For example to find all the invalid instances and perform actions

on them to make them valid Note that the predicate query must be saved before

the generated query will produce the correct results

Business rules


225

Using states in regular queries and dataforms

An instances state can be obtained in a regular query in two ways You may add a state

request node or use the GetState function in an expression

To add a State Request Node follow these steps

1 Select the Node you wish to request the State for From the context menu select

Add and then Stateshellip

2 In the dialog that opens select one or more Domain that you wish to request the

State of

3 The State Request Nodes will be added to the query node

The GetState Function for use in Query Expressions takes two parameters The first

parameter is a reference to the node for which the state is required The second parameter

should resolve to the name of the Domain for which the state is required

Note that only one state will be returned per instance If several of the State definition

expressions evaluate to true then the first one will be returned so the order of the State

definitions is important Only if none of the state definition expressions evaluate to true

will the Undefined State be returned

If a State request is included in the query that defines a Custom Dataform then the state

will be displayed as a read-only field on the dataform

Business rules


226

If the state request is bound to an instance and a Button Text attribute is specified then

the state will be represented as a button Clicking the button will fire the effecters for that

state on the dataform instance

Effector queries

Effector Queries like Predicate Queries are extensions to the standard Sentences Queries

They do not appear in the list of regular queries as their use is very specific to Business

Rules functionality

An Effector Query is a special kind of Update Query which has the ability to modify data

Its execution is intended to effect one or more changes By attaching an Effector Query to

a State you are instructing Sentences to execute the query when an instance changes to

that state In a Change Rule when you specify a State as mandated by a change you are

instructing Sentences to execute all the Effector Queries attached to that state for the

given instance

In a Change Rule the inference is that you desire one change to lead to a particular state

but this does not mean that the instance will necessarily gain that particular state or that an

Effector Query will bring about that state

Sentences V40 introduces Sandbox Modes that can be used when creating and testing

Update Queries or Effector Queries This allows you to try your Query explore and check

the results and then revert to the state the database was in before execution In this way

you can experiment without fear of corrupting your data See the section on Sandbox

Modes for details

Because an Effector Query can modify data those changes may lead to further state

changes and thus further Effector Queries being executed in the transaction

Effector query parameters

Effector queries have three built-in parameters that are populated depending upon the

kind of change that led to their execution

bull update_subject

The update_subject is populated with the instance that has been affected For

example the new instance the instance about to be deleted the instance that has been

renamed the association that has had its target changed and so on

bull update_old_name

For the special situation where an entity has been renamed it may be useful to know the

name before it was renamed The update_old_name is populated with the old name

bull update_old_target

For the special situation where an association has its target changed it may be useful to

know what the old target is The update_old_target is populated with this old target

Business rules


227

Creating an effector query

To create a new Effector Query follow these steps

1 From the State Domains tab of the types Properties select the State that you

wish to add an Effector Query to and select the Add an Effector Query button

A new blank Effector Query will be created and opened in a Query Editor for

you to define

By default the query will be based on the Domains type with a Data Request

renamed to ldquoupdate_subjectrdquo so that it is bound to the parameter of the same

name

2 You can now construct the query to include relevant data and action the changes

you desire See the next sections for each kind of change Select the Save toolbar

button and close the Query Editor once you are finished

3 The name of the query will be derived from the domain and state that you are

creating it for but you are free to rename it from the State Domains tab of the

types Properties Select the query you wish to rename and select the Rename

button or press F2

An Effector query has the same functionality as an Update Query For details of Update

Query abilities see the ldquoUpdate Queriesrdquo section

Effector triggers

Sentences Triggers provide the maximum possible flexibility when manipulating data and

were the only available mechanism to do so prior to Version 40

As well as executing one or more Effector Query when a State is mandated you may also

fire one or more Sentences Trigger

Prior to Version 40 when a trigger is fired it is passed an update object that contains

details of what was changed and why If a trigger is fired in this way then this information

is included

Creating an effector trigger

To create a new Effector Trigger follow these steps


wish to add an Effector Trigger to and select the Add an Effector Trigger

button The Add Effector Trigger dialog showing the available triggers will be

opened

2 Type in all or part of the trigger name to filter the list of available triggers

3 Select the desired trigger and click the Add button

4 Select another trigger or Close when done

Business rules

Business Rules allow you to define the behaviour of your application without the need for

specialist programming knowledge Once you have designed and created your State

Domains to define the states that your application entities may exist in you can use

Business Rules to prohibit undesirable behaviour and mandate desired actions when

suitably stimulated

Creating a state rule

You may use State rules to prevent undesirable behaviour

To create a State Rule follow these steps

Business rules


228

1 From the Business Rules tab of the types Properties select the Create State

Rule button A New State Rule dialog will open

2 Define the change that will be prohibited You may optionally specify the

starting state You must specify the final state

3 You may enter a name for the rule or once you have chosen From and To states

selecting the Default button will generate an appropriate name

4 Select Always to specify that the change will always be prohibited

OR

5 Select When to specify how the change will be prohibited You must enter the

condition that needs to be fulfilled for the change to be prohibited

In the example below when a Projects Name System Domain changes to the Renamed

state then that renaming is prohibited only when the instances user defined Cycle

Domain is in the Closed or Progressing states

Creating a change rule

You may use Change rules to define mandated changes as a result of suitable stimulus

To create a Change Rule follow these steps

1 From the Business Rules tab of the types Properties select the Create Change

Rule button A New Change Rule dialog will open

2 Define the change that will stimulate this rule You may optionally specify the




4 Select one or more States to be mandated You may add as many States to the

selected list as required Each will have their effector queries executed when this

rule is fired

Business rules


229

States with a red background do not have any associated Effector Queries or

Effector Triggers As such they will not affect anything You are not stopped

from adding these as you may later add effectors to them

5 Select Always to specify that the change will always mandate these states

OR

6 Select From to specify under which conditions the states will be mandated You

must enter the condition that needs to be fulfilled

The From State

When a User Defined State change triggers a business rule there are several ways to

determine if a change has taken place If you specify a specific change from state and a

different change to state then it is obvious to the system how to act You may wish to

trigger a rule to fire whenever an instance ends up in a state such as invalid regardless of

its initial state even if it started in that state You may wish to trigger a rule even if there

was no previous state before the transaction started (because the instance did not exist)

Because of this there are four predefined Change From states that you can use to

indicate the desired behaviour

bull ltAny Stategt triggers the rule when the initial state is any state including the change to

state including no previous state Any instances already in the change to state will be

triggered

bull ltAny Other Stategt triggers the rule when the initial state is any state except the

change to state including no previous state Any instances already in the change to state

will not be triggered

bull ltAny Existing Stategt triggers the rule when the initial state is any state including the

change to state except for no previous state Any instances already in the change to

state will be triggered

bull ltAny Other Existing Stategt triggers the rule when the initial state is any state except

for the change to state or no previous state Any instances already in the change to state


Business rules


230

Disabling individual rules

All Business Rules or individual Business Rules can be enabled or disabled in the

properties for that Type

Business rules reference


administrators

Business rules parameters in the Serverproperties file

The following parameters in the Serverproperties file are used by Business Rules

bull MaxConcurrentEffectorMessages

You may use this property to specify the maximum number of Messages generated by an

Effector Query before we curtail reporting to the client (to avoid overwhelming the client)

bull MaxConcurrentEffectorSMTPEmails

You may use this property to specify the maximum number of Simple Emails generated

by an Effector Query

bull BusinessRulesDisabled

You may use this property to disable the Business Rules functionality By default

Business Rules are not disabled

bull MailSMTPHost

The MailSMTPHost property must be specified in order to send simple emails from

Effector Queries If the server requires authentication then you will also need to provide

details

bull MailSMTPUser

bull MailSMTPPassword

bull NotifyUserOfSMTPMailFailures

If the simple email SMTP details are not set up or fail for another reason the user will be

informed This property is true by default You may use this property to stop such

information being displayed by setting it to false

bull MailSMTPValidFromList

Business rules


231

As it will be an application rather than an individual that is sending the email one or more

such ldquonoreplyrdquo accounts will need to be set up for this use This property can be set to a

list of accounts that you wish to allow the users to send email from Multiple addresses

are separated by semi-colons

Browsing state domains


the State Domains in your Schema at once You can also use the position and filter tools

to narrow your search

The State Domains Schema Folder is displayed according to your User Preferences See

the section on User Preferences for details

Browsing business rules


the Business Rules in your Schema at once You can also use the position and filter tools


The Sentences Dataform


232

The Business Rules Schema Folder is displayed according to your User Preferences See



The Sentences Dataform is a dynamically generated data viewing and data entry window

In the Sentences client all entity value and association instances are created using a

Dataform

You can open a Dataform either on an association or entity type to create new instances

and optionally create the associations for those instances (see ldquoThe create Dataformrdquo ) or

on an association or entity instance to edit or update the associations for that instance (see

ldquoThe update Dataformrdquo )

The base Dataform for an entity or an association displays associations which have that

entity or association type as their source Each association is represented by a labelled

field The field label is the same as the verb of the association type and the field itself

allows you to view or define a target Each target defined in the Dataform represents an

association instance

If you defined an association type as singular then the Dataform field for that type only

allows a single entry If you defined an association type as multiple then the Dataform

field for that type allows multiple entries You can control the display of Dataform fields

using the Properties dialog or panel for each entity and association type as described in

the section ldquoPropertiesrdquo

Dataform Layout Systems

There are two systems for laying out fields in dataforms Page Layout and Section

Layout The original Page Layout system has been replaced with the more flexible and

sophisticated Sections Layout system The Section Layout system is the default but can be

changed by setting a server property See the Server properties section for details

Dataform Page Layout System

The original Dataform Page Layout System for dataforms uses a single column of fields

on multiple tabbed pages Tabbed pages are automatically generated according to the

schema structure Different supertypes subsets equivalent types and schema groups



233

The order in which the fields are displayed in the Dataform depends on the order in which

they appear in the schema pane If there are any association types sourced on instances of

a type the instances are displayed on their own tabbed pages as well

For further information see ldquoDataform tabbed pages with subsets and supertypesrdquo

Dataform Section Layout System

The Dataform Section Layout system uses a separate structure of Sections to define the

layout of forward and inverse Association Types and State Domains For a Custom

Dataform Derived Types can also be included in Sections

Each Section can be a logical grouping of fields but can also define presentation

attributes A Section can represent a tabbed page a bordered panel or allow the designer

to place multiple columns of fields on one dataform These Sections can themselves be

added to other Sections and so sophisticated dataform layouts can be defined

Each Entity Type and Association Type has an associated set of Sections that define the

default (base) layout for Association Types sourced on it To organise the child

Association Types and Sections select Organise Dataform Sections from the Schema

menu

The organiser dialog allows you to move child schema around create delete and modify

sections and alter some of the dataform presentation attributes common to the standard

schema properties For example whether an inverse association should be visible on

dataforms by default Hidden Association Types are shown in grey

Unlike the Page Layout System the inclusion and location of inverse associations and

State Domains can be defined

The Sections have attributes to affect the way that these children are displayed in-line

new-line or tabs There are attributes to give the section a border a title some

introductory text or footer text and how to fill the available space The title attribute is

used for a bordered panel and tabs If no title is set for a tab then the section name is used

as a default If no title is given for a bordered panel then the panel simply has a plain

border

Schema Section defaults are generated when schema is created and modified

1 When an ET or Subset is created no sections are generated



234

2 When an AT is created then both the source and target have Sections added (if

not already there) and then the AT is included (forwards for the source and

inverse for the target) Inverse ATs are still hidden by default Note they appear

greyed out in the Section Organiser

3 When a State Domain is created a section is added to the owning Type (if not

already there) and the domain is included in that section

4 When an AT changes its Schema Group (including being included in a group for

the first time and including being removed from all Groups) then the AT is

removed from the previous Section and included in the new Section Any

required new Section will be created (with the Group name or SourceTarget

name) If a Section is now empty after the AT is removed then the Section is

deleted

5 When an AT is deleted then it is automatically removed from the source and

target Sections created in item 2 If a Section is now empty after the AT is

removed then the Section is deleted

6 If a Type is renamed then if it has an existing Section with the old name it is

renamed to match

7 If a Schema Group is renamed then if it has an existing Section with the old

name it is renamed to match

8 If a Schema Group is deleted then the contents are moved to the appropriate type

Section (if available) If the Section for the Schema Group is empty then it is

also removed

9 If an AT has its source or target changed then any Sections for the old

sourcetarget have the AT removed and if now empty the sections are removed

The new AT is included in the new relevant Section creating a new Section if

needed

The default Schema Sections created for types will be formatted as Tab Pages that will fill

the available space vertically and horizontally by default For an Association Type that is

to be represented as a Table for Associations the default Section will be an in-line

section

In the Sentences Explorer a new schema menu item View Base Dataform Query

opens up the Query Editor with the request that is generated from the Dataform Section

metaschema This query can be saved as the starting point for a Custom Dataform

This includes the second-level requests required for tables and nested panels

Dataform Field Formatting

The way fields are displayed in the Dataform is defined in the properties for the

association type concerned For example an association that has been defined as multiple

has by default a list-box display in the Dataform

Mandatory association types are marked with an asterisk () on the Dataform You cannot

save a Dataform unless you supply a value for every mandatory association

If a dataform contains fields which are calculated then it will automatically refresh these

calculations whenever a field is changed by default This ldquoauto-refreshrdquo function can be


For the Section Layout system there is an additional attribute for Association Types and

State Requests The Label positioning of Top Left or None can be specified



235

The base Dataform and the default Dataform

Sentences can always create a Dataform which automatically displays all the associations

belonging to a particular source type This is known as the base Dataform State

Domains that are viusible will also appear on the base Dataform











You can use the Query Editor to design and save a custom Dataform that may only

display a selection of the available associations or inverse associations For information

see ldquoCreating a custom Dataformrdquo

You may define either the base Dataform or a custom Dataform as the default Dataform

for a source type

Sentences displays the default Dataform whenever you select the Dataform for a type

either from the Explorer or from another Dataform If you do not define a default

Dataform Sentences uses the base Dataform

To define a Dataform as the default Dataform follow these steps

1 In the Sentences Explorer highlight the entity or association type

2 Select Properties from the shortcut menu or click the Properties button on the Toolbar

3 Select the Custom Dataforms tab

4 Highlight the Dataform that you want to use as the default and click Set as Default

Create and update Dataforms

You can open a Dataform on a source entity type and use it to create new associations

This is known as a create Dataform You can also open a Dataform on any source type

or instance which can be used to update existing associations This is known as an update

Dataform

The create Dataform

You can display a create Dataform from the shortcut menu on an entity type in the

schema pane or by highlighting an entity type and clicking the Dataform button on the

toolbar An example of a create Dataform is shown in Figure 5-34 If you open a create

Dataform on a subset entity type Sentences displays the create Dataform for the subsetrsquos

superset type

Create Dataforms always show the words New xxx in their title bar (where xxx is the

name of the entity type) You can use this Dataform to create an entity and its

associations and optionally create new entities to be the targets for its associations all in

one operation



236

Figure 5-34 A Create Dataform

The first field on the Dataform has the name of the entity type as its label Type in the

name of the new entity you want to create in this field

You can type in new names in other fields to create additional new entities as targets of

the associations shown on the Dataform as long as those new names are valid for the

target type Alternatively you can select the association targets from existing instances of

the appropriate type

Some of the association target fields on the create Dataform include an ellipsis button

which you can click to display a picker list showing the existing instances If the display

format of the association target field does not include an ellipsis button you can right-

click on the field and choose the Select Existing Instance command from the shortcut

menu

The buttons on a parent create Dataform are Save amp Reset which updates the Dataform

contents to the database and displays a new blank Dataform Save amp Edit which updates

the Dataform contents to the database and allows you to continue to update the same

Dataform and Close which closes the Dataform If you make changes to the Dataform

the label for this button changes to Cancel

Selecting Cancel closes the Dataform without updating the database Sentences displays a

warning message that any new information in the Dataform is not saved A child

Dataform has an Apply command button which temporarily saves the Dataform contents

and allows you to continue to update the same Dataform and an Apply amp Reset button

which allows you to add additional child associations before returning to the parent

dataform Changes made on a child Dataform are only saved to the Sentences database

when you select a Save button on the parent Dataform from which it was called (see

ldquoParent Dataforms and child Dataformsrdquo)

When you open a create Dataform that includes any association type defined as

mandatory you cannot save the Dataform if you do not supply a target for that association

The update Dataform

The update Dataform is displayed when you select Dataform from the shortcut menu on

an entity or association instance in the data pane An example of an update Dataform is

shown in Figure 5-35



237

Figure 5-35 An entity instance update Dataform

When you open a Dataform on an entity instance the name of the entity is shown as the

first field in the window The only shortcut menu options for that field are Rename and

in the case of a Hyperlink Follow Hyperlink When you open a Dataform on an

association instance the identifying source verb and target of the subject are shown in the

window title bar

You can use the Dataform to rename the entity that appears in the first Dataform field

This field has the entity type name as its label To change the name of an entity select

Rename from the shortcut menu on this field

The Rename command is not available for value instances To change a value instance

either select a different instance from the picker list or delete the current instance and type

in a new one

Some association target fields on the update Dataform include an ellipsis button which

allows you to choose an existing entity as the target for each association Alternatively

you can create a new target entity by typing in a valid value (depending on the datatype

selected for this entity type)

The buttons on the update Dataform are Save (or Apply on a child Dataform) which

updates the Dataform contents to the database and allows you to continue to update the

same Dataform and Close which closes the Dataform If you make changes to the

Dataform the label for this button changes to Cancel Selecting Cancel closes the

Dataform without updating the database

Parent Dataforms and child Dataforms

A Dataform can be a parent or a child depending on how it was opened Any Dataform

opened from the Explorer is a parent Dataform A parent Dataform is modeless

Any Dataform opened from another Dataform is a child Dataform except in two specific

cases listed below A child Dataform is modal with respect to its own parent Dataform

but modeless with respect to any other parent Dataform the Explorer or the Query

Editor

The only cases in which a Dataform opened from another Dataform is a new parent

Dataform are

bull if the target of an association shown on the Dataform is an association and you open a

Dataform on the source of the target association

bull if the target of an association shown on the Dataform is displayed as a tree and you

open a Dataform on any level of that tree below the top level

Creating an association in the Dataform

To create an association instance using the Dataform you must first select an instance of

the required associationrsquos source and then open the Dataform for that instance



238

To open the Dataform you can either

bull highlight an entity type entity instance or association instance in the Sentences Explorer

and select Default Dataform from the shortcut menu or


and select the Default Dataform command on the View menu or


and select the Dataform button on the toolbar

You create an association in the Dataform by entering data in the target field As an

alternative to typing in a new value you can select from existing instances of the

appropriate type

To select an existing instance click the ellipsis button to the right of the entry field

Sentences displays a picker list from which you can select the target You canalso display

the picker list by right-clicking on the entry field and selecting Select lttarget typegt from

the shortcut menu or by pressing Alt + down arrow on the keyboard

If you select an entity or value instance from the picker list for a multiple association

Sentences first places the value in the edit field where you can edit it When you press

Enter or move to another field Sentences moves the value to the main list If you select

an association Sentences places it directly in the main list

Association type targets and metatype targets

If the target of an association type is an association type you cannot create a new instance

of the target by typing into the target field on a Dataform You can only create a new

instance by clicking the ellipsis button and selecting a target from the list displayed

Similarly if the target of an association type is a metatype you cannot create a new

instance of the target by typing into the target field on a Dataform You can only create a

new instance by clicking the ellipsis button and selecting a target from the list displayed

Dataform shortcut menu

When you right-click on a field in the Dataform Sentences displays a shortcut menu The

text of the shortcut menu commands includes the name of the association or the target

concerned This is indicated by the text in square brackets in the table below Not all

commands are available at all times for example the Create Select and Delete options

are not available if the presentation format is Radio Button or Check box

Command When Available Action

Follow Hyperlink If the target is a hyperlink

Opens browser or mail

program as required by

Hyperlink

View [association with this

target] Always

Displays a child Dataform for

the association If no

association exists the

displayed Dataform shows

the target only

View [target] Always Displays a child Dataform for

the target

View [source] When target is an

association type

Displays a parent Dataform

on the source of the target

association



239


Create [new association]

If this association is the

source of a further

association

Displays a child create

Dataform for the association

Create [new target] If this target is an entity type Displays a child create

Dataform for the target

Select [existing target Always Displays a picker list

Delete [association] When an association exists Deletes the association

Note The options Create [new target] Select [existing target] and Delete [association] may

be restricted or disabled by the query defining a custom Dataform

Selecting targets in the Dataform

The display of an association target in the Dataform varies according to the datatype of

the target type and the Format and Presentation options defined for the association type

and the target type

If an association target in a Dataform field is underlined this means either that the target is

a Hyperlink or that the association is itself the source of one or more further associations

If you double click a Hyperlink Sentences displays the target page for that Hyperlink in

your Web browser mail program or other application depending on the protocol being

used

If you double click an underlined target that is not a Hyperlink Sentences displays a

Dataform that has that association as its source

Double-clicking a word in a multi-line edit field selects that word

When association targets are displayed in a Table for target or Table for associations

format each field may be edited directly in the table This property can be disabled by

selecting the Disable in-place editing checkbox on the Format page of the Properties

dialog To open a child Dataform for the row displayed in a Dataform table double-click

any cell in the row The source of the child Dataform is the instance displayed first

column of the table

Creating an entity instance in the Dataform

Entity instances are always created in a Dataform When you are working in the

Sentences Explorer and want to create an entity instance follow these steps

1 Highlight an entity type name in the All types folder and select Dataform from the

shortcut menu

Note You cannot open a Dataform for a value type

Sentences displays a create Dataform (see ldquoCreate and update Dataformsrdquo ) which has the

selected entity type as its source

2 Enter the entity instance name in the first Dataform field This field has the entity type

name as its label

3 If there are any association types defined for the entity type the appropriate association

fields are displayed on the dataform and you can create the corresponding associations at

the same time as you create the entity To create an association either select an existing

instance from a Picker list or type in a new entity name Sentences automatically creates a

new entity instance of the appropriate type with the name you have used



240

Note Only the base Dataform contains all the associations for a type If you have defined a

custom Dataform as the default for the entity type it is possible that some associations may not

be displayed

4 Click Save amp Edit or Save amp Reset

Targets with duplicate names

Sentences uses unique hidden identifiers for entities (and for many other elements) This

means that you can create entities with duplicate names and rename entities as needed

Sentences always prompts you to confirm that you want to create a duplicate entity when

an entity with the name you are using already exists

If you type in a target name for which duplicate instances already exist Sentences

prompts you to select the correct instance by displaying the Resolve Instances dialog

This dialog displays all the identically named instances in a tree picker window which

allows you to expand the names and view their associations so that you can select the

correct instance Highlight the correct instance and click OK to make your selection

The Resolve Instances dialog is not displayed if you select a target instance from a picker

list

Targets that are subsets

The target of an association type may be a subset If you enter a new target instance for an

association type whose target is a subset Sentences checks that the instance you have

entered is a valid member of the subset

If the instance is not a valid member of the subset Sentences displays an error message

For more information on subsets see ldquoSubsets propertiesrdquo

Changing the target in a Dataform

You can change the target of an association in a Dataform either by selecting an existing

instance from a picker list or by typing in a new entity name

When you change a target Sentences checks whether the association you are changing is

the source of further associations If it is then Sentences treats changing the target in the

same way as it treats deleting a target Sentences may display a Deletion Impact dialog

listing showing what else is deleted when the target is changed

If you change the target in an association and that target is the source of a mandatory

association you must provide a value for the mandatory association before you save your

changes to the database Sentences displays an error message if you try and save without

completing all the mandatory associations

When you save a changed target on a dataform Sentences automatically checks whether

the change has affected membership of subsets

Instance specific Dataforms

When you open a Dataform on an instance that has instance specific association types

sourced on it the Dataform includes additional fields for those association types (see

ldquoInstance-specific association typesrdquo )

Picker list initial selection

Whenever you open a picker on a field in which you have started to type a new value the

picker puts the text that you have already entered into the Positioner field and performs a

positioning operation on that text



241

Business rules and states

Sentences Dataforms can display instance states These are displayed as read-only fields

They are not present in a Base Dataform but can be added as part of a Custom Dataform

query When a dataform is saved and not reset any states that have changed will be

updated

If a dataform field requires a particular input format or is mandatory and these

requirements have not been met then the field is highlighted in red to indicate this when

you attempt to save the changes With the introduction of Business Rules if by changing

or entering data on a dataform you directly or indirectly cause a state change that is

prohibited then the field in question will be similarly highlighted if possible

Display names

Sentences Dataforms show types display names in the dataform title and in fields if they

have Display Name Queries attached to their types Custom Dataforms can override the

Display Name Query to use (or none) for individual fields

Table and list buttons

Sentences Version 40 enhances dataform tables and lists with convenience buttons for

viewing adding and deleting items in the list or table

Creating a custom Dataform

The base Dataform for an entity or association type automatically includes all the

associations that have that type as their source When using the Section Layout system

the schema sections are used to layout the fields on the base dataform A custom

Dataform displays only those associations you choose to display Creating a custom

Dataform involves two steps

bull defining the custom Dataform on the Custom Dataform page of the Properties dialog

for the type

bull developing a query in the Query Editor which defines the associations to be displayed

on the custom Dataform and attaching it to the custom Dataform definition You may

also attach an existing query to a custom Dataform definition

Full details about using the Query Editor are given in Chapter 7 ldquoSentences queriesrdquo



242

To create a custom Dataform follow these steps

1 Open the Properties dialog for the entity or association type and select the Custom

Dataforms tab All the dataforms for the current type are listed including the base

dataform which always has the name of the type inside angle brackets The default

dataform is marked ltdefaultgt

2 Click Createhellip and name the custom Dataform

Figure 5-36 Selecting a query to attach to a subset

3 If you have not created a query click Edit Query Sentences creates a new query with

the current type is automatically selected as its data request node saves it with the name

you gave to the custom Dataform attaches the query to the custom Dataform definition

and opens it in the Query Editor for you to customise

4 Use the Query Editor to customise the query that includes the associations you want on

your Dataform as nodes in the request tree You can use forward and inverse associations

in the query tree Hidden nodes in the query tree are not shown in a custom Dataform

The Query Editor offers a number of options that are not suitable for use in custom

Dataforms For example select and sort nodes would generally not be appropriate for

custom Dataforms Similarly the use of parameters or the use of required nodes in the

query would not be appropriate for custom Dataform use

In addition derived type nodes are displayed as a read-only fields Sentences displays an

error message if you try to create a custom Dataform using an unsuitable query

5 Save the query and close the Query Editor

6 If you have already created a query to use for the custom Dataform definition click

Attach Query Sentences displays a list of suitable queries for the current type as shown

in Figure 5-36 For details of how Sentences determines which queries are suitable see

ldquoCustom Dataform restrictionsrdquo Select the saved query you created from the list and

click OK



243

7 If you want the custom Dataform to be used as the default Dataform click Set as

Default

Using the Dataform Section Layout system custom dataforms can arrange their fields in

sophisticated ways See the Human resources example profile for examples like the

Employee Custom Dataform

Refresh button on custom Dataforms

If a custom Dataform is based on a query that includes a derived type or a derivation an

additional button Refresh appears on the dataform (see ldquoDerived types and derivationsrdquo

) When this button is selected Sentences calculates the values for the derived types or

derivations shown on the Dataform The recalculation of a derivation is dependent on the

setting of its calculation option in the Derivation properties dialog (see ldquoDerivation

propertiesrdquo )

Custom Dataform restrictions

You can only use a query as the basis for a custom Dataform if it conforms to certain

rules The following conditions apply to any query that you want to use as the basis of a

custom Dataform

bull the query must have a data request node

bull the queryrsquos data request node must have a type

bull the type of the queryrsquos data request node must be related to the type that thecustom

Dataform is intended for

bull the queryrsquos data request node must not be hidden

bull the queryrsquos data request node must not be bound to an instance

bull the query may not have any parameters

bull the query may not use recursive closure or transitive closure

Triggers are not invoked when you click the Refresh button on a custom DataformThey

are invoked as normal when you click the Save button (see ldquoTrigger invocationrdquo )

Selecting a custom Dataform

You can select a custom Dataform instead of the Default Dataform from the Dataform

sub-menu of the Explorer shortcut menu

Sentences uses the first character of the custom Dataformrsquos name as a keyboard shortcut

key for the custom Dataform If the names of two or more custom Dataforms begin with

the same letter you cannot use the keyboard shortcut key to select the second or

The Dataform applet


244

subsequent custom Dataform as the key sequence always selects the first custom

Dataform

Where one or more custom Dataforms are defined for a type or for any of its supertypes

there is a choice of Dataforms that may be used to view and to create instances Define

the Dataform to be used as the default for a type using the Custom Dataforms page on

the Properties dialog

Custom Dataforms with subsets and supertypes

You cannot define a default Dataform for a subset type independently of its base type

The pages that appear on a dataform for a subset are always the same as those that appear

on the Dataform for the base type and all the criteria for the subset must be met before

the Dataform and its data can be saved

You can define different custom Dataforms for an entity type and its related supertype

and select different default Dataforms The pages displayed on these Dataforms may vary

If a Dataform includes an association that is not relevant for the selected type the field

remains blank

For more information about subsets and supertypes see the section ldquoComparison of

subsets and supertypesrdquo

The Dataform applet

You can display a Sentences Dataform as a stand-alone Java applet This is known as the

Dataform applet You can embed the Dataform applet in an HTML page on a Web server

to create a customised user interface for your Sentences database When you use the

Dataform applet you can specify the Dataform you want to use which may be either the

base Dataform or a custom Dataform for a named entity type

The dataform applet is controlled by an HTML page that supplies parameters to the applet

specifying the host and profile to use the type to open a Dataform on and (optionally) the

specific Dataform to display

An example of the Dataform applet is distributed with Sentences and can be found in the

ltSentences_homegtExamplesHTML directory To run this example with the Sentences

Enterprise Edition copy the file DataformApplethtml to your Sentences Web

application directory ltSentences_homegtTomcat4webappsSentences and open it

using your Web browser If you are using the default installation of Sentences with

Tomcat the URL is as follows

httplocalhost8090SentencesDataformApplethtml

The Dataform applet


245

Figure 5-37 Example of a Dataform applet in a browser page

The Dataform is displayed as part of the HTML page as shown in Figure 5-37 and

behaves like any other Dataform If you open other Dataforms from a Dataform applet

they are displayed in separate windows

Dataform applet code example

When you create an HTML page to launch a Sentences applet such as the Dataform

applet you can use a helper javascript library that facilitates deployment on various

browser and platform combinations See ldquoSentences client configurationrdquo for details

Applet parameters for the Dataform applet

The following parameters are used by the Dataform applet in addition to the standard

ldquoSentences applet parametersrdquo

Note that the value of the code parameter is different for each applet

bull ServletPort

The Dataform applet attempts to connect to the Sentences servlet using the host name and






the ServletPort parameter

bull ServletContext

The Dataform applet


246

The first part of the URL required to access the servlet The default is Sentences This

parameter depends on the configuration of the servlet container being used For example

with ServletExec you would normally use ldquoservletrdquo This parameter is optional

bull Profile

The Profile parameter defines the default profile opened when the Dataform applet is

started The name of your profile must not contain any special characters that need to be

represented by escape sequences in HTML This parameter is mandatory

bull EditOption


The possible values for the Dataform applet are schema data and none


schema allows the user to edit schema queries and data

data allows the user to edit data

none no editing actions allowed

If this parameter is set to none the Dataform is read-only This optional parameter is case-

sensitive and the default is schema

bull LazyType

This parameter specifies which entity or association type to open the Dataform on The

parameter is mandatory All of the following examples are valid uses of the LazyType

parameter

ltparam name=LazyType value=Employeegt

ltparam name=LazyType value=(Employee salary Money)gt

ltparam name=LazyType value=((Person bought Car) on Date)gt

Note The LazyType parameter replaces the EntityType parameter used in Sentences

Version 20

bull LazyInstance

This is an optional parameter which specifies an instance of the specified LazyType to

open the Dataform on If it is not specified the Dataform opens as a blank create Dataform

based on the specified LazyType All of the following examples are valid uses of the

LazyInstance parameter

ltparam name=LazyInstance value=Bill Jupitergt

ltparam name=LazyInstance value=(Bill Jupiter salary20000)gt

The LazyInstance parameter is locale-sensitive so care must be taken when using it with

locale-sensitive value datatypes such as Date or Time The HTML which gives the value

of the LazyInstance parameter must be stated in a format which is valid for that datatype

in the locale of the Sentences client For example on a client running with en_GB locale

the format for a Date datatype is as follows

ltparam name= LazyInstance value=((Bill Jupiterboughtpizza) on 22012000)gt

In contrast on a client running with en_US the format for a Date datatype is as follows

ltparam name= LazyInstance value=((Bill Jupiterboughtpizza) sect

on Jan 222000)gt

Failure to use the correct format results in an error stating that the instance cannot be

found

Note The LazyInstance parameter replaces the Entity parameter used in Sentences

Version 20

The Dataform applet


247

bull LazyId

This is an optional parameter which may be used instead of the LazyInstance parameter

The LazyId parameter specifies the internal identifier of a Sentences element The

internal identifier may be useful in identifying distinct instances which share the same

name (for example where a customer list includes more than one instance named John

Smith) The format for the LazyId parameter is

ltparam name=LazyId value=12012gt

You can retrieve the internal identifiers when you run an XML Export command (see

ldquoInclude Sentences IDsrdquo )

Do not use the LazyInstance parameter and the LazyId parameter together as this

causes an error

bull EnablePickers

This parameter disables the display of picker lists in the Dataform This prevents a user

from viewing data entered by a previous user The possible values for this parameter are

Yes which allows the display of picker lists and No which disables the use of picker lists

This parameter is optional and the default value is No If you set this parameter to No to

disable the use of picker lists you can still make use of the combo box presentation

method to allow users to select from an existing list

bull SaveButtonText

This is an optional parameter that allows you to set the text on the Dataformrsquos save

button The default value for this parameter is Save (language dependent)

bull ImageURLBase





display images By default this is the Images subdirectory created in the

ltSentences_datagt location you chose during installation For more information see

ldquoAbout the ImageURLBase parameterrdquo

bull RequestSize

This optional parameter sets the number of data items retrieved from the Sentences

database for each request If more items exist Sentences displays the Morehellip prompt in

the relevant multiple association field in the Dataform If this parameter is not set the

dataform applet uses the value for the RequestSize parameter that has been set for the

Sentences client (see ldquoSentences Applet Parametersrdquo) The default value is 500

bull Dataform

This is an optional parameter that instructs the applet to use a specific custom Dataform

for the entity type or entity specified If this parameter is not specified the applet uses the

default Dataform If the value given for this parameter is the entity type name enclosed in

angle brackets for example ltPersongt the applet uses the base Dataform for the type

bull DisplayStatus

This parameter determines whether a status bar is shown when the applet is displayed

Possible values are yes and no The default value is yes

bull Border

This is an optional parameter which specifies a border decoration style on the Dataform

Possible values are line bevel etch and none The default value is none


The Picker applet


248

bull ForegroundColour

These two optional parameters allow you to specify the foreground and background

colours of the Dataform panel using the standard HTML hexadecimal coding for colours

The dataform controls are not affected If these parameters are not set the applet uses the

default system colours

Note Sentences accepts the American spelling of these parameters (BackgroundColor and

ForegroundColor) as well as the British spelling shown above

As an alternative to using only the BackgroundColour and ForegroundColour

parameters you can specify colours for a number of system features

The Picker applet

You can display a Sentences picker as an individual Java applet This is known as the

Picker applet and is illustrated in Figure 5-39 You can embed the Picker applet in an

HTML page on a Web server to create a customised user interface for your Sentences

database

An example of the picker applet is distributed with Sentences and can be found in the


Enterprise Edition copy the file PickerApplethtml to your Sentences Web application

directory ltSentences_homegtTomcat4webappsSentences and open it using your Web

browser If you are using the default installation of Sentences with Tomcat the URL is as

follows

httplocalhost8090SentencesPickerApplethtml

The Picker applet displays a list of instances of a specified entity type or association type

from a specified profile as defined in the appletrsquos parameters

When using any of the Sentences Applets you will be asked to log in (unless anonymous

access is enabled)

The Picker applet


249

Figure 5-39 Example of Picker applet in a browser page

The picker applet is controlled by an HTML page that supplies parameters to the applet

specifying the host and profile to use and the entity or association type to open a picker

on

When you double-click on an item from the Picker applet or highlight the item and click

the Edit or the View button Sentences opens a Dataform for the selected item The

Dataform opened is a standard client dataform and not a Dataform applet

If the picker applet cannot find the profile you specify or if you specify a LazyType for

the applet that does not exist or has a duplicate in the database the applet displays an

error in the Message Log and does not run

Picker applet code example

When you create an HTML page to launch a Sentences applet such as the Picker applet

you can use a helper javascript library that facilitates deployment on various browser and

platform combinations See ldquoSentences client configurationrdquo for details

In the example of the picker applet ltSentences_homegtExamplesHTML

PickerApplethtml the instances displayed in the picker are defined by these

parameters


EditOptiondata

FixedProfileno

LazyTypeEmployee

CreateButtonyes


Borderetch

The Picker applet


250

This means the picker displays instances of the Person entity type from the Human

resources profile A create button will be included and there will be an etched border

around the applet

Applet parameters for the Picker applet

In some cases the parameters used by the Picker applet are identical to those supported by

the Dataform applet (see ldquoApplet parameters for the Dataform appletrdquo ) In other cases

there are variations in the way the parameters are used and there are also some

parameters that are unique to the Picker applet

The following parameters are used by the Picker applet in addition to these and the

standard ldquoSentences applet parametersrdquo


All the parameters used by the Picker applet are case-insensitive for both the parameter

name and the parameter value except for the value of the LazyType parameter which is

case-sensitive

The following parameters are used by the Picker applet in exactly the same way as they

are used by the Dataform applet

bull ServletPort

bull ServletContext

bull Profile

bull ImageURLBase

bull LazyType

bull Dataform

bull DisplayStatus

bull Border



The following parameters are used by the Picker applet with variations from the way they

are used for the Dataform applet

bull EditOption


The possible values for the Picker applet are data and none

Parameter Value Editing Actions Allowed



If this parameter is set to none users may only view existing values from the Picker

applet The default setting for this parameter is none

The setting of this parameter affects the display of pickers in any Dataform opened from

the Picker applet and the display of buttons on the Picker applet If the EditOption

parameter is set to none the Picker applet displays a View button and the Create and

Edit buttons are not displayed

bull EnablePickers

The Query applet


251

This parameter determines the display of picker lists in any Dataform launched from the

Picker applet The possible values for this parameter are Yes which allows the display of

picker lists and No which disables the use of picker lists

The default value is Yes unless the EditOption parameter is set to none in which case

picker list use is disabled irrespective of the setting for this parameter

The following parameters used by the Dataform applet are not supported by the Picker

applet

bull LazyInstance

bull LazyId

bull SaveButtonText

The following parameters are unique to the Picker applet

bull Picker

This parameter defines the style of picker displayed It has a similar function to the

Picker options on the Format properties page The possible values for this parameter are

Tree and List The Calendar picker is not available If this parameter is not specified

the style of picker defined for the type is used

bull ShowTitle

This parameter defines whether or not there is a title embedded at the top of the applet

The possible values are yes or no If this parameter is not supplied the default value is

yes The title displayed is the name of the type on which the Picker applet is opened

bull CreateButton

This parameter determines whether a Create button is displayed in the Picker applet

which allows users to create new instances of the displayed type The possible values for

this parameter are Yes and No The default value is Yes The Create button is not

displayed if any of the following conditions are met irrespective of the setting of this

parameter

bull the Profile opened by the Picker applet does not allow data changes

bull the EditOption parameter is set to none

bull the Picker applet is used on an association type

bull the Picker applet is used on a type which has Prohibit New Instances set

bull the Picker applet is used on a type which is a subset

bull DeleteButton

This parameter determines whether a Delete button is displayed in the Picker applet

which allows users to delete existing instances of the displayed type The possible values

for this parameter are Yes and No The default value is No

The Delete button is not displayed if the Profile opened by the Picker applet does not

allow data changes

The Query applet

You can access query results using a Java applet known as the Query applet When you

use the Query applet with a query that makes use of query parameters the applet display

which is illustrated in Figure 5-41 resembles the Query parameters dialog (see

ldquoExecuting a query which has parametersrdquo ) If the query does not makes use of query

parameters Sentences displays a dialog similar to the Query parameters dialog which

does not have any fields

The Query applet cannot be used with Set Queries

The Query applet


252

An example of the Query applet is distributed with Sentences and can be found in the


Enterprise Edition copy the file QueryApplethtml to your Sentences Web application



follows

httplocalhost8090SentencesQueryApplethtml

Figure 5-41 Example of the Query applet display for a query with parameters

You can embed the Query applet in an HTML page on a Web server to create a

customised user interface for query results from your Sentences database

To run the query select the appropriate parameter values and click OK While Sentences

executes the query it displays a Cancel button This button may not be visible if the query

is executed very quickly

By default the query results are displayed in the same way as they are if you select the

View XML results option for the same query using the XML parameters attached to the

query You cannot specify different XML parameters when running the Query Applet

The resulting data may be either XML or HTML data depending on whether the XML

parameters specify a stylesheet to be used and which kind of data such a stylesheet

generates (see ldquoView query results as XMLrdquo )

Query applet code example

When you create an HTML page to launch a Sentences applet such as the Query applet



In the example of the query applet ltSentences_homegtExamplesHTML

QueryApplethtml the instances displayed in the query applet are defined by these

parameters


LazyQueryProject resources

Bordernone


Using colours in Sentences applets


253

ColourwindowFFFFEE

ColourmenuFFFFEE





ColourcontrolDDEEFF







This means the query applet displays parameters for the Project resourtces query from

the Human resources profile There will be no border around the applet Various

colours are also set (see ldquoUsing colours in Sentences appletsrdquo)

Applet parameters for the Query applet

The following parameters used by the Dataform and Picker applets are also used by the

Query applet For more details see ldquoApplet parameters for the Dataform appletrdquo

bull Profile

bull Border

bull ServletPort

bull ServletContext

bull DisplayStatus

The following parameter is unique to the query applet

bull LazyQuery

This parameter defines the name of the query to use This parameter is mandatory The

query referred to must not be a Set Query

bull Target

This optional parameter defines the name of the browser window in which to display the

query results This parameter supports the standard HTML values for the target attribute

which are _blank (which opens a new browser window) _self (which loads the results

window into the same frame or window as the applet was in) _parent (which loads the

results window into a window or frame one level above in a frame hierarchy) _top

(which loads the results window into the top level window) or ltnamegt for a named

window

In addition to these parameters the query applet also makes use of the colour parameters

described in ldquoUsing colours in Sentences appletsrdquo


When you create the HTML pages for use with Sentences applets you may use either a

simple colour scheme using the BackgroundColour and ForegroundColour parameters

only or an advanced colour scheme which allows you to specify colours for a number of

different system features There is an example of the use of the advanced colour scheme

in the partial HTML code listing for the Dataform applet example in Figure 5-40

You must use either the BackgroundColour and ForegroundColour parameters only or

the advanced colour scheme If Sentences detects the BackgroundColour and

ForegroundColour parameters all other colour parameters are ignored



254

In both schemes you need to define colours using standard HTML hexadecimal coding If

your Web page is going to be viewed by users who have only 256-colour monitors it is

recommended that you restrict your choice of colours to the 216 nondithering colours

which are common to all browsers (the so-called ldquoWeb-safe paletterdquo)

Sentences automatically maps the colours of certain system features to your

BackgroundColour and ForegroundColour settings Sentences also calculates values for

ldquodarkerrdquo and ldquobrighterrdquo versions of these colours which are used for the highlights that

create a three-dimensional effect

The system features mapped by Sentences are shown in the following table

System Colour Usage Mapped To

Window The interior of text fields and

lists BackgroundColour

Menu The backgrounds of menus BackgroundColour

MenuText The text in menus ForegroundColour

textText Text inside text fields and

lists ForegroundColour

textHighlight

The background of selected

text (for example in a text

field)

Brighter

BackgroundColour

textHighlightText The colour of selected text

(for example in a text field)

Darker

ForegroundColour

control

The backgrounds of controls

such as buttons labels

panels and sliders

BackgroundColour

controlText The text in controls such as

buttons and labels ForegroundColour

controlHighlight

The bright edge of controls

such as buttons (used to

give 3D appearance)

Brighter Background

controlLtHighlight Even brighter edge of

controls

Even Brighter

Background

controlShadow

The dark edge of controls


give 3D appearance)

Darker Background

controlDkShadow Even darker edge of

controls

Even Darker

Background

scrollbar The background of a

scrollbar (outside the slider) Brighter Background

If you wish to implement an advanced colour scheme you can create individual

parameters for each of these features

The name of the parameter is the same as the entries in the Colour column with the

addition of the prefix ldquoColourrdquo in the pattern

ltPARAM name=Colourcontrol value=FFFFFFgt

Any colours not specified retain their default values The case of the parameter name is

not significant

If any of the highlight colours such as textHighlight are not specified then its value is

derived automatically as shown in the table above

Sentences and external formats


255

The following are examples of colour specifications for individual features

ltPARAM name=Colourwindow value=33CCFFgt

ltPARAM name=Colourmenu value=CC3399gt

ltPARAM name=ColourtextText value=FFCC00gt

Note Sentences accepts American spellings for these parameters (such as Colorwindow and

Colormenu) as well as the British spellings shown above


Sentences provides extensive support for XML which is emerging as the new industry

standard for data exchange The procedures you must use to export data from a Sentences

database in XML format involve the Query Editor and details are given in ldquoThe Query

Editor and XMLrdquo

You can export a Sentences schema to XML For more information see ldquoExport

Sentences schema to XMLrdquo

Further details about the use of XML with Sentences are given in Chapter 8 ldquoSentences

and XMLrdquo For security reasons some XML features are only available when you have

enabled an appropriate servlet For more details see ldquoServlet access to Sentencesrdquo

You can also import comma separated value (CSV) files into a Sentences database and

export Sentences data to a CSV files CSV files are ldquoflatrdquo data files that can be created or

read by many applications Details of the CSV Import command are given in this section

and details of CSV Export are on page 2-103

Some examples of using CSV Import and CSV Export to integrate data from Sentences

with other applications are shown in ldquoIntegration with Microsoft Office applicationsrdquo

Using triggers when you import data

Trigger information is part of the Sentences schema which is read by the import

programs When you import XML data any triggers attached to any of the types for which

data is being imported are run This means that it is possible for a trigger to interrupt an

import operation When you import CSV files you can control whether or not triggers are

executed by specifying a command line switch

In order for the import program to use a trigger the JAR files containing the triggers must

be in the directory listed in the TriggerPath property in the Serverproperties file

and the triggers must be attached to types in your schema You can use switches with the

Import command to determine whether or not triggers are run

CSV Import

CSV Import is a command line program which is run on the Sentences server when

Sentences is not running

CSV Import allows you to add data derived from other systems to a Sentences database

You can also take data from one Sentences database and import it into a different

database using a combination of the Export to CSV command and CSV Import

CSV Import only deals with data and cannot be used to create or alter a database schema

You must have your database schema in place before importing data The schema must be

saved as named profile because you need to use the profile name when you run CSV

Import

If you want to import data into a complex database schema you may need to divide your

data into a number of CSV files which should each be imported separately In this case

the order in which the files are imported becomes significant

There is a detailed example of using CSV Import in Chapter 11 ldquoWorked examplesrdquo

CSV Import cannot distinguish between existing and new instances that have identical

names and treats the new instance as an update of an existing instance In cases where



256

new instances may have the same names as existing instances you should use Sentencesrsquo

XML Import procedure (see ldquoImporting XML datardquo )

CSV Import and supertypes and subsets

If your database uses supertypes and subtypes you must import the subtype instances

before you import the supertype instances to avoid the possibility of creating duplicates

This is because every subtype instance is also an instance of the corresponding supertype

You cannot import subset instances directly as the membership of a subset is always

determined by the result of a subset query All the relevant instances must be imported as

instances of the corresponding superset Those instances which meet the criteria for

membership of the subset are displayed when the subset type is selected

The problem of duplicate instances may occur when you import a CSV export file which

was based on a subset query If you create one CSV export file for a query which selects

all the instances of a superset entity type and a separate CSV export file which selects all

instances of the Subset entity type and then import both of these files into a new profile

you may create duplicates in your new database

This is because an instance of a Subset entity type is also an instance of the superset entity

type To avoid this problem you must import the CSV export file from the subset query

first

Structure of CSV files

When you import a CSV file Sentences treats the first line of the file as a series of

column headings and tries to match the column heading to an existing entity type

Column headings must match existing entity types and may optionally contain an

association verb to specify an association type The rules that Sentences uses a for this

matching are explained below

The order of the columns in the CSV file is also significant because of the way in which

CSV Import determines the association type to which column data corresponds CSV

Import can create association instances only where an instance of the source type for the

equivalent association type has been created as a result of a preceding column in the file

CSV Import rules

For each column in the CSV file Sentences identifies an entity type and looks for the

relevant association types according to the following rules

bull The association type can be sourced on any entity type or association type identified for

an earlier column or a subset or supertype of such a type

bull The association type can be targeted on another association type provided that the last

column which contributes to the identification of the target association type is preceded

by all columns which contribute to the identification of the source type

bull The target of the association type for a column can be a subset or supertype of the entity

type identified for that column

bull You can specify an association type by including its name as part of the column

heading delimited by a colon () The association type specified must still meet the other

criteria above

bull Because the colon () character is used as a delimiter between entity type names and

association type names you cannot use a colon character in an entity type name

bull If more than one association type is suitable and you do not specify which one to use

the program produces an error message and stops

bull If a line in a CSV file ends with one or more empty fields which are not marked

by a delimiter character Sentences assumes that these fields are empty



257

Cardinality rules and triggers with CSV import

The CSV Import program does by default implement Sentencesrsquo usual checks and

constraints on association type cardinality (see ldquoCardinalityrdquo ) and does run triggers

associated with types included in an import

However you can add the [-notriggers] switch to the CSV import command line to

force the import program to ignore triggers and cardinality checks If you choose to use

the [-notriggers]switch it is possible that after running CSV Import your Sentences

database may contain multiple associations for an association type defined as singular

Running CSV Import

To import a CSV file you need to run an external command while the Sentences server is

shut down You must run the command separately for each file you want to import

You must have write access to the chapter files to which you wish to add data in order to

run CSVImport

The command you run varies according to the platform you are working on In all cases

the command relates to the Java class that controls the import procedure

comsentencesexportImportCSV

To import a CSV file on Windows platforms

The Sentences installation directory on Windows platforms includes a batch file

CSVImportbat Use this batch file to run the CSV Import procedure

1 Shut down the Sentences server and open a command window (MS-DOS window)

2 Navigate to your Sentences installation directory

3 Type in the import procedure command in the format

CSVImport [-notriggers] [-nolog] ltprofilenamegt ltfilenamegt

where

ltprofilenamegt is the name of the profile you are importing into and ltfilenamegt is the

path and name of the CSV file you want to import

[-notriggers] is an optional switch to stop CSV Import from running any triggers that

are attached to types included in the import By default Sentences runs the triggers and if

you include the -notriggers switch Sentences ignores the triggers

[-nolog] is an optional switch which stops the creation of a recovery log file Using the -

nolog switch may speed up the import process An example of CSV Import is as follows

CSVImport HR CSV Example DeveloperExamplesCSVImportEmployeescsv

While CSV Import is running Sentences displays a row of asterisks Each asterisk

represents 100 lines of data If you know the number of lines of data in your CSV file the

row of asterisks can indicate the progress of the import

To import a CSV file on Unix Linux platforms

The Sentences installation directory on Unix Linux platforms includes a shell script

CSVImportsh Use this shell script to run the CSV Import procedure You can run the

CSV Import procedure either from the command line or from a script file using a

command for example





Server Process Scheduler


258

CSV Export

You can export the results of a Sentences query as a CSV file using the Export to CSV

filehellip command in the Query Editor or the Sentences Explorer You do not need to stop

the Sentences server in order to run the Export to CSV filehellip command

By making the Export to CSV filehellip command part of the query system Sentences

allows you to sort and select data from the Sentences database before you export it The

behaviour and procedures for exporting query results are different for queries and for set

queries For more information about using the Export to CSV filehellip command see

ldquoExporting query results as CSV datardquo


Sentences V40 introduces a scheduler that runs as part of the server Several processes

can be defined in a list and scheduled to run at a specific time and date or on a regular

basis The Personal Edition does not contain the Scheduler functionality

Only one scheduled process list can be executed at a time If a second list becomes due

then it is not queued till afterwards - it is ignored

Access to the Scheduler

A Sentences User has to be granted the Scheduler Role System Administrators

automatically have this privilege See the ldquoUser security referencerdquo for details of User

Roles

Scheduled Process Lists

The Scheduler enables you to create lists of Server Processes that will be run in sequence

at a specified time and date or at regular intervals A Scheduled Process List has a name a

list of Processes and a list of Schedule Plans Each Schedule Plan describes a date and

time or regular intervals that the list of processes will be run

Each list can be temporarily disabled and records the last time they were run and the

outcome for example whether the processes could not complete due to an error

If one process in the list fails then no further items in the list are attempted

To create a Scheduled Process List follow these steps

1 In the Sentences Explorer select Server Process Scheduler from the Tools

menu

Please wait while the list of available profiles queries entity types LazyView

chapters is read from the server

2 Select Create to open a New Scheduled Process List Dialog

3 You must give the list a name

4 You can optionally disable the list by selecting the Disabled checkbox

5 Create one or more Process (see below)

6 Create one or more Schedule Plan (see below)

7 Select OK to save the new list or Cancel to discard it

Server Processes

There are five types of process that can be scheduled to run Execute Query Set Entity

Type Name Creation Seed Update Static LazyView Data Replace Data Chapter Backup

Database



259

Execute Query Process

This process executes a query or an update query in a specific profile The output can

optionally be saved

To create an Execute Query Process follow these steps

1 From the New Scheduled Process List Dialog select the Create button next to

the list of Processes and select Execute Queryhellip from the sub-menu

2 Select the profile that contains the query you wish to execute and then select the

query from the two drop down lists

3 You can optionally check the Output results to file checkbox if you wish the

results to be output to a file

4 Select OK to add the process to the process list or Cancel to cancel

The output from a query will be saved to a text file in XML format The location can be

specified in the Serverproperties file but defaults to a subdirectory of the Chapters

Directory named Output Sub-directories will be created for the profile and the query

name (with inapropriate characters changed to underscores for the operating system) The

name of the output file will be the date and time when the query finished executing in the

format YYYYMMDDHHMMSSxml

Set Entity Type Name Creation Seed Process

To compliment the Automated Entity Type naming functionality the ldquoseedrdquo starting ID

can be set for a specific Entity Type in a Profile

To create a Set ET Name Creation Seed Process follow these steps


the list of Processes and select Set ET Name Creation Seed hellip from the sub-

menu

2 Select the profile that contains the entity type you wish to change and then select

the entity type from the two drop down lists

3 Enter the new seed


Only entity types that are set to automatically generate names using an ID seeded with a

starting value will be included in the drop down lists Only profiles that contain such

entity types will be listed

If the entity type generation mode is subsequently changed to not be an incremental ID

then the seed will still be set but this will have no effect

Update Static LazyView Data Process

This process is used to get the latest snapshot data for a static LazyView Mapping The

specified Profile and LazyView Chapter are used to update or replace the relational data

To create an Update Static LazyView Data Process follow these steps


the list of Processes and select Update Static LazyView Datahellip from the sub-

menu

2 Select the profile that contains the LazyView you wish to update and then select

the LazyView chapter from the two drop down lists

3 Select which of the three updates you wish to make



260

Standard Update Update the existing data with the latest additions

changes and deletions from the relational database This annotates each

instance with a timestamp so that the update history can be viewed

Incremental Update Add new data and update changes from the

relational database but do not annotates each instance with a timestamp

and do not delete old data This is faster than a Standard Update

Replace Data Delete the existing mapped relational data and re-import

the latest data This process replaces the existing Data Chapter that has

been set as the target for data changes and deletes the old one as it is

assumed that the data is transient This is the fastest process You can

optionally specify a limit to the number of rows imported from each

table


If static data is to be regularly updated then the third option is the most efficient method

It will delete the previous data chapter so any other data should be stored in a separate

chapter

Replace Data Chapter Process

This process allows the user to replace the chapter that is the target for data changes for a

specific profile The old chapter can be kept or deleted

To create a Replace Data Chapter Process follow these steps


the list of Processes and select Replace Data Chapterhellip from the sub-menu

2 Select the profile that you wish to replace the target for data changes chapter

from the drop down list

3 Optionally uncheck the Delete old chapter file checkbox if you wish to keep the

old chapter file


If the old chapter file is kept then it can be restored in the profile definition This would

enable the database to be viewed at that point in time as a kind of archive

Backup Database Process

This process starts an online backup of the database See ldquoOnline Backuprdquo for details of

how an online backup works

Schedule Plans

There are several types of schedule plan that can be added to a Scheduled Process List to

determine when the list is executed

bull Specific date and time

This is the simplest of Schedule Plans specifying a single date and time

bull Daily Recurring Plan

This Schedule Plan allows you to specify that the list should be executed every weekday

or a fixed number of days apart For example every 10 days

bull Weekly Recurring Plan

This Schedule Plan allows you to specify that the list should be executed a fixed number

of weeks apart For example every 2 weeks You must specify which days of the week

the list should be executed Monday through to Sunday You can select any number of

days of the week from all to just one



261

bull Monthly Recurring Plan


of months apart on a specific day of the month For example every 6 months on the 3rd

of the month

Alternatively you can specify that the list is executed every [ first | second | third | fourth |

last] [Monday | Tuesday | Wednesday | Thursday | Friday | Saturday | Sunday | Day |

Weekday] For example every last Friday of each month

bull Yearly Recurring Plan

This Schedule Plan allows you to specify that the list should be executed on a specific day

of a specific month each year



Weekday] of a specific month For example every third Tuesday of April

You must specify a time of day for all Recurring Plans If you wish to execute a list at

more than one time a day you must enter two plans one for each time

All Recurring Plans allow you to specify a Start Scheduling from date and a Stop

Scheduling after date If you do not specify a Stop Scheduling after date then the list

will continue to be scheduled indefinitely

When calculating the next Due date the Start Scheduling from date is used as a starting

date when calculating say every third day

Managing Scheduled Process Lists

The Server Process Scheduler Dialog allows you to manage the Scheduled Process Lists

You can create new lists as mentioned above You can Edit Delete and Disable the lists

You can also refresh the Inputs (available profiles Chapters Queries and Entity Types)

and the Scheduled Process Lists themselves The table shows when each list is next due to

be executed when it last executed and the outcome By Editing a Scheduled Process List

that has run you can view more details of the outcome including the start and finis times

Manually running a Scheduled Process List

The Server Process Scheduler Dialog allows you to select a Scheduled Process List and

run it immediately ndash regardless of its Schedule Plans

You can also request that the currently running Scheduled Process List be cancelled In

most cases this means that once the current process has finished the next item in the

Scheduled Process List will not be run The list will be cancelled and the outcome is

recorded as such

Viewing Scheduled Process List Progress

The list will not automatically refresh when a process is started or cancelled You must

select the Refresh Lists button to update the status of all Scheduled Process Lists

The outcome of a Scheduled Process List is not updated until execution is completed or

cancelled You can view the progress of a List that shows when each item in the list has

completed through the Statistics applet See ldquo Scheduled process statusrdquo

Sentences and Java technology

Advanced techniques

263

Chapter 6

Advanced techniques

This chapter looks at techniques for getting the best out of Sentences and is

designed for more advanced users The topics described in this chapter are

bull Sentences and Java technology

bull transaction processing in Sentences

bull Dataform tabbed pages with subsets and supertypes

bull target parameters

bull creating database views using profiles and chapters


Sentences makes use of Java technology and the Java Virtual Machine to achieve

platform independent operability This section is a brief introduction to the architecture of

Java programs for users who may be unfamiliar with Java More information on Java can

be obtained from the Java website

httpwwwjavacomendownloadwhatis_javajsp

The Java Runtime Environment contains two components that allow Java applets to be

run on the client machine The first component is a browser plug-in for Web browsers

such as Microsoft Internet Explorer Firefox and Chrome The plug-in allows a Java

applet to run inside the browser The second component is called Java Web Start This is a

desktop application program that also allows a Java applet to run as if it were a desktop

application The Sentences Explorer application is one such Java applet

Java programs that run on the server are known as servlets Sentences has a number of

server servlets for different purposes More information about servlets can be obtained

from the Oracle website

httpwwworaclecomtechnetworkjavaindexhtml

Figure 6-1 shows a diagrammatic representation of how the Sentences applet and servlets

communicate in the Sentences Enterprise Edition The right-hand side of the diagram

represents a client machine running a Web browser with the Java plug-in running the

Java Virtual Machine It also shows the applet running in Java Web Start

The left-hand side of the diagram represents a server machine which is running an

Application Server (for example Oracle Glassfish or IBM WebSphere) A Java

Application Server contains a Web server which requires a servlet container to run Java

servlets Some Web server programs such as Tomcat already contain a servlet container

The servlet container browser plugin and Java Web Start all perform the same purpose to

allow access to the Java Virtual Machine

Transaction processing in Sentences

Advanced techniques

264

Figure 6-1 Diagram of client and server interaction in Sentences

The Sentences applet sends requests to the SentencesServer servlet running on the

server The servlet then sends a response to the applet The communication between

server and client uses the Internet communication protocol TCPIP

The setup described here applies to the Enterprise Edition even when it has been set up in

local mode with the client and server parts of the programme actually residing on the

same physical computer The Personal Edition of Sentences however does not use a

client-server configuration and the whole program is bundled as a single application


A database transaction is generally considered to be an action or series of actions that

changes one or more items of data stored in the database Sometimes a number of related

units of information need to be changed together

The method for updating data in Sentences is divided between the client and the server

All data resides on the server and the server handles data requests from the client

Sentences is designed to work over the Internet and therefore the communication between

client and server uses Web-based protocols This means there are no persistent

connections between server and client Each client request is handled and replied to and

the connection is then closed There is no record locking on the server side

Every time a user updates information to the database the new information must be

available immediately to all other users so as to support real time applications

Sentences does not use any of the data locking or file locking techniques commonly used

in relational databases to maintain data integrity Instead requests to change the database

include a copy of the unchanged data which is used to verify that no other changes have

been made since the data being changed was sent to the client

Sentences Explorer based updates

If you change data in the explorer for example adding or deleting an entity type your

change is sent to the server as soon as you click the Create button or the Delete button

When you rename any item your change is sent to the server as soon as you press the

Enter key

All changes received by the server are processed immediately If for any reason your

change cannot be updated to the database for example if the entity type you selected as

Dataform tabbed pages with subsets and supertypes

Advanced techniques

265

the target for a new association type has been deleted by another user Sentences displays

an error message

Dataform based updates

In order to display a Dataform the Sentences client sends a data request to the server The

server searches the database and returns the requested values to the client These values

represent the state of the data on the server at that moment in time

The data returned is displayed in the Dataform When you change data on the Dataform

the Sentences client stores your changes in an update package All the

changes in a Dataform and any related child Dataforms are stored in the same package

Child Dataforms are defined in the next section When you click the Save button all your

changes are passed to the server along with the original data request and the original set

of returned values

All changes in your package are processed by the server as soon as they are received The

first action taken by the server is to reprocess the original data request and to compare the

current returned values with the stored set of returned values from the original request

Messages from multiple users are queued and are processed by the server one at a time

Any difference between these two sets of values indicates that data has been changed by

another user after your original data request was made In this case your update package

is not processed and none of your changes are updated to the database

If for any reason any one change in your package cannot be updated to the database then

none of the changes in your package are updated and Sentences displays an error

message

Updates in parent and child Dataforms

The Dataform that relates to an object shows all the associations that have that object as

their source Each association is represented by a label based on the verb of the

association and a data entry field for entering or displaying the target Dataforms opened

from the Explorer are parent Dataforms

You can display a shortcut menu on the target field and then display another Dataform by

selecting one of the Viewhellip options from the shortcut menu Dataforms opened from

other Dataforms are almost always child Dataforms (see ldquoParent Dataforms and child

Dataformsrdquo )

Any changes made on a child Dataform are regarded as part of the same transaction to

which the original parent Dataform belongs This means that changes made in a child

Dataform are not saved to the Sentences server until the original Dataform is saved

You can check whether a Dataform is a child or a parent by looking at the text on the

command buttons A child Dataform has an Apply command button On a parent

Dataform the command buttons are Save amp Reset Save amp Edit or Save

If the Sentences server does not accept a change you want to make you must refresh your

view of the server before you try and save your changes again


This section describes the original Dataform Page Layout system for Dataforms and

Custom Dataforms This system has been replaced with the more versatile Dataform

Section Layout system See the section The Sentences Dataform under Chapter 5

Workind with Sentences for details

You can use the Sentences Query Editor to create custom Dataforms Custom Dataforms

may include tabbed pages based on Page nodes that you add to your query (see ldquoPage


Advanced techniques

266

Nodesrdquo )Sentences also adds a tabbed page for any instance-specific association types

(see ldquoInstance-specific association typesrdquo )

Sentences automatically displays Dataform tabbed pages for subset or supertype

associations in any base Dataform and in any custom Dataform you create in addition to

the tabbed pages you specify using Page Nodes If Schema Pages have been created then

these will be used to create default Page Nodes

The order in which these automatically created tabbed pages appear on the base Dataform

is the same as the order of the subsets in the entity typersquos has subsets folder in the

Sentences Explorer schema pane You can change the order of the subsets in this folder

by using drag-and-drop and this changes the order in which the Dataform subset tabs are

displayed

The following sections show some examples of how using subsets and supertypes affects

the appearance of your Dataform

Figure 6-2 The Fivestar Garage application Sentences Explorer view

Figure 6-2 shows the Sentences Explorer schema and data panes for a fictional garage

application The database for this application uses a number of examples of supertypes

and subsets The entity types Employee and Customer both use the entity type Person

as their supertype

Dataform appearance with Supertypes

In this fictional garage application the entity type Person is the source of a number of

association types The Prohibit new instances property has been set for Person so you

cannot create new instances of this type However all the instances of Employee and of

Customer are also instances of Person All the instances of Employee and of

Customer are displayed in the data pane when you select Person in the schema pane


Advanced techniques

267

Figure 6-3 Dataform on instance of customer showing Person page

Figure 6-4 Dataform on instance of employee showing Person page

Figure 6-3 shows a Dataform on an instance of Customer showing the Person page and

Figure 6-4 shows a Dataform on an instance of Employee also showing the Person

page The associations types displayed in each case are identical as both Dataforms are

showing the association types that have Person as their source

Figure 6-5 Dataform on instance of Customer showing Customer page


Advanced techniques

268

Figure 6-6 Dataform on instance of Employee showing Employee page

Figure 6-5 and Figure 6-6 are not the same as Figure 6-5 shows only the association

types that have Customer as their source and Figure 6-6 shows only the association

types that have Employee as their source

The Fivestar Garage application uses an entity type called Job This is the supertype for

Bodyshop and Workshop entity types Figure 6-7 and Figure 6-8 show the Dataform

tabs for Workshop and Bodyshop which reflect the different arrangements of data for

jobs 1001 and 1004 displayed in Figure 6-2

Figure 6-7 Dataform on instance of a Job showing Workshop page


Advanced techniques

269

Figure 6-8 Dataform on instance of a Job showing Bodyshop page

Dataform example with Subsets

One of the association types that is sourced on Job refers to the jobrsquos status The possible

values for this association are A = Waiting B = Started and C = Finished

The application includes three subset entity types named Waiting jobs Started jobs and

Finished jobs Subset entity types are shown with yellow icons in the schema pane

These types have been modelled as subsets of Job because they represent the status of a

particular job which changes from time to time The subset query for each subset checks

the value of the Status association In each query the association node is bound to the

appropriate instance

Figure 6-9 shows the subset query for the Waiting jobs subset For more information on

using queries see Chapter 7 ldquoSentences queriesrdquo

Figure 6-9 The subset query for the Waiting jobs subset

The Finished jobs entity type is the source of an association type invoice which only

applies to finished jobs As Finished jobs is the source of an association type the

Dataform creates a separate tabbed page with the subset name as its title which can be

seen in the Dataform for Job 1004

Target parameters

Advanced techniques

270

Figure 6-10 Dataform for job 1004 showing the Finished Job page

There are no tabs for Waiting jobs and Started jobs as neither of these is the source of

an association type However when you open a Dataform for a job with a different status

and which therefore belongs to a different subset the Finished jobs page is still present

on the Dataform This is because Waiting jobs and Started jobs are subsets of the same

entity type that Finished jobs is a subset of

Figure 6-11 Dataform for job 1001 showing the Finished Job page in background

Any mandatory associations that have a subset as their source are considered optional

when an entity is not a member of the subset

Target parameters

When you create an association in the Dataform you can select a target from a picker list

Generally the picker list displays all the available instances of the target association or

entity type The Target Parameters feature allows you to constrain the available targets

for a particular association to a subset of the target relative to the associationrsquos source If

the associationrsquos source is itself an association the constraining subset may be relative to

its source

Target parameters

Advanced techniques

271

Conference room example

The following conference room example uses a constraining parameter based on a subset

of an associationrsquos source It demonstrates how an events organiser who is planning a

number of conferences simultaneously might restrict the picker list for conference session

rooms to those rooms belonging to the conference hotel Rather than setting up individual

static queries for each conference or each hotel the Target Parameters feature allows

the creation of a single dynamic solution

Figure 6-12 Part of a conference planning application

Figure 6-12 shows part of conference planning application displaying associations

of the type Hotel has room Room for two hotels each with three rooms In order to

use the Target Parameters feature the database for this application also includes a

subset of Room called Hotel has room The association type that defines the room

allocation for each session uses the subset as its target Session name in room

Hotel has room

Target parameters

Advanced techniques

272

Figure 6-13 Subset query for Hotel has room

Figure 6-13 shows the subset query for Hotel has room The association (room of

Hotel) has been added and has been marked as Required (shown with an asterisk) Hotel

has been added to the Parameters folder so that it can be used to restrict the results of the

query to those rooms in a particular hotel

Note In Set queries there is an additional parameter which appears first in the parameters list

This parameter (in this example it would be named Room) is the automatically created subset

parameter query which must not be altered or removed

Figure 6-14 Hotel selected but unrestricted choices

Figure 6-14 shows the picker list on the Dataform for selecting a hotel room for a session

before setting Target Parameters All six rooms are shown in the picker list even

though some of them are not in the Hotel that has been selected

Target parameters

Advanced techniques

273

Figure 6-15 Setting the Target parameter restrictions

To restrict the available targets for this association type open the Properties dialog and

select the Target Parameters tabbed page All the parameters of the subset query are

displayed Sentences looks for other association types that share the same source (in this

case Session name) and that have targets of the same type as the restricting parameter

already added to the subset query (in this case Hotel) In our example shown in Figure 6-

15 the association type Session name in hotel Hotel is displayed To enforce the

restriction select this association type in the Values taken from field To clear the

restriction select (not bound)

Figure 6-16 Hotel selected restricted choices


after setting Target Parameters Only the three rooms that belong to the hotel named in

the in hotel association are shown in the picker list

Target parameters

Advanced techniques

274

Allowed products example

You could construct a database schema that allowed you to select a constraining

parameter from an association that was a second or third level parent of the association

you wished to restrict The following allowed products example uses a constraining

parameter based on as subset of the source of the source of an association

In the allowed products schema shown in the diagram in Figure 6-17 represents a

situation in which a customer of a store may only buy products of a certain food type

This could be due for example to dietary restriction based on medical grounds

Figure 6-17 Allowed products schema

The constrained association is a nested one (Person customer of Store) buys

Allowed product) The constraint on the target is shown in the diagram by a thick arrow

and is based on an association with the source Person

Figure 6-18 Target parameters dialog for the buys Allowed product association

The Target parameters page of the Properties dialog for the buys Allowed product

association is shown in Figure 6-18

It would be possible to construct a schema in which the constraint is based on an

association source at a more distant level of nesting

Creating database views using profiles and chapters

Advanced techniques

275

Limitations of the Target Parameters mechanism

As illustrated by the above examples the Target Parameters mechanism can constrain the

allowed instances of an association type for a particular source This is achieved by

selecting a subset as the target type for the association type to be constrained and binding

a parameter for that subset to a schema node associated with the source

To be useful with the Target Parameters mechanism the subsets membership must be

defined by a query The query must have a parameter which when an instance is assigned

to it limits the results of the subset All parameters have a defined type To apply the

constraint the parameter must be associated with a schema node of the same type which

becomes the constraining node That node must be associated with the source of the

constrained association type by a single valued path through the schema This association

is the target parameter binding created on the Target Parameters page of the association

types properties

The following restrictions apply to the Target Parameters mechanism When attempting to

use the mechanism these restrictions may be manifested either by the desired constraining

node not being available in the Values taken from selection list or by the available

association targets being unconstrained

There are limitations on the possible paths through the schema which can link the source

of the constrained association type to the constraining node The potential constraining

nodes are defined as a set of source types contributing to the definition of the constrained

association types source and the set of targets of singular association types sourced from

those source types Specifically they are

bull the source itself

bull if the source is an association type then its source and iteratively all types along the

path of source types through the schema including but limited to when an entity type is

reached

bull the target of any association which has any of the above sources as its source provided

that the associations type is defined as singular

In addition

bull the subset parameter and the constraining node must have the same base type bull target

parameters do not work where the constrained association type uses the Combo

Checkbox or Radio button presentations

bull as queries are evaluated on the server when data has been changed on a Dataform but

not saved that change cannot affect the result of a subset evaluation including for a target

parameters constraint This is the case even where the changed data and constrained

association are on the same dataform


There are many situations in which it is useful to allow different groups of users access to

different parts of a database For example in a Human Resources application you might

want to enable all users on an Intranet to find the department phone number and physical

location of their co-workers while making sure that sensitive salary information was only

available to the small number of staff who dealt with payroll matters

In Sentences you can achieve this result by creating one profile for payroll staff and a

separate profile for all other staff These profiles would share some but not all their

chapters The following example illustrates how this is done

Database views example

A Sentences profile includes one or more chapter files which contain the schema query

and data information that make up a database However Sentences only displays entity


Advanced techniques

276

and association instances if their entity types and association types are present in the

profile

Two further rules about the use of profiles are important in this context

bull Users can only change those parts of the database for which a changes chapter is

defined in their profile (see ldquoUsing the Edit Profile dialogrdquo )

bull Users are unable to change their profiles and therefore unable to change what they can

view if the FixedProfile parameter is set to yes (see ldquoSentences Applet Parametersrdquo)

The following table shows the combination of chapters for the two profiles Staff list and

Staff Salaries

Profile Available Chapters Changes Chapter

Staff List

Staff Schema No

Staff data Yes - data changes

Staff queries Yes - query changes

Staff Salaries

Staff salaries schema Yes - schema changes

Staff schema No



The Edit profile dialog for the Staff list profile is shown in Figure 6-19

Figure 6-19 The Edit profile dialog for the Staff list profile

Users of the Staff list profile may change data and change queries but they may not

change the schema as there is no Schema changes chapter defined in this profile

The Edit profile dialog for the Staff salaries profile is shown in Figure 6-20

Creating Candidate Lists

Advanced techniques

277

Figure 6-20 The Edit profile dialog for the Staff Salaries profile

Users of the Staff salaries profile may make changes to schema data and queries as

there are three changes chapters defined in their profile One of the chapters in the Staff

salaries profile is staff salaries schema which includes the association type Person

salary Salary

Users of the Staff salaries profile see a Dataform that includes a Salary field

The file staff salaries schema is not present in the Staff list profile and as a result the

salary association type is not visible to users of Staff list profile

Users of the Staff List profile see a Dataform that does not include a Salary field


A Candidate List is a specialised kind of Dataform table that has been configured to allow

the user to select items from a pre-populated list of candidates There are two kinds of

Candidate list Item Candidates and Value Candidates

Item Candidates

Item candidate lists can be used to make the selection of a finite number of targets simple

for the end user In the Human resources example each Group Company can have

several locations In the example below a custom dataform has been created so that the

user can check the locations for a particular Group Company


Advanced techniques

278

Figure 6-22 Dataform showing an Item Candidate list

The query in Figure 6-22 has had the (Group company location Location) forward

request properties edited to change the Candidate list type to ldquoCreate Item Candidatesrdquo so

that the list of all locations is displayed and those already selected are checked This is

equivalent to changing the presentation to Checkbox but has the convenience of the Select

All checkbox

Value Candidates

With Value candidates the user can allocate amounts from one set of associations to

another within a set of constraints The example for which this functionality was created

was Cash Allocation a common requirement in many accounting applications

The Cash Allocation scenario can be modeled in several ways Here we demonstrate

schema created so that a Customer has a list of Receipts Invoices and Credit Notes

As they receive Reciepts they wish to allocate them to Invoices with an outstanding

balance The amounts can be wholly or partly allocated to one or more Invoice


Advanced techniques

279

Figure 6-23 Cash Allocation Schema

Once the Receipts amounts have been wholly allocated then they can be hidden

Similarly Invoices with no outstanding balance can also be hidden

For the schema shown in Figure 6-23 we create a Custom Dataform and edit the

properties of the (Customer this customer Invoice) forward association to change the

Candidate list type to ldquoCreate Value Candidatesrdquo The custom dataform query and

properties dialog are shown in figures 6-24 and 6-25 respectively


Advanced techniques

280

Figure 6-25 Cash Allocation custom dataform query

The custom dataform will show Receipts Invoices and Credit notes Figure 6-25 shows

how the child dataform for a Receipt will include the Receipt number the date the value

an ldquoallocated tordquo candidate list table the sum of allocated values to date the outstanding

balance and the status The Status is a derived field that either has the value ldquoFulfilledrdquo or

ldquoOutstandingrdquo to indicate whether the receiptrsquos value has all been allocated to invoices


Advanced techniques

281

Figure 6-26 Cash Allocation ldquoallocated tordquo properties

The Candidate list for Value candidates requires three properties to be set

bull The Association Type that holds the Input Value

bull The Association Type that holds the Outstanding Value

bull The Association Type to allocate values to

In Figure 6-26 the input value is the value of the receipt The outstanding value could

simply be each invoice value but in this case the invoice may be subject to a discount or

a credit note so we have created a derived type to calculate the outstanding value after

any such discount or credit has been subtracted The Allocation Value association type is

the allocated values association type Instances of this type will be created to fulfill the

invoice

Figure 6-27 Cash Allocation custom dataform


Advanced techniques

282

Figure 6-28 Cash Allocation custom dataform child

Figure 6-28 shows the child dataform containing the Candidate List for invoices The

invoices that appear in the list are determind by the query only those with an outstanding

value

Figure 6-29 Cash Allocation custom dataform child - allocated

Figure 6-29 shows after the Allocate button has been clicked The remaining pound10 has been

allocated to the first invoice on the list and the total balance and status of the receipt have

been updated

The button text ldquoAllocaterdquo on the candidate list button can be changed in the properties of

the candidate list See ldquoAssognment verbrdquo in Figure 6-26

If you manually change the allocated values then two errors may arise Firstly a value

greater than the candidates outstanding value is entered then the allocation will be

highlighted Secondly if the total allocated values are greater than the input value to be

allocated then an error message is shown Changes cannot be applied until this is

resolved

Filtering Dataform Tables

Advanced techniques

283


Whilst a Custom Dataform query allows you to limit the contents of lists and tables

sometimes you wish to dynamically change how the contents are limited rather than use a

different Custom Dataform for different contents

The Candidate List in the previous section is a good example where you only usually

desire to see outstanding Invoices and Receipts but sometimes you may wish to see all or

say the most recent for the last few months

Dataform Filters can be set on columns so that the user can choose one value More than

one filter can be used at the same time to limit the contents Usually a column with only a

few values is a good candidate for filtering a status or a type with a small number of

values such as ldquosmallrdquo ldquomediumrdquo ldquolargerdquo or 0-50 50-100 100-

A filtered column will display a filter symbol in the query definition The filter properties

also allow you to specify a default value or instance

As well as the possible values the filter list will contain Show All and Show Empty

options Show All will show all rows as if no filter is in place Show Empty will only

include rows where the value is blank or void

Limitations

Data is normally fetched in pages rather than all at once Filters are only intended to be

used on relatively small numbers of items (a few thousand) because every possible value

has to be obtained before displaying the table

Server Text Documents

LazyView functionality allows you to combine disparate data sources from Relational

Databases and Spreadsheets The Server Text Document functionality complements this

ability by allowing you to import plain text from plain text documents and Adobe

Portable Document Files (PDFs)

To facilitate this a directory on the server is used to store these text documents This is

specified in the Server properties with the property TextDocumentPath

To view Server Text Documents follow these steps


Advanced techniques

284

1 In the Sentences Explorer select Server Text Documentshellip from the Tools

menu

When the dialog opens the directory on the server will be scanned for any

changes to the contents See Figure 6-30

2 You can manually refresh the list by clicking on the Refreshhellip button

Figure 6-30 Server Text Documents Dialog

The table shows the file names the date they were last modified and their size The last

column shows the status when the file is being read and imported into Sentences The

tooltip shows additional information about PDF files such as the number of pages

You can open a Dataform to show the full details by clicking on the Open Dataformhellip

button

Figure 6-31 Server Text Document Dataform

To open the original text or PDF document click on the Open Documenthellip button

Configuration

As can be seen in Figure 3-31 the original document is stored on the Server and a context

has been added to the Tomcat webserver TextForSentences so that clients can access

the original documents This web context is set up differently for each kind of Web

server Sentences has another context for Images ImagesForSentences In the Tomcat

test server that is installed with Sentences by default these contexts are specified in the

serverxml file

The schema that stores this information is hidden by default A Specialist Schema folder

can be included that contains the schema so that it can be included in queries To make

the Specialist Schema folder visible follow these steps

1 In the Sentences Explorer select Preferences hellip from the View menu


Advanced techniques

285

2 Select the Schema Pane tab

3 Scroll down to the checkbox labelled ldquoInclude the specialist schema folderrdquo and

select it

4 Click OK to save the preferences

When the dialog closes an additional Specialist Schema folder will appear in the schema

pane This folder will also be present in the schema pane of each Query Editor

Introducing the Query Editor

Sentences queries

287

Chapter 7

Sentences queries

This chapter describes how to work with the Sentences Query Editor which is based

on the associative model of data The user interface for the Query Editor is described

in Chapter 4 ldquoThe Sentences Quick Tourrdquo

Note The Query Editor used in Sentences Version 1 is now referred to as the Set

Query Editor If you need information about using set queries and the Set Query

Editor please contact supportsentencescom

The topics described in this chapter are as follows

bull creating database queries including the use of expressions

bull the Query Editor and Dataforms

bull the Query Editor and XML

bull exporting query results


Relational databases are based on tables and relational query processors such as SQL are

based on tables and operations on tables Associative databases such as Sentences use

trees rather than tables to display their schema and data as described in the section ldquoTree

displays in the Sentences Explorerrdquo The Sentences Query Editor is based on the

Associative Model of data and uses trees and operations on trees

The Sentences Query Editor can be used to interrogate the database and also allows you

to make calculations based on the data in your results Another use of the Query Editor is

to create customised dataforms from your queries The custom Dataform displays only

those associations that are present in the query (see ldquoThe Query Editor and Dataformsrdquo )

The Query Editor is also central to Sentencesrsquo XML strategy The structure of a Sentences

query can be saved as an XML document type definition (DTD) and the results of a

Sentences query can be exported as an XML document You can use the DTD you create

from a query to build XML structures that can be used to format data created by external

applications for import into Sentences (see ldquoThe Query Editor and XMLrdquo ) You can use

XSL Stylesheets to format XML output for presentation as HTML in a Web browser

Sentences can generate an XSL stylesheet from a query according to options you select

(see ldquoXSL Stylesheet optionsrdquo )

More information on the ways in which you can use XML including how to use XML to

import data into a Sentences database is given in Chapter 8 ldquoSentences and XMLrdquo

New in version 4

Version 40 introduces new functionality to the Request Queries There are specialised

versions of queries used in the new Business Rules functions and some extensions to the

functionality that have already been covered

bull Effector Queries

Effector Queries can now produce actions such as creating or deleting data and sending

simple emails See the section on Effector Queries for details

bull Update Queries

Update Queries are similar to Effector Queries but can be executed outside the context of

Business Rules See the section on Update Queries for details


Sentences queries

288

bull Predicate Queries

Predicate Queries are a special kind of query used to define the logic that determines

which State an instance is in for a given Domain See the section on Predicate Queries for

details

bull Display Name Queries

Display Name Queries are a new use for standard queries to produce a friendlier display

name for data in the Sentences Explorer and Dataforms See the section on Display Name

Queries for details

bull State Requests

The ability to request the current state of an instance in a query is covered in the section


bull Grouping Requests

An additional filtering node has been introduced that allows you to specify how to group

results This ability covered in the section Using states in regular queries and dataforms

The Request Editor now includes a Validate Expressions menu option under the Query

menu This validates all expressions in the query which may be useful when composing

Effector Queries that you cannot execute in the Query Editor

The next sections cover the other enhancements to Sentences Queries

bull Specific Derived Type Targets

The type of a Derived Types target can now be specified so that further request nodes can

be added to it

bull Additional Expression Capabilities

New functionality such as new logical constructs and new datatype functions have been

added Datatype Functions no longer have to be prefixed with the Datatype name unless

there is an ambiguity and you need to be more specific For example You do not need to

specify TextTrim(Name) and can simply use Trim(Name) but by default the function

Now() will return todayrsquos Date If you require a Timestamp then you would need to

qualify the function as TimestampNow()

bull The Expression and Function Editors

New editors to assist in the creation and editing of query expressions

Starting the Query Editor

You can start the Query Editor to create a new query or to edit an existing query

Availability of the Query Editor

You can edit an existing query or create a new query in any profile When you create a

query you can change any of the elements in it execute the query and view the results

and export the query and the query structure

Creating a new query

To create a new query select Create Query from the Query menu or highlight the

Queries folder and select Create Query from the shortcut menu

In the Create Query dialog type in a name for your query and click Create Sentences

displays the Query Editor


Sentences queries

289

Editing an existing query

To edit an existing query highlight the name of the query in the Queries folder in the

Sentences Explorer and select Edit Query from the shortcut menu or from the Query

menu or click the Properties button on the toolbar Sentences displays the Query Editor

If a profile is available to more than one user any user may edit a query It is possible that

two users may edit the same query independently and changes made by another user

might be overwritten when the query is saved

Saving a query

Sentences does not save queries automatically If you want to keep your query you must

save it before you close the Query Editor

You can save a query only if the current profile has a chapter defined as the Query

changes chapter in the Edit Profile dialog For more information see ldquoThe Edit Profile

dialogrdquo

The setting of the EditOption parameter also controls whether or not you may save a

query If this parameter is set to schema or query you may save queries but if it is set

to data or none you may not save queries

To save a query select Save Query from the Query menu or click the Save button on the

toolbar When you close the Query Editor Sentences prompts you to save any unsaved

changes in your query

The Query Editor window

The Query Editor window is shown in Figure 7-1 The Query Editor window has three

panes The right-hand pane is the schema pane and displays schema elements When you

start a new query the whole of the schema tree is displayed After you start building your

query the Query Editor schema pane displays only those types that could be used at the

currently selected query node

The top left-hand pane shows the nodes in the query data request tree and the lower left-

hand pane shows the query results

The Results Pane can display Inactive instance in the results if the checkbox is selected

For details of inactive instances see ldquoInactive instancesrdquo

Figure 7-1 The Query Editor


Sentences queries

290

General query properties dialog

The General query Properties dialog applies to the query as a whole This dialog shares

a display with the XML Properties dialog described in the section ldquoXML properties

dialogrdquo Values set for the XML Properties dialog are defaults for the query and can be

over-ridden when a query is executed

To view the dialog select Properties from the Query menu

Figure 7-2 The Query General properties dialog

Include query parameters in results

When the query is executed the query parameters that were chosen will be included in the

results They will be included whether run in Sentences or exported as XML

Automatically refresh custom dataform fields

Dataforms have an ldquoauto-refreshrdquo facility where calculations are updated whenever the

user changes any fields This property allows you to set whether ldquoauto-refreshrdquo is on or

off by default

Description

You can enter a text description for the query

Database queries

The Sentences Query Editor like the Sentences Explorer uses a tree-shaped structure A

Sentences query takes the form of a request tree made up of request nodes which

represent associations and entities you choose as well as sorting and selection nodes and

derived type nodes and derivations used for calculations

Building the request tree

When you create a new query Sentences displays a blank Query Editor You must select a

suitable starting point for your query which is known as the data request node You then

select other nodes one step at a time and build a ldquopathrdquo through the schema until you

have all the data needed for your query


Sentences queries

291

Figure 7-3 An empty Query Editor for a new query

Creating the data request node

When you create a new query Sentences displays an empty Query Editor as shown in

Figure 7-3 To create the data request node select an entity type or association type and

drag it over the ltEmpty Querygt placeholder to form the root of the request tree as

shown in Figure 7-4 Alternatively you may use Copy and Paste commands (with the

toolbar buttons or menu commands or standard shortcut keys)

Figure 7-4 Adding the data request node

The data request node is the starting point of the query and all the other information in the

query is relative to it The data request node can be an entity type or a forward or an

inverse association type The direction of the association type (forward or inverse) is

maintained in the data request node

Changing the data request node type

When prototyping you may create a new query based on one type and subsequently

realise that it should have been based on a related type a subtype supertype superset or

subset You can change the Data Request schema type to a related type by selecting the

Change Typehellip menu item from the edit menu or the popup menu


Sentences queries

292

Adding Forward and Inverse Nodes

You can add any number of forward and inverse nodes to the data request node as long as

the source (or target) of the association type is equivalent to the data request node You

can add associations that relate to the data request node or to subsets or supertypes of the

data request node or to equivalent types

You can add more forward or inverse nodes to the data request node or to any other node

and you are only limited by the available schema You may add child nodes based on

superset or subtype associations as if they were associations of the current parent node

If you add an inverse node where its source is itself an association type then all nodes

required for that association type are added to the request tree

To add a node drag the node from the schema pane and drop it on a node in the query If

the source or target of the new node matches the existing node then the new node is

added as a child of the existing node

To add multiple nodes highlight a node in the request tree and select Associations from

the Add submenu of the Edit menu or from the shortcut menu as shown in Figure 7-5

Figure 7-5 Using the shortcut menu to add associations

The following options are available for adding associations

bull Associations

displays the Add Associations dialog

bull Instance Specific Associations

adds all the instance specific associations This option is only enabled if the current

node is bound to an instance If no instance-specific associations exist for an

instance Sentences displays an error message if this option is selected

The Add Associations dialog shown in Figure 7-6 lists all the possible associations that

may be linked to the node selected in the Query Editor

You can control the associations displayed in this dialog by selecting one or both of the

Forward and Inverse check boxes

To select an association click on it with your mouse You can use Shift+click and

Ctrl+click to select multiple adjacent or non-adjacent associations

You may automatically add page nodes for the selected associations by selecting the Add

page nodes checkbox If this box is checked a page node is added whenever the

association to be added has a source type that is different from the selected node


Sentences queries

293

After selecting the associations you wish to add to the query node click Add To return to

the Query Editor without adding associations click Cancel

Figure 7-6 The Add Associations dialog

An illustration of the result of adding Associations is shown in Figure 7-7

Figure 7-7 A data request node with forward Associations added

The associations added in the example shown in Figure 7-7 are grouped into pages for

each supertype equivalent type and subset Associations from the data request node type

are not put on a page (see ldquoPage Nodesrdquo )

Using drag and drop and cut copy and paste in the Query Editor

You can use the standard drag and drop and copy and paste mechanisms in the Query

Editor to create forward and inverse nodes to create Parameters to copy or move nodes

to bind nodes and to place nodes for display purposes on defined page nodes

If you drag and drop a request node onto one of its siblings (another node in the query that

has the same parent node) the order of the siblings is changed to place the dragged node

before the node it was dropped onto This also applies when you drag a Page node and

drop it onto another Page node

If you drag a request node that is not a Page node and drop it onto a sibling Page node

the dragged node is placed on that Page

If you drag and drop an association type onto an existing request node Sentences creates

a forward or inverse request node if its source or target matches


Sentences queries

294

If you drag and drop an entity or association type onto the Parameters folder then a new

Parameter of that type is created with the type name If you drag and drop a data instance

onto the Parameters folder then it is used as the default value

You can use the standard drag and drop and copy and paste to reorder nodes at the same

level in the tree or to copy or move them to another part of the tree

If you drag and drop an existing request node onto another request node of a related type

(such as a superset or subtype) the branches of the request nodes are merged

This means that the child nodes of the dragged node are copied iteratively onto therequest

node onto which it was dropped Only one Sort node is allowed at any one level of the

data request tree If the merging of branches were to result in a duplication of Sort nodes

then the Sort node being dragged is ignored and not copied

Result Trees

The result of a Sentences query is a tree of entity and association instances When you

execute a query the Sentences query processor retrieves instances of the entity type or

association type corresponding to the data request and processes each one For each

instance it processes the query processor looks at the immediate child nodes of the data

request and uses each one to retrieve a set of association instances which it adds to the

growing result tree For each instance that it adds it looks at the children of the

corresponding request nodes and adds further sets of association instances This recursive

process is carried out to any depth required The result is a tree of data whose shape is

derived from but not identical to the request tree

The root node of the result tree is not shown in the query result tree Each request node

generates one or more sets of result nodes each result node is derived from one and only

one request node The result tree can be displayed in the Sentences Explorer or in the

Query Editor

Displaying query results

To display the results in the Query Editor click the Execute button on the toolbar or select

Execute Query from the Results menu When query results are displayed in the Query

Editor results pane the instances are shown with green icons rather than with the cyan

icons used for data instances in the Explorer

Figure 7-8 Results displayed in the Query Editor

In the example shown in Figure 7-8 the data request has the root node Employee and

the child nodes address home telephone and work telephone The results pane


Sentences queries

295

shows a list of employees and the corresponding association instances for address and

home telephone for each employee

If there are no results that match the query request Sentences displays the message No

results match your query

You can display a Dataform for a query result instance in the Query Editor Highlight the

instance and click the Default Dataform button on the tool bar or select Default

Dataform from the shortcut menu


When you execute a query you request data from the Sentences server and after

evaluating the query Sentences returns a number of data items up to the limit specified in

the RequestSize parameter (see ldquoAdditional optional parametersrdquo ) Occasionally this data

retrieval action may take a long time for example because the query is very complex or

because the RequestSize parameter is set to a high value




The Stop button is available in the Sentences Explorer and in the Query Editor You can

only stop a data retrieval action by using the Stop button in the same window that started

it You cannot for example use the Stop button in the Explorer to stop a data retrieval

action started in the Query Editor

Displaying query results in the Sentences Explorer

You can execute a query in the Sentences Explorer by highlighting the query name and

selecting Execute Query from the Query menu or from the shortcut menu The query

results are displayed in the data pane

You can also execute a selected query by selecting Reload Data from the File menu or

clicking the Reload Data button on the toolbar or by pressing F5

Although the top level of the displayed query results may resemble a list of entity or

association instances remember that the only nodes shown in the query result tree are

those that correspond to nodes in the data request tree The query may include conditions

that result in only certain instances being displayed in the query result This means that

the results tree of instances is likely to be different from the data tree of instances for the

same schema type

When query results are displayed in the Sentences Explorer data pane the instances are

shown with green icons rather than with the cyan icons used for data instances

You can display a Dataform for a query result instance in the Sentences Explorer

Highlight the instance and click the Default Dataform button on the tool bar or select

Default Dataform from the shortcut menu

The query results can include the query parameters that were chosen for this execution

To include parameters in the results check the box ldquoinclude query parameters in resultsrdquo

in the General tab of the Query Properties The parameters will be output to the Query

Editor Sentences Explorer and XML or CSV outputs

Expanding and Collapsing

The query result tree includes expand node and collapse node buttons which act in the

same way as the equivalent menu commands in the Sentences Explorer


Sentences queries

296

Binding Nodes

The Sentences Query processor returns all the instances of the type that the data request

node refers to and builds a branch of the result tree from each one

You can limit the amount of data returned by the query processor by defining a restriction

on a particular node The restriction you define limits the results returned for the node to

one specified instance and is known as binding a node

If you have a multiple association and bind the results to a particular instance Sentences

still regards the association as multiple for the purposes of calculations in expressions

There are three ways to bind a request node You can bind a node

bull to an entity or association instance

bull to another request node

bull to a parameter

Binding to an instance

You may bind any type node in your request tree to an instance which limits your results

to those that refer to that instance

If you bind the data request node Sentences builds a result tree with only a single main

branch based on the instance specified

If you bind any other request node the results for that node are limited to the specified

instance The results for the immediate parent node are also limited to that instance if the

bound request node is a source or target request

If you want to display only those nodes that are bound to the instance you specify define

the parent node of that instance as Required

If a source or target request node is bound to an instance its parent request may still

produce more than one result as there may be more than one association between the

same source and target

To bind a node to an instance

To bind a node to an instance highlight the node and select Bind to instance from the

Edit menu You can also open the shortcut menu select the Edit submenu and then

select Bind to instance Sentences displays a picker list showing the available instances

Alternatively you may use drag and drop to bind a query node to an instance If you drag

an instance from the Query Editor results pane or from the Explorer data pane and drop it

onto a request node of the same type Sentences binds the request node to that instance

To cancel binding to an instance highlight the node and select Clear instance binding

from the Edit menu You can also open the shortcut menu select the Edit submenu and

then select Clear instance binding

The example shown in Figure 7-9 shows the node Hyperlink bound to the instance

johnatkinssleepysoftcom The parent node is also designated as a required node

(indicated by an asterisk) The results pane shows the only instance of employee that has

the specified Hyperlink


Sentences queries

297

Figure 7-9 Request node bound to an instance

Binding to a Request Node

In some queries a parent node may have a child or descendant node that is an inverse

association type that has a source that is of the same type as the parent node The result

tree for this query would have a separate branch for each instance of the parent node but

the inverse association type node would return instances relevant to all the instances of

the type not just those for the current instance of the parent node To prevent this from

happening you can bind the later occurrence of the type to the first occurrence in the

parent or ancestor node This ensures that the results in a specific branch are related only

to the defining instance of the parent node for that branch

To bind a node to a request node

To bind a node to a request node highlight the node and select Bind to node from the


select Bind to node Sentences displays a picker tree and only allows you to select one of

the appropriate nodes for the binding action

To cancel binding to a node highlight the node and select Clear node binding from the


select Clear node binding

Binding to a Parameter

If you create a parameter that has the same name as one of the nodes in your query

request tree the node is automatically bound to the parameter When you execute the

query the effect of binding to a parameter is the same as binding to an instance For more

details on using parameters in queries see ldquoQuery Parametersrdquo If two or more nodes

have the same name they are all bound to the parameter and therefore you may want to

rename one or more of the nodes before binding to a parameter

Selection Sort and Derived type nodes

You can modify the results returned by a query by adding additional nodes to the query

tree These nodes can

bull specify calculations to be carried out using the query results (a derived type node or a

derivation) These are discussed separately in the section ldquoDerived types and derivationsrdquo

bull restrict the results returned by another request node by applying a filter condition (a

selection node)

bull cause the results returned by another request node to be sorted (a sort node) Every

operator request has an expression associated with it which defines the calculation or


Sentences queries

298

filtering to be carried out An operator request affects the results generated by its

immediate parent

Figure 7-10 Query showing sort selection and derived type nodes

Selection nodes

A selection node acts as a filter on its parent node The selection node has an expression

associated with it which represents a condition that must be true for each instance to be

returned

As shown above you can also select data in a query by binding one or more nodes (see

ldquoBinding Nodesrdquo ) When using a large database if you expect the majority of instances

being filtered to match your selection criteria using a selection node should produce

faster results If you expect only a minority of instances to match your criteria then

binding to a node with the Required property set should produce faster results You may

need to experiment to find the best solution for your requirements

To create a selection node

1 Highlight the node and select Selection from the Add submenu of the Edit menu or the

shortcut menu

Sentences adds a Selection node with an attached expression node as shown in Figure 7-

10

2 The selection node is automatically selected and available for editing Add the the

expression for your selection criteria For more details about expressions see ldquoUsing

expressions in queriesrdquo

To edit the selection expression on other occasions select Edit Expression from the

shortcut menu for the expression node

Note Selection nodes do not appear in results and cannot be referenced and therefore

they do not have names and cannot be named or renamed

To delete a selection node

1 Highlight the node and select Delete from the Edit menu or click the Delete button on

the toolbar

An example of a Selection node is the ldquoSelectionDatelt=DateNow()rdquo node shown

in Figure 7-10 This is part of the Latest Salaries query in the Human resources

example application In this example salaries are selected by dates in the expression


Sentences queries

299

Datelt=DateNow() which uses a Date datatype method Now() There is more

information on expressions and datatype methods later in this chapter (see ldquoUsing

expressions in queriesrdquo ) This expression selects those salaries that are associated with

dates that are less than or equal to todayrsquos date

Sort nodes

By default a request node returns results in the order that they are returned by the

database Entity instances are sorted and association instances are either sorted or

sequenced depending on the properties of the association type You can override this

behaviour by adding a sort node to the request tree

Each node can have one sort node which acts on its parent node Sort nodes cannotbe

named

To create a sort node

1 Highlight the node that you wish to sort and select Sort from the Add submenu of the

Edit menu or the shortcut menu

You can specify the sort direction by adding an A (for ascending) or a D (for

descending) to the sort expression You must use a comma to separate the direction

indicator from the identifier in the expression

You can use multiple sort identifiers separated by semi-colons ()

An example of a Sort node is the ldquoSortDate Drdquo node shown in Figure 7-10 This is

part of the Latest Salaries query in the Human resources example application In this

example salaries are sorted in descending order (D) of date

To delete a sort node

1 To delete a sort node highlight the sort node and select Delete from the Edit menu or

click the Delete button on the toolbar

Derived types and derivations

You can add the results of calculations to your query results by adding calculated nodes

and targets Nodes that contain calculated results are known as derived types and targets

that contain calculated results are known as derivations

In Chapter 11 Worked examples there is an example of the use of derived types and

derivations and their affect on a custom Dataform For more details see ldquoDerivations

examplerdquo

Derived type nodes

At any node you can add one or more derived type nodes A derived type request causes

new values to be generated according to an expression that you define You can rename

the derived type to give it a meaningful name This name is used as the ldquoverbrdquo of the

association that is created to hold the result of the derived typesrsquo expression

You can add one or more derived type nodes to the query node itself These derived type

nodes apply to the whole query A derived type node is evaluated once for each result

instance that its parent node returns and just once if its parent is the query node

If a derived type added to the query node contains no references to the data request node

or any of its child nodes (the main data request tree) then it is called ldquoindependentrdquo and

can be calculated before the data request This means that it will be calculated before the

main data request tree and can be referenced in expressions in the main data request tree

without any circular reference problems

This kind of node allows us to have references to global ldquoSystem Parametersrdquo and use

them within the data request tree If the derived type is given a specific result type then


Sentences queries

300

that target can be bound to an instance in the database used to store globally referenced

constants or indices

If a derived type added to the query node is independent then by default it will be

calculated first before the main data request tree If you wish it to be calculated at the end

then you can specify for it to do so in the properties and from the context menu For

example if the derivation expression is ldquoTimeNow()rdquo and is used to note when the query

finishes executing you would wish to change when the derived type is calculated

To create a derived type node

1 Highlight the node and select Derived type from the Add submenu of the Edit

menu or the shortcut menu

Sentences adds a Derived type node with an attached expression node and opens

the properties dialog

2 Enter a name for the Derived type node

3 Click on the Edit button and use the Expression Editor to create your expression

For more details about expressions see ldquoUsing expressions in queriesrdquo

4 When you have finished creating your expression and return to the Properties

dialog the Resulting and Existing Datatypes will be displayed You can choose

to change the existing datatype to match the suggested one Note that it is not

always possible to determine the resulting datatype and so you may have to

manually choose an appropriate one

To edit an existing derived type expression select Edit Expression from the shortcut

menu for the expression node or double click the expression

An example of a derived type node is the latest salary node shown in Figure 7-10 This

is part of the Latest Salaries query in the Human resources example application

In this example salaries have been selected by date and sorted in descending date order

The derived type node uses the group function First() to select the first salary in the

ordered list of salaries produced by the selection and sort nodes

Derived type node properties dialog

The Properties dialog for a derived type node is shown in Figure 7-11 More information

about the Format page is in the section ldquoQuery node Format properties pagerdquo and full

details are in the section ldquoFormat properties pagerdquo For details of the settings on the

Presentation page see the section ldquoDatatype properties pagerdquo The User Help page allows

you to enter the help text to be displayed to the user of a dataform when they request help

for the field corresponding to this request

The Read-only on dataform property on the Format properties page is always checked

for derived types

You can use this Properties dialog to set a datatype and the corresponding format

options and these are saved with the query Data values returned by the derived type are

displayed using the datatype and format options that you define


Sentences queries

301

Figure 7-11 The derived type node Properties dialog

To view the derived type properties dialog highlight the derived type node and select the

Properties tab The resulting datatype and settings can also be set on the same property

page

Note Checking or clearing the Instances are values checkbox on the derived type node

Properties dialog has no effect on the output of the query

Default Targets and Derived Targets

A create dataform can populate a field using a default target or a derived target a

calculated field If an edit dataform is opened and such a field is empty it will also be

populated with the default target A calculated derivation replaces the original target of

the association on which it is set

Default Target and Derived Target functionality has been normalised into one property

page for requests There is an equivalent property page for Schema and those values will

be used as defaults in query request nodes

If the Association Type is used in an Inverse request then it is the source that is derived

rather than the target

A Derived Target can be either a specific instance or a derivation


Sentences queries

302

For a detailed example of the use of derived types and derivations and their affect on a

custom Dataform please see the ldquoDerivations examplerdquo

Recalculation rules for derivations

When you create a derivation you can define when its value is recalculated The

recalculation options are given in the section ldquoDerivation propertiesrdquo The available

options are determined by whether or not the association type to which the derivation is

attached is read-only and whether or not the derivation itself is editable or not

The Read-only property of the association type is set on the Format page of the parent

nodersquos Properties dialog The Editable property of the derivation is set on the

Derivations page of the Query node properties dialog If an association is Read-only it

cannot be Editable


Sentences queries

303

Derivation properties

A Properties dialog that includes a Derived Target properties page is available for

forward nodes in a query whose targets are calculated as derivations (see ldquoDefault Targets

and Derived Targetsrdquo) The properties dialog also includes the Dataform navigation page

as described in (see ldquoQuery node Dataform properties pagerdquo) and the Format page

To view the Derived Target properties page select Properties from the Edit menu or

from the shortcut menu on the node

Figure 7-12 The Derived Target properties dialog

bull If the association type is multiple the only available calculation option is Calculate

once In this case the derivation is effective only when no instances of the association

type exist for this source When one or more instances already exist the derivation does

not create new instances

bull If the association type is singular and read-only the derivation editable property is

always Not Editable In this case the calculation options are

bull Calculate once for example to set the date the invoice was created

bull Only calculate on ldquoSaverdquo for example to calculate an account balance or to set the

date last saved

bull Calculate always for example to calculate an invoice line total In all these cases the

derivation field cannot be edited by the user

bull A derivation with the recalculation option Only calculate on ldquoSaverdquo is only

recalculated if it appears on a parent Dataform or on a child Dataform whose parent is a

custom Dataform

bull If a derivation is shown on a child Dataform whose parent is a base Dataform do not

use the Only calculate on ldquoSaverdquo option Use Calculate once or Calculate always

bull If the association type is not defined as read-only the derivation Editable property can

be set to either Editable or Not Editable If it is set to Not Editable the calculation

options are identical to those given above However if the derivation property is Editable

the calculation setting is

bull Calculate once

In this case the derivation field is always editable by the user


Sentences queries

304

The following table summarises the permissible combinations for singular association

types (for multiple association types the only setting allowed is Calculate once)

Association type read-only

property

Derivation editable property Calculation setting

read-only=yes not editable Calculate once

read-only=yes not editable Calculate on ldquoSaverdquo

only

read-only=yes not editable Calculate always

read-only=no not editable Calculate once

read-only=no not editable Calculate on ldquoSaverdquo

only

read-only=no not editable Calculate always

read-only=no editable Calculate once

Editing a derivation expression

To edit a derivation highlight a node in the Query Editor and choose Edit Derived

Target from the Edit menu

To clear a derivation open the properties for derived target and select None

Specific derived type targets

Version 40 introduces the ability to define the type of a Derived Types target This means

that further request nodes can be added to the target

The derived type is singular so either a derivation or a bound instance must be specified

to determine the target instance This functionality is intended for use when needing to

associate with reference data that does not change frequently For example some global

parameters to an application that depend on region or business unit

Using expressions in queries

You can use expressions in derived types derivations and selection operator statements

in Sentences queries

The calculations in a derived type node can use identifiers based on node or parameter

names (the equivalent of variables) constants which may be a string or a numeric value

arithmetic operators comparison operators wildcards and logical connectives (all listed

in the tables below) Calculation expressions may also make use of Datatype methods and

type constructors In addition the derived type node can use a number of group

expressions and the selection operator can use the special conditional function

Exists()

Expressions are always evaluated from left to right so you should take care to place the

most specific datatype (such as Currency a specialised type of Number) on the left hand

side of any expression before any general datatype (such as Number)


Sentences queries

305

Expression syntax for queries

The following BNF grammar shows how expressions in Sentences queries are parsed

FilterExpression = ConditionalExpression ltEOFgt

RequestQueryExpression = ScalarExpression ltEOFgt

Assignment = Id = ScalarExpression

ConditionalExpression = ConditionalInclusiveOr

ConditionalInclusiveOr = ConditionalExculsiveOr ( ( | | ltORgt )

ConditionalExculsiveOr ) ConditionalExculsiveOr = ConditionalAnd ( ^ ConditionalAnd

)

ConditionalAnd = UnaryConditional ( ( amp | ltANDgt )

UnaryConditional )

UnaryConditional = ( | ltNOTgt ) (

ConditionalExpression )

| ConditionalPrimary

| ltEXISTSgt ( Id )

ConditionalPrimary = ( ConditionalExpression )

| ScalarExpression ComparisonCondition

ComparisonCondition = = ScalarExpression

| == ScalarExpression

| = ScalarExpression

| ltgt ScalarExpression

| lt ScalarExpression

| gt ScalarExpression

| lt= ScalarExpression

| gt= ScalarExpression

| LikePredicate

LikePredicate = ( ltNOTgt ) ltLIKEgt ScalarExpression

ScalarExpression = IfStatement

| ConcatPart ( ( || | ltCONCATgt )

Concat Part

IfStatement = ltIFgt ConditionalExpression ltTHENgt

ScalarExpression ltELSEgt ScalarExpression

ConcatPart = ScalarTerm ( + ScalarTerm | -

ScalarTerm )


Sentences queries

306

ScalarTerm = ScalarFactor ( ScalarFactor |

ScalarFactor )

ScalarFactor = - ScalarPrimary

| ScalarPrimary

ScalarPrimary =

| FunctionCall

| MethodCall

| Default

| Literal

| ID

| ltVOIDgt

| ( ScalarExpression )

FunctionCall = ltIDENTIFIERgt ( ( ScalarExpression )

)

MethodCall = ltIDENTIFIERgt ltIDENTIFIERgt ( (

ScalarExpression ( ScalarExpression

) ) )

Default = ltDEFAULT_VALUEgt ( ScalarExpression

DefaultLiteralValue )

DefaultLiteralValue = FunctionCall

| Literal

Id = ltIDENTIFIERgt ( ltIDENTIFIERgt )

= ( ltINTEGER_LITERALgt )

| ( ltFLOATING_POINT_LITERALgt )

| ( ltSTRING_LITERALgt )

In this BNF grammar listing FilterExpression is the starting point for Selection

expressions and RequestQueryExpression is the starting point for derived type and

derivation expressions

FunctionCall indicates either one of the group functions for example Sum(x) or a

datatype constructor for example MixedCurrency(ldquoGBP100rdquo) and MethodCall

indicates a Datatype method for example DateNow()

Arithmetic and Concatenation operators

The arithmetic and concatenation operators that are supported in derived type and

selection node expressions are

Precendence Operator Meaning

Highest - Unary Minus

Multiply

Divide

+ Add

- Subtract

Lowest || Concatenate

If either side of an add subtract multiply or divide operator has no value the operator

returns no value


Sentences queries

307

If either side of add or subtract operator has the zero token output from a Sum() method it

is treated as a zero with the datatype of the other side of the operator If both sides of the

operator have the zero token the operator returns the zero token

If either side of the multiply operator has the zero token the operator returns the zero

token With the divide operator any value divided by the zero token returns no value and

the zero token divide by any value returns the zero token

If the input to the singular negate operator (the unary minus) has no value the operator

returns no value If the input to the singular negate operator (the unary minus) is the zero

token the operator returns the zero token

If either side of the concatenate operator has no value the operator returns no value

bull Arithmetic operators example

The following example illustrates the precedence of the arithmetic operators An

expression in the format

-4 + 6 2

returns the result

-1

as the divide operation is evaluated before the add operation The use of parentheses can

change the order of evaluation An expression in the format

(-4 + 6) 2

returns the result

1

bull Concatenate operator example

In a schema with entity types FirstName and LastName and with entity instances Mary

and Jones respectively an expression in the format

FirstName || ldquo rdquo || LastName

returns results of the type

Mary Jones

The expression includes a blank space in inverted commas which appears between the

FirstName and LastName instances

Further operations on strings can be performed using the string methods on the Text

datatype (see ldquoDatatype methods examples Text datatype string methodsrdquo )

Comparison operators

The comparison operators that are supported in selection node expressions are

Operator Meaning

= Equals

== Equals

= Not equals

ltgt Not equals

lt Less than

lt= Less than or equal to

gt Greater than

gt= Greater than or equal to

LIKE Pattern Match

NOT LIKE Negative Pattern Match


Sentences queries

308

If either side of a comparison operator has no value then the comparison operator

expression returns no value If either side of a comparison operator is the zero token

output from a Sum() method the token it taken as being a zero (0) in the datatype on the

other side of the comparison operator If both sides of the comparison operator have the

zero token the values are assumed to be equal

bull Comparison operators example NOT LIKE

Given a schema with an entity type LastName and entity instances of various names an

expression in the format LastName NOT LIKE ldquoJonesrdquo returns results that include all

names that do not match Jones Used in this way the LIKE and NOT LIKE operators

return the same results as = (equals) and = (not equals) The LIKE and NOT LIKE

operators may also be used with wildcards as shown below

The LIKE and NOT LIKE operators are not case-sensitive

Wildcards

The wildcards that are supported in selection node expressions are

Wildcard Character Meaning


matches from zero to any number of

characters

If you want to use either of the wildcard characters as part of your pattern you need to

ldquoescaperdquo the character with a backslash as follows




characters

represents a literal character

a single backslash causes an error in query expressions

You can use these wildcards with comparison operators such as LIKE and NOT LIKE

and in the Sentences Explorer Filter tool

bull Wildcards example LIKE with

In a schema with an entity type LastName and entity instances of various names an


LastName LIKE ldquoJonsrdquo

returns results that include names such as Jonas Jones Jonsons and so on

bull Wildcards example using an escaped wildcard character

In a schema with an entity type Description and entity instances of text strings that may

end in a question mark () character an expression in the format

Description LIKE ldquordquo

returns any instance of Description that ends in a question mark () character


Sentences queries

309

Logical connectives

The logical connectives that are supported in selection node expressions are listed below

You can either use the special character shown or the English alternative for each

connective

Character Alternative Meaning

amp AND And

| OR or (inclusive)

^ XOR or (exclusive)

NOT not

|| CONCAT concatenate

bull Inclusive or

The inclusive or is represented by ldquo|rdquo The expression ldquoA|Brdquo means ldquoeither A or B or

bothrdquo

bull Exlusive or

The exclusive or is represented by ldquo^rdquo The expression ldquoA^Brdquo means ldquoeither A or B but

not bothrdquo

bull Logical connectives example amp

In a schema with entity types FirstName and LastName and with entity instances

David and Jones respectively an expression in the format

FirstName = ldquoDavidrdquo amp LastName = ldquoJonesrdquo

returns only those results for which both conditions apply that is where the FirstName is

David and the LastName is Jones

The operators AND OR and XOR are case-sensitive and must always be entered in

capitals The operators NOT and CONCAT are not case-sensitive

Logical connectives behaviour with missing values

The following list shows the output of the logical operators if one side of the operator has

no value

Operator Left Hand Side Right Hand Side Result

OR True True False or no value True

False True True

False False False

False no value no value

no value True True

no value False no value

no value no value no value

AND True True True

True False False

True no value no value

False True False or no value False

no value True no value

no value False False


Sentences queries

310



XOR True True False

True False True


False True True

False False False



NOT True - False

False - True

no value - no value

Conditional operator

You can use a conditional operator in a derived type derivation or selection expression

The operator requires the three keywords IF THEN and ELSE The operator is not valid

unless all three keywords are present The syntax for a conditional operator expression is

as follows

IF Condition THEN trueValue ELSE falseValue

The condition can be any statement using a comparison operator

bull Conditional operator example

To return the name of an Employee except when that person is the manager use the

conditional operator in an expression in the following form

IF Employee=ldquoBarney Norrisrdquo THEN Employee ELSE ldquothe managerrdquo

For this expression if the Employee is not Barney Norris the expression returns the

Employee name otherwise it returns the string ldquothe managerrdquo

The three keywords IF THEN and ELSE are case sensitive and must always be entered

in capitals

The conditional operator cannot be used as the only term in a Selection expression as

Selection expressions require a Boolean result (true or false) which the conditional

operator does not return Selection conditions can be created using one of the comparison

operators

To create a Selection expression which is conditional use the conditional operator in a

derived type expression followed by a Selection expression that refers tot the derived

type for example

Derived Type(IF(Exists(Phrase)) THEN( || Phrase || ) ELSE())

Selection(Title LIKE Derived Type)

Using Void in an expression

You can instruct Sentences not to create an association in a query result if a particular

result is not found by using the token VOID in a conditional expression

bull Void example

If you only want to output an association that represents the number of employees when

that number is greater than 3 use the following expression


Sentences queries

311

IF Count(Employee)lt3 THEN VOID ELSE Count(Employee)

The VOID token is case-sensitive and must always be entered in capitals

Exists Conditional function

The Exists() conditional function can be used to restrict results of a parent request

based on whether a child request has any results This function is used to limit the display

of results in the results tree to those branches where an instance of the specified node

exists

The argument of the Exists() conditional function must be an identifier It may not be

a complex expression

You should compare the result of using this function result with the result of defining a

node as Required (see ldquoRequired nodesrdquo )

You can combine the Not operator ldquordquo with the Exists() conditional function in the

format (Exists()) to restrict results of a parent request based on whether a child

request does not have any results This is useful as there is no negative equivalent of the

Set Required function

bull Exists conditional function example

In a schema with the association type Person visits store adding a Selectionnode to

Person with an expression in the format

Exists (Store)

returns only those Person instances for which the Person visits Store association

exists

The Exists operator is not case-sensitive

Default value

You can set a default value for a type that you wish to use in an expression The default

value must be an instance of the selected type Setting a default is the equivalent of using

the Exists() conditional function in a conditional expression

bull Default value example

In a schema with the entity type Employee and a number of Employee instances you

can define Barney Norris as the default Employee with either of the following

expressions

IF Exists(Employee) THEN Employee ELSE ldquoBarney Norrisrdquo

or

DEFAULT(Employee ldquoBarney Norrisrdquo)

The DEFAULT operator is case-sensitive and must always be entered in capitals

Using parameters in query expressions

You can use a parameter in a query expression (see ldquoQuery Parametersrdquo )

In many cases you may use the parameter name directly in an expression However if you

use a parameter name and there is a query node with the same name the value returned is

the value of the query node and not that of the parameter

To make sure that you get the value of the parameter use the GetParameter function

This function takes the name of a parameter as its argument The parameter name must be

a string inside quotation marks

For example GetParameter(ldquoPersonrdquo) returns the value of the query parameter

Person


Sentences queries

312

Using user-defined parameters


for servlet access and refer to them in query expressions For details of how to use these

parameters see User-defined parameters

To refer to a user-defined parameter use the GetClientParameter method with the

name of the parameter in the query expression Optionally you may add a default value to

the query expression which is used if no value is defined for the parameter

bull User-defined parameters example

If your HTML startup page includes a user-defined parameter in the format

ltPARAM NAME=ClientParameter1 VALUE=CP1=Barney Norrisgt then a

query expression in the format GetClientParameter(CP1) returns the value

Barney Norris


ltPARAM NAME=ClientParameter2 VALUE=CP2=gt

then a query expression which includes a default value in the format

GetClientParameter(CP2Mary Venice) returns the value Mary Venice

The default value you specify in the query expression is returned whenever Sentences

cannot return the value from the user-defined parameter for example when the

specification is missing or incomplete

Using conditionals to check for parameter values

If either side of a comparison operator has no value the expression returns no value If

either side of one of these operators uses a parameter and that parameter has no value the

expression returns no value

You can use a conditional expression or use the Exists() conditional function to

check for the existence of parameter values and to substitute a value if none exists

Group functions

The group functions that are supported in derived type and selection node expressions are

Function Meaning

Count() Returns the number of values

CountDistinct() Returns the number of distinct values

Sum() Returns a sum of the values

Average() Returns the average of the values

Min() Returns the lowest value

Max() Returns the highest value

First() Returns the first value

Last() Returns the last value

StdDev() Returns the standard deviation of the values

StdDevSample() Returns the sample standard deviation of the values

Group functions can also take an expression as their argument

If the Sum() or Count() group function has no input values it returns a special zero

token (see ldquoExpressions that give the zero token as their resultrdquo) If the Average()

group function has no input values it returns no value

The CountDistinct() function is similar to the Count() function except that it

counts the number of distinct values rather than the number of values Repeated values

are counted many times by Count() but are counted only once by CountDistinct()

Note that CountDistinct() compares values by name not by their internal identifiers


Sentences queries

313

For example if you are counting instances of the entity type Person and there are two

Persons named John Smith they are counted as one instance

bull Group functions example Max()

In a schema with an association type ((Company orders Product) on Date) you

could construct a query to return the date of the latest order using a Derived type named

LastOrderDate with an expression in the format Max(Date)

Datatype methods

Datatype methods can be used in derived type and selection node expressions For a

complete list of functions see the section ldquoAdditional Expression Capabilitiesrdquo

bull Arithmetic operations with Date and Time datatypes

The following arithmetic operations are supported with the Date datatype

date + number

adds number of days to the date of date

date ndash number

subtracts number of days from the date of date

date1 - date2

computes the number of days that date2 is earlier or later than date1

The following arithmetic operations are supported with the Time datatype

time + number

adds number of seconds to the time of time

time ndash number

subtracts number of seconds from the time of time

The following arithmetic operations are supported with the Timestamp datatype

timestamp + number

adds number of seconds to the time of timestamp

timestamp ndash number

subtracts number of seconds from the time of timestamp

bull Datatype methods examples Date Time and Timestamp datatypes

The following expression is an example of the method GetDayofWeek(date) The

(date) part of this expression shown in the example is a type constructor for the Date

type (see ldquoType constructorsrdquo ) You may also use a variable of the type Date

DateGetDayofWeek(Date(ldquo150302rdquo) )

returns a numeric value representing the day of the week for 15th March 2002 (where

Monday=1 Tuesday=2 and so on) The value returned in this example is 5 representing

Friday

The other DateGet methods also return numeric values

DateGetYear(date) returns a numeric value equal to the year

DateGetMonth(date) returns a numeric value representing the month (where

January=1)

DateGetDay(date) returns a numeric value equal to the day of the month

The following examples of expressions use the Date datatype and may be applied equally

to expressions using the Time or Timestamp datatype as well

These examples use an entity type LastDate


Sentences queries

314

The following expression is an example of the method AddDays(date num) DateAddDays(LastDate 5)

returns a new date that is 5 days after LastDate without altering the value of LastDate

The following expression is an example of the method AddMonths(date num)

DateAddMonths(LastDate 5)

returns a new date that is 5 months after LastDate without altering the value of

LastDate

The following expression is an example of the method AddYears(date num)

DateAddYears(LastDate 5)

returns a new date that is 5 years after LastDate without altering the value of LastDate

The Now() method for the Date Time and Timestamp datatypes takes its value from

the time clock on the machine running the Sentences server

bull Datatype methods examples Currency and MixedCurrency datatypes

The following examples use an entity type MyCurrency which is a number with the

Currency datatype assigned

The following expression is an example of the method Convert(source iso code

source cur factor target iso code) for Currency MixedCurrencyConvert(ldquoGBPrdquoMyCurrency161 ldquoEURrdquo)

converts an amount of MyCurrency in pounds (GBP) to Euros (EUR) using the exchange

rate 161 and the result has the Currency datatype

The following expression is an example of the method GetISOCode(value) CurrencyGetISOCode(MyCurrency)

returns the ISO code for MyCurrency

The following expression is an example of the method GetValue(value) CurrencyGetValue(MyCurrency)

returns the amount of MyCurrency as a number with the Number datatype


source cur factor target iso code) for MixedCurrency

CurrencyConvert(ldquoGBPrdquoMyCurrency161 ldquoEURrdquo)


rate 161 and the result has the MixedCurrency datatype

Note The Convert method for the MixedCurrency datatype does not currently

support conditional access to multiple conversion factors As a result this method can

only process input data in a single currency Input values with a currency other than that

specified as the source ISO code do not produce valid output (the output value is zero)

bull Datatype methods examples Text datatype string methods

The following string methods can be applied in query expressions to Text datatypes In

the following examples string represents the type name

IndexOf(string substring)

returns the index position of the first occurence of the substring

IndexOf(string substring fromIndex)

returns the index position of the first occurence of the substring after the specified

fromIndex index position

Length(string) returns the length of the string

Replace(string oldSubstring newSubstring) replaces the oldSubstring text

with the newSubstring text


Sentences queries

315

SubString(string beginIndex)

returns the substring beginning at the specified beginIndex index position and

ending at the end of the string

SubString(string beginIndex endIndex)


ending at the specified endIndex index position

ToLowerCase(string)

returns the entire string in lower case characters

ToUpperCase(string)

returns the entire string in upper case characters

Type constructors

To create an instance of a Currency MixedCurrency Percentage Time Date or

Timestamp value in an expression you must use the appropriate constructor method for

the datatype You cannot use a string such as ldquo100rdquo on its own

Instances of Number and Text do not require type constructors

This type constructor consists of the name of a datatype followed by a value in

parentheses which is used to construct a suitable value

Note The date format used must match the date format supported by the version of Java

installed on the machine running your Sentences server

bull Type constructors examples

The following are examples of type constructors for their respective datatypes

Currency (ldquo100rdquo)

MixedCurrency (ldquoGBP100rdquo)

Percentage (ldquo10rdquo)

Time (ldquo2359rdquo)

Date (ldquo31121999rdquo)

Timestamp (ldquo1999-12-31 235900rdquo)

Identifiers in operator request node expressions

You can use a parameter name or any request node name as an identifier in a derived type

or selection expression

The following restrictions apply to the use of identifiers in expressions

bull node names used in expressions must be unique You may rename a node to make sure

its name is unique without affecting the nodes link to its original type

bull parameters used in expressions must be based on entity types not association types

bull request node names used in expressions must be those of entity types not association

types

bull if you want to use a node name which contains a character that is also an operator

character (such as - or +) you must rename the node before you can use it as these

characters would cause an error

You should take care to avoid circular references in your queries

Expression results

The number of possible results from a request node determines where the node may be

used in an expression If more than one result can be produced then that node name can

only be used is as part of an expression that is the argument to a group function The

result from an expression that is an argument to a group function can be multiple or

singular


Sentences queries

316

The rules that determine whether a particular request node can generate a singular result

or multiple results is as follows

bull Any request node that is a direct parent node of the expression or selection node is

singular

bull Any other request node whose results have been generated before this depends on the

singularity of any forward or inverse association type request nodes between the

expression or selection request node and request that the identifier comes from Any

forward or inverse requests that are direct parent requests are considered to be singular

Missing values in expressions

The way Sentences behaves when it finds missing values in expressions depends on the

operator being used The descriptions of each of the types of expression operator

elsewhere in this chapter give details of the way missing values are dealt with

Expressions that give the zero token as their result

If the Sum() or Count() group operator has no input values it generates a special zero

token that may be the input for other expressions

If the result of a complete expression for a derived type is the zero token Sentences

converts the result into a zero value for the datatype for the derived type request If

the datatype for the derived type request has not been set and this is the first value found

for this expression then the returned value is 0 with the Number datatype

Required nodes

You can restrict the results of a node by defining the node as Required If a node is

defined as required then the query results for the parent level of that node are restricted to

those instances for which the child node exists

If you need to restrict the returned instances of the node above the parent you must also

define the parent node as Required To restrict the instances of an ultimate parent node to

only those where a child instance exists all associations in the branch to the child must be

defined as Required

Figure 7-13 shows a simple query listing four garage customers By defining the (hellip

owns vehicle registration no) node as required only the three customers who own

vehicles are listed in the results as shown in Figure 7-14

Figure 7-13 Query results before setting the Required node property


Sentences queries

317

Figure 7-14 Query results after setting the Required node property

Another use of the Required node property is shown in the example of a node bound to

an instance (see Binding to an instance) When used with bound nodes the Required

node property may be used as an alternative to the Exists() conditional function as a

selection mechanism (see Exists Conditional function)

To set the Required node property highlight a node and select Set Required from the

Edit menu or the shortcut menu To clear the Required node property select Set

Optional from the Edit menu or the shortcut menu

Renaming request nodes

You can rename any request node in the query tree with the exception of Sort and

Selection nodes This allows you to make node names unique which simplifies references

between one node and another and can make your query easier to read

Sentences uses the new names you assign to query nodes when you display the query

results in the Query Editor or in the Explorer or when you export the query results using

XML or when you display a custom Dataform based on the query

The default name of any node in the request tree is the same as its association or entity

type name in the Sentences Explorer If you change the name of an association or entity

type in the Explorer the Query editor retains the original name and treats the node as if it

had been renamed The reference to the entity or association type remains intact

Except for node names used in derived type expressions which must be unique to prevent

ambiguity Sentences does not require you to use unique node names

Ambiguous names in expressions may cause the query to be executed incorrectly or not at

all

To rename a node

To rename a node follow these steps

1 Highlight the node you want to rename You can rename both association type and

entity type nodes If you want to rename the entity type that is the target of an association

make sure you expand the node and select the target

2 Select Rename from the Edit menu or the shortcut menu or press Ctrl+R or press F2

3 Type in the new name for the node Press Enter or click outside the text edit box or

use the up or down arrow cursor keys to complete the renaming You may wish to save

your query after renaming a node


Sentences queries

318

Hidden Nodes

The expression used by a derived type or a selection request can only use data that is

retrieved as part of the query This means that you may need to including certain data in

your query so that an expression can use it and you may not want to display the data You

can suppress the display of selected branches by marking them as Hidden

Hidden nodes are displayed in grey If you hide a node all its children are hidden as well

To hide a node

To hide a node highlight the node and select Hide Branch from the Edit menu You can

also open the shortcut menu select the Edit submenu and then select Hide Branch To

make a hidden node visible in the results tree select Show Branch

Figure 7-15 shows a query result (from the latest salaries query in the Human

Resources example application) which does not have any of its nodes hidden In the

result tree you can see details of all the Event associations that the query needed to select

from and sort in order to derive the latest salary These branches detract from the results

you want to display

Figure 7-15 Query results before hiding a branch

Figure 7-16 shows the same query and results after the Events branch has been hidden

The results pane only shows the relevant salary details and not the intervening nodes


Sentences queries

319

Figure 7-16 Query results after hiding nodes

Transitive closure and recursive closure

Some relationships between real-world entities are transitive and carry over from one

entity to another An example is ancestor of If Henry is an ancestor of Clare and Clare

is an ancestor of Edward then Henry is also an ancestor of Edward Database systems

use recursive mechanisms to find instances of this kind of relationship For example

instead of locating only a Person who is an ancestor of Clare the system also looks for

any Person who is an ancestor of an ancestor of Clare and so on

Sentences offers two query operations to deal with these kinds of relationships

Transitive closure and Recursive closure

Transitive closure

A transitive closure operation allows you to find all the instances of a transitive relation

such as the association type (Person parent of Person) The result of a transitive

closure operation is a simple list of instances all at the same level The node selected as

the target for transitive closure must be a child node of the selected node and it must be

of the same type or of an equivalent type (supertype subset type or equivalent type) as

the selected node

To define transitive closure for a node

Figure 7-17 Parents query before applying transitive closure


Sentences queries

320

Figure 7-17 shows a query before adding transitive closure

To define transitive closure for a node highlight the node and select Add transitive

closure from the Edit menu You can also open the shortcut menu select the Edit

submenu and then select Add transitive closure

Note To make a closure using transitive closure select the start of the chain of query

nodesTo make a closure using recursive closure select the end of the chain of query

nodes When you select Add transitive closure Sentences displays a special Picker that displays

the whole request tree but only allows you to select appropriate nodes as shown in Figure

7-18

Figure 7-18 The node picker for the add transitive closure operation

When you select a node for transitive closure Sentences adds a new node to the query as

shown in Figure 7-19 The original branch to the selected target node ishidden by default

This branch cannot be modified in any way except for renaming to avoid duplicate names

referred to in expressions

Figure 7-19 The transitive closure node ready to be renamed

The transitive closure node is created with the name Transitive Closure which changes

to the name of the selected target node This should be renamed to a unique name If you

do not rename it Sentences warns that there is a node with a duplicate name in your

query

Figure 7-20 shows the results of the same query shown in Figure 7-17 after adding a

transitive closure node and changing the name of the node to Ancestors


Sentences queries

321

Figure 7-20 Parents query after adding a transitive closure node

You may add further query nodes from the target of a transitive closure to define the

information shown for each result (in this case for each ancestor) A query that includes a

transitive closure node cannot be used for a custom Dataform If you associate a custom

Dataform with a query that includes a transitive closure node Sentences displays an error

message

To cancel recursive closure for a node select Remove transitive closure

Recursive closure

If your database contains associations which have the same entity or association type or a

related entity or association type as both the source and the target (for example Person

parent of Person) then you can use a recursive closure operation to find all the

instances in a chain (for example all the known ancestors of a given individual)

Recursive closure requires a linked chain of association instances (for example a is

parent of b b is parent of c c is parent of d and so on) and the result of a recursive

closure operation is always a linked tree of nodes Figure 7-21 shows an Ancestors query

without using recursive closure


Sentences queries

322

Figure 7-21 Ancestors query without recursive closure

The recursive closure operation creates a loop in the request tree by automatically adding

the child nodes of the parent to the child node This loop generates a new level of the

result tree with each turn However if there is a loop in the data (which may happen in a

case such as Person sibling of Person) then the recursion could repeat itself forever

To prevent this Sentences checks each entity to make sure that it has not already been

processed If it has then it is not processed again

Figure 7-22 shows the same query after recursive closure has been applied

Figure 7-22 Ancestors query with recursive closure

To define recursive closure for a node

To define recursive closure for a node highlight the node which must be a source or a

target Select Make recursive closure from the Edit menu Alternatively select the Edit

submenu and then select Make recursive closure

Note To make a closure using recursive closure select the end of the chain of query

nodes To make a closure using transitive closure select the start of the chain of query

nodes

Sentences displays a special Picker (shown in Figure 7-23) that displays the whole request

tree but only allows you to select appropriate nodes

Figure 7-23 Recursive closure target picker

The node you choose for recursive closure must be of a related type which includes the

same type a supertype a subtype or a subset The node chosen for recursive closure must

be higher up the tree than the selected node on the path between that node and the data

request node It may be a source a target or a data request


Sentences queries

323

A query that includes a recursive closure node cannot be used for a custom Dataform If

you start a custom Dataform on a query that includes a recursive closure node Sentences

displays an error message

You cannot add any further query nodes from the target of a recursive closure

To cancel recursive closure for a node highlight the node and select Break recursive

closure from the Edit menu Alternatively select the Edit submenu and then select

Break recursive closure

Query Parameters

You can use parameters in a query to restrict the results to a specific instance of a type

rather than all the instances You can use a parameter directly to replace an entity type or

indirectly in an expression (see ldquoUsing parameters in query expressionsrdquo ) An example of

a query with parameters is the Resource Data query which is part of the Human

Resources example application as shown in Figure 7-24

Figure 7-24 A query with parameters

Using a parameter makes running a query interactive Each time you execute the query

Sentences asks you to select the value for your parameter by displaying a parameters

dialog as shown in Figure 7-25 (below)

Naming parameters

If you want to create a parameter to bind an entity type request node in your query you

must give it exactly the same name as the request node Using the same name

automatically binds the node to the parameter (see ldquoBinding Nodesrdquo ) If you want to

create a parameter to be used in an expression you may give it any name you like

Try to use only alphabetic characters in parameter names You may use numerals and

spaces in parameter names as long as a space is followed by a character and not a

numeral You may not use special characters in parameter names Parameters may also be

renamed in the same way as a node (see ldquoTo rename a noderdquo )

Creating parameters

Every query includes a Parameters folder in the Query Editor To create a parameter

highlight the Parameters folder and select Create Parameter from the


Sentences queries

324

shortcut menu or select Create Parameter from the Parameters menu Type a name for

the parameter in the dialog box and click OK

To define a parameter highlight the parameter name and use the options on the shortcut

menu or the Parameters menu

Defining a parameterrsquos type

When you create a parameter you may specify the entity or association type that it

replaces To specify the parameterrsquos type highlight the parameterrsquos name and select Set

Type from the shortcut menu or the Parameters menu

Sentences displays a picker list of entity or association types from which you can select

the type

Defining a parameterrsquos value

When you create a parameter you may specify a default value for the parameter The

default value is used unless you specify a different value when you execute the query To

specify the parameterrsquos default value highlight the parameterrsquos name and select Set

Default Value from the shortcut menu or the Parameters menu You may clear the

default value by selecting Clear Default Value from the shortcut menu or the

Parameters menu

If the parameter is based on an association type or an entity type Sentences displays a

picker list of entity or association instances from which you can select the default value

If the parameter is based on an value type Sentences displays a Dataform from which you

can either select an existing value instance or create a new value instance to be used as the

default value

Making a parameter mandatory

All parameters are optional when you create them If a parameter is mandatory you must

supply a value for it when you execute the query To make a parameter mandatory

highlight the parameterrsquos name and select Set Mandatory from the shortcut menu or the

Parameters menu

To make a mandatory parameter optional highlight the parameterrsquos name and select Set

Optional from the shortcut menu or the Parameters menu

Executing a query which has parameters

When you execute a query that includes one or more parameters Sentences displays the

Parameters dialog which allows you to type in values or to select them from a picker

list


Sentences queries

325

Figure 7-25 The Parameters dialog

The example in Figure 7-25 shows the Parameters dialog

Showing parameters in the Explorer

When you hold your mouse pointer over the name of a query in the Explorer schema pane

Sentences displays a Tooltip message listing the parameters for that query and their

current settings

Attaching Subset Queries

You can attach a query to a subset using the entity type Properties dialog available from

the Sentences Explorer You need to initiate the attach action from the Properties dialog

or from the Explorer subsets shortcut menu not from the Query Editor (see ldquoSubsets

properties pagerdquo )

Using parameters in subset queries

You may use parameters in subset queries but you must make sure that the query can run

in all cases When you view the subset in the Sentences Explorer Sentences uses the

default value for the parameter to select instances for display If there is no default value

the parameter is not given a value

If the query parameter is used to bind a node to an instance and there is no value given for

the parameter Sentences runs the query as if there were no binding and returns all

possible instances

If the parameter is used in an expression and there is no value Sentences cannot run the

query In particular it is recommended that you set a default value for parameters used in

expressions in subset queries

Sentences query execution process

The order in which Sentences processes query nodes when it executes a query is not

necessarily the same as the sequence in which the nodes appear in the query structure

This is because Sentences first optimises the query based on the dependencies between

the nodes in order to enhance the execution speed

When there is a problem with query execution Sentences may report the following error

Error 10199 The order in which the execution of requests occurs cannot be

determined due to circular references

When this error is reported Sentences displays the node expression which caused the

error

When you construct a query you should bear in mind that all nodes in the query tree are

visible to all other nodes Therefore any node name that is used more than once must not

be used in an expression as it is not possible for Sentences to distinguish which

occurrence of the node name should be used to evaluate the expression

Additional expression capabilities

Version 40 introduces several new functions and syntax The flexibility of datatypes has

also been improved Rather than attempt to show changes this section includes a

complete list of functions available

Function Description

Textual Functions that act on text or

hyperlink values


Sentences queries

326


Value1 | Value2 Returns the concatenation of the first

and second values as Text

Value to compare Like Text

pattern to compare likenessText

Returns whether the first value is

textually like the second value The

second value can contain wildcards

Char(Number to obtain unicode

character forNumber)

Returns the character represented by

the given number in unicode as text

First(Node) Returns the first value returned by the

specified Node

GetEmail(Hyperlink to obtain email

address forHyperlink)

Returns the email address of the

Hyperlink as text if one exists

GetHostname(Hyperlink to obtain

hostname forHyperlink)

Returns the host name of the


GetPath(Hyperlink to obtain path

forHyperlink)

Returns the path of the Hyperlink as

text if one exists

GetPort(Hyperlink to obtain port

forHyperlink)

Returns the port number of the


GetProtocol(Hyperlink to obtain

protocol forHyperlink)

Returns the protocol of the Hyperlink

as text if one exists

GetQuery(Hyperlink to obtain query

string forHyperlink)

Returns the query string of the


GetUserinfo(Hyperlink to obtain

userinfo forHyperlink)

Returns the user information of the


GetWord(Text to split into words

Text Index of the word to extract

Number)

Returns the Nth word in the input text

If there are fewer words than index

then a null value will be returned

Hyperlink(Value) Construct a new Hyperlink value

IndexOf(Input textText Subtext to

find the index ofText)

Returns the index (as a number) in

the first value of the second value -1

indicates not found


find the index ofText Index to

start searching fromNumber)


the first value of the second value

starting a the index specified in the

third value -1 indicates not found

Last(Node) Returns the last value returned by the

specified Node

Length(Text to get the length

ofText)

Returns the length of the value as a

number

MatchFirstRegexp(Text to be

matchedText Regular Expression

Text)

Returns the first section of input text

matching the regular expression

MatchAllRegexp(Text to be


Text)

Returns all sections of input text

matching the regular expression -

separated by spaces

Metaphone(Text to obtain

Metaphone forText Maximum

metaphone characters to

generateNumber)

Returns the encoded metaphone of

the first value as text The second

value indicates how many characters

to generate


Sentences queries

327



Metaphone forText)


the first value as text

MetaphoneDifference(First input

text to compare MetaphonesText

Second input text to compare

MetaphonesText Maximum


generateNumber)

Returns difference (as a floating point

number between zero and one) of the

first and second values when

encoded using the metaphone

algorithm Zero indicates no

commonality One indicates maximum

commonality The third value

determines how many characters to

generate when encoding




MetaphonesText)







commonality

Replace(Input textText Subtext to

be replacedText Subtext to

replace withText)

Returns the text in the first value after

having any occurrences of the second

value text replaced with the third

value text

Sort(Text to be sortedText

Sorting order Text)

Returns text where the words in the

input are returned sorted

alphabetically The second parameter

dictates sorting (A=ascending

D=descending) Note that any

duplicates are retained Use

SortUnique() to remove duplicate

words

SortUnique(Text to be

sortedText Sorting orderText)






duplicates are removed

SubString(Text to get the substring

ofText Index of the start of the

substringNumber Index of the

end of the substringNumber)

Returns a substring of the first value

starting from the index specified in the

second value and ending at the index

specified in the third value



substringNumber)



second value until the end

Text(Value) Construct a new Text value

ToLowerCase(Text to convert to

lower caseText)

Returns the value converted to

lowercase

ToUpperCase(Text to convert to

upper caseText)


uppercase

Trim(Text to trim leading and

trailing space fromText)

Returns the value trimmed of leading

and trailing spaces as text

Mathematical and Statistics Mathematical and Statistical

Functions


Sentences queries

328


Number(Value) Construct a new Number value

Abs(Number to get the absolute

value ofNumber)

Returns the absolute value of the

value as a number

Power(Number to raise to a

powerNumber Exponent to raise

byNumber)

Returns the first value raised to the

power of the second value as a

number

Random(Number to generate a

random number up to (from

zero)Number)

Returns a random floating point

number between 0 and the given

value

Round(Number to roundNumber

Decimal places (+) or significant

figures (-) to round toNumber)

Returns the first value rounded to the

nearest decimal point or significant

figure If the second value is positive

then it indicates a decimal point if

negative then it indicates significant

figures

Sqrt(Number to get square root

ofNumber)

Returns the square root of the value

as a number

Percentage(Value) Construct a new Percentage value

Value1NumberText +

Value2NumberText

Returns the addition of the two values

appropriate to their datatypes

Value1Number - Value2Number Returns the subtraction of the two

values appropriate to their datatypes

Value1Number Value2Number Returns the multiplication of the two


Value1Number Value2Number Returns the division of the first value

by the second appropriate to their

datatypes

Value1Number ^ Value2Number Returns the first value raised to the

power of the second appropriate to

their datatypes

StdDev(NodeNumber) Returns the population standard

deviation of the values returned by

the Query Node specified

StdDevSample(NodeNumber) Returns the sample standard



Max(NodeNode) Returns the largest of the values

returned by the specified Node

Min(NodeNode) Returns the smallest of the values


Median(NodeNode) Returns the median of the values


Modulo(Node Node) Returns the remainder of the first

value divided by the second value

Average(NodeNode) Returns the mean of the values


Count(NodeNode) Returns a count of the values



Sentences queries

329


CountDistinct(NodeNode) Returns a count of the distinct values


Sum(NodeNode) Returns the sum of the values


Currency Functions that operate on

currencies

Currency(Value) Construct a new Currency value

Convert(Currency code of

inputText Input

CurrencyCurrency Exchange

factorNumber Currency code of

outputText)

Returns a currency converted using

the given codes and factor

GetISOCode(Currency to get ISO

code

fromCurrencyMixedCurrency)

Returns the International Organization

for Standardization code for the

currency as text

GetValue(Currency to get value

ofCurrencyMixedCurrency)

Returns the value of the currency as a

number


value ofNumber)


value as a number



byNumber)



number



zero)Number)



value









figures


ofNumber)


as a number

MixedCurrency(Value) Construct a new MixedCurrency value


inputText Input

MixedCurrencyMixedCurrency

Exchange factorNumber

Currency code of outputText)

Returns a mixed currency converted

using the given codes and factor

Abs(Mixed Currency to get

absolute value ofMixedCurrency)


mixed currency as a number

Date and Time Functions that operate on dates

times and timestamps

Date(Value) Construct a new Date value

Now() Returns the date today

AddDays(Date or Timestamp to

add days toDateTimestamp

Number of days to addNumber)

Returns the given date or timestamp

with the number of days added The

second value can be negative


Sentences queries

330


AddMonths(Date or Timestamp to

add months toDateTimestamp

Number of months to addNumber)


with the number of months added

The second value can be negative

AddYears(Date or Timestamp to

add years toDateTimestamp

Number of years to addNumber)


with the number of years added The


GetAgeInYears(Date or

Timestamp to get the age

ofDateTimestamp)

Returns the whole number of years

since the given date as a number

GetFiscalDay(Date or Timestamp

to get day of the fiscal year for

DateTimestamp Fiscal year start

month (1-12) Number Fiscal year

start day of month (1-31) Number)

Returns the day of the fiscal year as a

number

GetFiscalWeek(Date or Timestamp

to get week of the fiscal year for




Returns the week of the fiscal year as

a number

GetFiscalMonth(Date or

Timestamp to get month of the

fiscal year for DateTimestamp

Fiscal year start month (1-12)

Number Fiscal year start day of

month (1-31) Number)

Returns the month of the fiscal year

as a number

GetFiscalQuarter(Date or

Timestamp to get quarter of the





Returns the quarter of the fiscal year

as a number

GetLastDayOfMonth(Date to get

last day of the month forDate)

Returns the last day of the month as a

number

GetSeconds(Time or Timestamp to

get seconds of the minute

forTimeTimestamp)

Returns the seconds of the minute as

a number

GetMinutes(Time or Timestamp to

get minutes of the hour

forTimeTimestamp)

Returns the minutes of the hour as a

number

GetHours(Time or Timestamp to

get hour of the day

forTimeTimestamp)

Returns the hour of the day as a

number

GetYear(Date or Timestamp to get

the year forDateTimestamp)

Returns the year of the date as a

number

GetMonth(Date or Timestamp to

get month of the year

forDateTimestamp)

Returns the month of the year as a

number

GetDay(Date or Timestamp to get

day of the month

forDateTimestamp)

Returns the day of the month as a

number


Sentences queries

331


GetDayOfWeek(Date or

Timestamp to get day of the week

forDateTimestamp)

Returns the day of the week as a

number

InFiscalYear(Node1

DateTimestamp Node2

DateTimestamp)

Returns whether or not the first date

parameter is in the fiscal year starting

with the second date parameter

Time(Value) Construct a new Time value

AddSeconds(Time or Timestamp

to add seconds

toTimeTimestamp Number of

seconds to addNumber)

Returns the given time or timestamp

with the number of seconds added


AddMinutes(Time or Timestamp to

add minutes toTimeTimestamp

Number of minutes to

addNumber)


with the number of minutes added


AddHours(Time or Timestamp to

add hours toTimeTimestamp

Number of hours to addNumber)


with the number of hours added The


Timestamp(Value) Construct a new Timestamp value

GetLastDayOfMonth(Timestamp

to get last day of the month

forTimestamp)


number

GetMilliseconds(Timestamp to get

milliseconds ofTimestamp)

Returns the milliseconds of the

timestamp as a number

Logical Functions that evaluate a logical

condition to determine their

answer

NOT(ValueBoolean) Returns the logical opposite of the

value

Value1 == Value2 Returns whether the first value equals

the second value

Value1 = Value2 Returns whether the first value does

not equal the second value

Value1 lt Value2 Returns whether the first value is less

than the second value

Value1 gt Value2 Returns whether the first value is

greater than the second value

Value1 lt= Value2 Returns whether the first value is less

than or equal to the second value

Value1 gt= Value2 Returns whether the first value is

greater than or equal to the second

value

Value1Boolean expression AND

Value2Boolean expression

Returns whether the first value and

the second value are both true

Value1Boolean expression OR


Returns whether either the first value

or the second value or both are true

Value1Boolean expression XOR


Returns whether one of the two

values is tru and the other false


Sentences queries

332


CaseStart (case expression)

When (when expression1) Then

(then expression1) When (when

expression2) Then (then

expression2) Else (else

expression) CaseEnd

Evaluates whether each when

expression matches the case

expression in turn and returns the

appropriate then expression (or the

else expression if none match)

CaseStart When (when

condition1Boolean) Then (then

expression1) When (when



expression) CaseEnd

Evaluates each when condition in

turn and returns the then value or the

else expression if none of the

conditions evaluate to true

Coalesce(Expression1

Expression2 )

Returns the value of the first

expression that does not evaluate to

null

Default(Expression Default

ValueLiteral TextLiteral Number)

Returns the default value if the first

expression evaluates to null

Exists(expression) Returns whether or not the


IF (when condition Boolean)

THEN (then expression) ELSE

(else expression)

Returns the value of the then

expression if the when condition

evaluates to true or else returns the

value of the else expression

Reference Functions that use features

specific to Sentences

PriorResult(NodeNode) Returns the value of the specified

node that was the previous result in

this query data set

PriorResult(NodeNode

DepthNumber)

Returns the value of the specified

node that was a previous result in this

query data set The depth value

determines how many results prior to

this one

CurrentUserHasRole(Role) Returns whether or not the currently

logged on user has the specified role

The depth value determines how

many results prior to this one

GetClientParameter(Client

Parameter)


Client Parameter


Parameter Default Value)


Client Parameter The second value

is returned if no such client parameter

has been set

GetCurrentUserID() Returns the user id of the currently

logged on user

GetCurrentUserName() Returns the name of the currently

logged on user

GetParameter(Query Parameter) Returns the value of the specified

Query Parameter


Sentences queries

333


GetState(Node DomainDomain) Returns the State of the specified

Node for the given Business Rules

Domain

HasState(Node

DomainDomain StateState)

Returns whether or not the specified

Node has the given Business Rules

Domain and State


specified Node


specified Node

TypeOf(Node) Returns the schema type of the

specified Node value

IsSubtypeOf(Node Node) Returns whether or not the value of

the first parameter is a subtype of the

second value The second parameter

can be either an instance a reference

to an Entity Type or the name of an

Entity Type

IsSupertypeOf(Node Node) Returns whether or not the value of

the first parameter is a supertype of

the second value The second

parameter can be either an instance

a reference to an Entity Type or the

name of an Entity Type

User Datatype Functions Functions defined on User

Datatypes

TelecomsNumber(Value) Construct a new TelecomsNumber

value

Valid(TelecomsNumber to

validateTelecoms)

Valid

Of particular note are the following areas

bull Metaphone and MetaphoneDifference

Metaphone is a phonetic algorithm an algorithm published in 1990 for indexing words by

their English pronunciation The algorithm produces variable length keys as its output as

opposed to Soundexs fixed-length keys Similar sounding words share the same keys

The Metaphone function built into Sentences Query Engine returns the encoded

metaphone of the input string There is an optional numeric parameter that indicates how

many characters to generate

The Metaphone Difference function returns the difference (as a floating point number

between zero and one) of the first and second values when encoded using the metaphone

algorithm Zero indicates no commonality One indicates maximum commonality The

third optional numeric value determines how many characters to generate when

performing the encoding on the two string values

bull Hyperlinks

Functions for Hyperlinks have been extended to extract key parts of the URI For

example if you wish to extract the email component from a mailto Hyperlink you can

use the function GetEmail(Hyperlink) to do so


Sentences queries

334

bull Mathematical and Statistical Functions

Numbers (which include Percentages and Currency datatypes) have additional functions

for calculating Random numbers Rounding to a number of decimal places or significant

figures obtaining the Absolute value raising one number to the power of another and

finding the square root of a number

Two new group functions have been added to obtain the Standard Deviation of a set of

numbers StdDev returns the population standard deviation whilst StdDevSample

returns the sample standard deviation Sample assumes a small subset of the total

population and adjusts the calculation to compensate

bull Date and Time functions

A Date or a Time can now be asked for the last day of the month A Timestamp can now

be asked for its milliseconds component

bull Case and Coalesce

Joining the IF THEN ELSE statement are two new logical constructs Case and Coalesce

The Case statement has two syntaxes

Syntax 1

Case (case expression)

When (when expression1) Then (then expression1)


Else (else expression) End

This statement allows you to return a given value depending upon which of the when

expressions evaluates to be equal to the first case expression If none are equal then the

optional else expression is returned

Syntax 2

Case

When (when condition1Boolean) Then (then expression1)



The second syntax for case is the more general form and allows you to return a given

value depending upon which conditional expression evaluates to true This means that

you are not limited to equalities Again there is an optional else expression if none of the

conditional expressions evaluate to true

The Coalesce statement allows you to provide a list of expressions the first one that does

not evaluate to null will be returned There is no Else clause because the last item in the

list can be a ldquocatch-allrdquo value

bull PriorResult

The PriorResult function allows you to reference the result from a specified node from the

previous branch of data results There is an optional parameter to say how many results to

go back


Sentences queries

335

As an example suppose that whether or not it rains today depends on previous weather

conditions through the last two days Specifically suppose that if it has rained for the past

two days then it will rain tomorrow with probability 07 if it rained today but not

yesterday then it will rain tomorrow with probability 05 if it rained yesterday but not

today then it will rain tomorrow with probability 04 if it has not rained in the past two

days then it will rain tomorrow with probability 02

If an entry is made each day to record whether it rained or not we could create a query

that uses this hypothesis to predict the weather tomorrow based on the records for today

and yesterday We could also write a query to historically compare the actual outcome

with the predicted outcome

The Chance of Rain Tomorrow expression is

CASE

WHEN ((Exists(Rained Yesterday) AND Exists(Yes))) THEN

(07)

WHEN ((Exists(Rained Yesterday) AND Not(Exists(Yes)))) THEN

(05)

WHEN ((Not(Exists(Rained Yesterday)) AND Exists(Yes))) THEN

(04)

WHEN ((Not(Exists(Rained Yesterday)) AND Not(Exists(Yes))))

THEN (02)

END

Some results might be


Sentences queries

336

bull User Security

The CurrentUserHasRole() function allows you to adapt the application behaviour

depending upon which Roles the current user has

You may also obtain the users name and login id with GetCurrentUserName() and

GetCurrentUserID()

bull State Domains

The GetState() function allows you to get the current state of an instance for a

specified Domain

The HasState() function answers true if the specified instance has the specified state

Note that an instance may be in two states at once The first function will answer the first

state that evaluates to true according to the order of state definitions in the Predicate

Query The second function will answer true if that state evaluates to true regardless of

the other state definitions in the Predicate Query

See the Using states in regular queries and dataforms section for details

Entity type constructors

Sentences expressions include functions for creating instances of Datatypes to use in

expressions For example you can specify a percentage value using the expression

Percentage(ldquo12rdquo) This is useful if a particular function requires that one of itrsquos

parameters is a certain Datatype

Sentences Version 40 introduces General Entity Type Constructors as well as these

Datatype Constructors

You may enter an expression such as Person(ldquoBarry Squiresrdquo) in an expression and

the resulting value will be of the type Person In the case of Datatype constructors if a

value does not exist then one is created For Entity Types the constructor works

differently If Barry Squires exists then the entity is returned otherwise no value is

returned That is a new Person is not created if the name does not match an existing

entity

The expression and function editors

Expressions in requests prior to Version 40 were composed and edited by editing a text

field You needed to know the available functions and syntax in order to formulate your

expression The expression was not validated until you attempted to execute your query

Version 40 introduces new Expression and Function Editors to assist with the

composition of expressions in Request Queries

Expressions are used in Sentences Queries to derive values and to evaluate truefalse

conditions used to filter results Expressions exist

In a Derived Type to derive the Target

In a Forward Request or a Forward Action Request to derive the Target

In an Inverse Request or an Inverse Action Request to derive the Source

In Message Action Requests to derive the message

In Simple Email Requests to derive the To recipients the Cc recipients the

email subject and the email text

In Selection Nodes to filter the parent of the Selection


Sentences queries

337

In Predicate Queries to define when an instance is in a particular State

In the Default Target properties of an Association Type

In all cases except the Default Target properties of an Association Type the expressions

are part of a query and may reference other request nodes and parameters from that query

When you edit an expression rather than editing the text in a field the Expression Editor

is opened

The expression editor shows you the expression decomposed into its constituent parts and

allows you to select individual components to edit

When you select a component of the Expression a description of that Function or a field

to alter the parameter will be shown

Below this is a field where the entire expression can be edited

Finally there is a notification area at the bottom of the editor that will inform you of any

problems with the expression

You can either select a Function or a Function Parameter If you select a Function they

you may

Edit that function in a child Function Editor

Delete the function You can only do this if you have selected the top-level

function or one side of a binary operation

Wrap a function This opens a child Function Editor with the selected function

specified as the first parameter to the new function that you choose to wrap it in

Remove the outer Function (unwrap a function)

If you select a Function Parameter then you can directly edit that value or node

depending upon the type of parameter expected


Sentences queries

338

The Parent Function of the selected Parameter ldquoExistsrdquo takes one parameter that should

be either a Query Request Node or a Query Request Parameter

Creating a new expression

When a new expression is required a blank Expression Editor will be opened for you

You will have three options open to you

Insert a Function

Insert a Node (or Query Parameter)

Start to type an expression into the full expression field

If you select the Insert Node button the node and parameter picker will be opened for you

to select a node or parameter You may then wrap this node in another function to build

up a more complex expression

If you select the Insert button a blank Function Editor will be opened

This allows you to find the function you require by selecting a category and browsing

through the list of functions on the right When you select a particular function a

description the kind of value it returns and the parameters it requires are shown below

The notification area at the bottom of the editor will inform you of any problems with the

function

At any time in an expression editor or child editor you may select the Reset button to

reset the contents of the editor to the state in which it was opened


Sentences queries

339

Note that the available list of functions will be filtered depending upon the kind of value

that the parent editor expects In the above example any non-boolean value is acceptable

If you were creating a new expression for a Select Request Node then only boolean values

would be acceptable

If the parent function requires a particular datatype then only functions that return that

datatype will be included

Editing a function

If you select a Function and select the Edit button the Function Editor will open for that

Function with its parameters You can select a different function and the parameters will

be retained For example if you had a function to derive the minimum of a Monetary

Value and wished to change it to be the maximum you would select Edit change the

selected function from Min to Max and select OK


Sentences queries

340

Wrapping functions and parameters

When the function or parameter you have selected can itself be the parameter to another

function the Wrap button will be enabled

If you select Wrap then a blank Function Editor will open and when you select a

function the first parameter will be set If the function you select requires more

parameters then you will need to fill in these fields before you can select OK and wrap the

original function or parameter

Unwrapping functions and parameters

If the function you have selected has a single parameter that is a compatible type with the

functions parent then you will be able to unwrap (remove the outer function)

For example below you can remove the Not() function to leave

hellipAND Exists(Yes)hellip

Deleting the expression

If the function you have selected is the top level function then selecting Delete will

remove the entire expression


Sentences queries

341

Deleting a function or parameter

If the function or parameter you have selected is one parameter in its parent binary

function (for example either X or Y in the function X AND Y) then you will be able to

delete it The effect is to remove the parent function and leave behind the other parameter

so in this case deleting X would leave Y and deleting Y would leave X

Nested expressions and functions

When you edit or wrap part of an expression one of the parameters may itself be an

expression or function In this case the parameter field will not contain a simple node

name or literal value and you are able to edit or wrap the expression or function in a new

child editor

To Edit the expression or function select the Edit button To Wrap the expression or

function select the Wrap button If there is no existing parameter value then the Wrap

button will be an Insert button Select this to open a blank child Function Editor

Node and parameter pickers

Many functions take Request Nodes or Query Parameters as parameters If applicable

then Nodehellip and Parameterhellip buttons will appear Selecting one of these will open a

picker showing eligible Request Nodes and Query Parameters

By default only eligible nodes are shown By deselecting the Hide ineligible nodes

checkbox you will be able to see all available request nodes with the ineligible ones

greyed out If you select one then information at the base of the picker will tell you why

the node is ineligible


Sentences queries

342

The reasons why a node may not be eligible are

You cannot specify the node name of the node that this expression is attached to

unless the function is a PriorResult function

You cannot select a node that does not have a unique name

You cannot select a node that has an incompatible datatype

It is possible to rename a node from the list by selecting Rename Node when that node is

the selected item in the picker This allows you to continue defining the expression

without returning to the query editor

When you rename the node any references to it will also be renamed This is unlikely as

existing expressions should prevent a non-unique node name being used elsewhere

Other pickers

There are a few very specific Functions that require very specific parameters

bull GetParameter

The GetParameter() function requires a parameter name so the picker for this only

includes query parameters

bull GetClientParameter

The GetClientParameter() function requires a client parameter name so the picker

for this only includes client parameter names

bull GetState and HasState

These functions require a Domain so there is a picker that shows Domains applicable to

the Type of the node parameter The HasState function further requires a State name and

the picker for this only shows States applicable to the selected Domain


Sentences queries

343

Update Queries

Version 40 introduces the ability to create queries that change data rather than request

results Effector Queries have these abilities but are only executed within the context of a

Transaction and triggered by State Changes and Business Rules Generally an Effector

query will also be acting on a single instance and its associations

Update Queries are intended to update many instances at once Queries that contain

request nodes that may change data appear with a different red icon to identify them as

Update Queries Effector Queries also use the same icon For details of Effector Queries

see the ldquoEffector Queriesrdquo section

When you execute a standard query the results are not all returned at once but for an

Update Query the entire update is performed and you will be asked to confirm the

execution because it could potentially change many data If you press the stop button

whilst an Update Query is executing then the query will be stopped and the transaction

and all changes will be rolled back

There are five kinds of action that an Update Query can perform

Creating or deleting data

Firing a Sentences Trigger

Requesting a State change

Creating a message for the current user

Sending a simple email message

In addition to these five actions some Grouping Requests will act on the instances to

supersede delete duplicates or make the groups members equivalent to one another

Creating and deleting instances

When constructing regular queries you add forward and inverse requests and derived

type requests to existing query nodes starting with the Data Request If you add a forward

request for example then this instructs Sentences to fetch all matching instances from the

database and return them as results You can filter the results that return and you may

derive the results from expressions

With an Update Query you may also delete instances by specifying that a Data Request

deletes matching instances This is toggled on and off from the Data Request context

menu or the Edit menu of the Request Editor The icon ( ) has a minus sign similar to

the ForwardInverse Action Requests below and the query is classed as an Action Request

if the flag is set The LazyType cannot be a Value Type but can be either an ET or an AT

The instances that are deleted are limited in all the usual ways

bull Binding to an instance

bull Adding required child nodes

bull Adding a Selection node

With an Update Query you may also use Association Actions These can be added (either

forwards or inverse) to create or delete data rather than fetch existing data Again you are

able to filter the instances created or deleted

There are four variations on creating data and two variations for deleting When you add a

Forward Action Request or an Inverse Action Request you specify one of six actions

to take

bull Create Associations (duplicate targetssources)


Sentences queries

344

This action will always create a new association even if this leads to duplicate

associations The target (or source) will also always be created even if this leads to

duplicates

bull Create Associations (reuse targetssources)


associations but will reuse any existing target (or source) or create them as needed

bull Set Association

This action creates an association if one is needed If there is already an existing

association then it replaces that instance If the Association Type is multiple then an error

is reported

bull Reuse Associations

This action creates an association unless it already exists If it does exist then the existing

association is reused

bull Delete Associations

This action deletes all associations that match the target (or source if inverse) Any targets

(or sources) that have no matches are silently ignored The targets (or sources) are not

deleted themselves

bull Delete SourcesTargets

This action deletes all matching targets (or sources if inverse) The associations

themselves are not directly deleted but will no longer be visible

To add an Association Action Request follow these steps

1 In the Query Editor select the node you wish to add an Association Action

Request to

2 Select Add from the Edit menu to open the sub-menu

3 Select Association Actions hellip A dialog showing the available association types

will open

4 Select the association type you wish to create one or more instances of

5 Select the type of action you wish to perform

6 Select the Add button


Sentences queries

345

7 The request is added You can then specify how the target should be determined

In the example shown we have derived the Date today but you could also bind

to an instance or another node in the same way that you may limit normal

forward requests

In the example shown it is then possible to add further Association Actions to the

existing one

The action to perform can be changed by opening the properties of the Action Request

Node

The Action Page allows you to change which action is performed

Firing triggers


were the only available mechanism to do so prior to Version 40 Update Queries are able

to fire Sentences Triggers to maintain this flexibility


Sentences queries

346


details of what was changed and why If a trigger is fired from an Update Query then this

information is included

It is also possible to directly request that a trigger is fired when an instance changes state

See the section Effector Triggers

To add a Trigger Request follow these steps

1 In the Query Editor select the node you wish to add a Trigger Request to


3 Select Trigger Actions hellip A dialog showing the available triggers will open



6 The Trigger Request will be added to the query node

Requesting a state change

You may desire to change the state of one or more instances related to a Request Node

When a state is mandated the desired effect is to change that instance to the given state

but it must be remembered that states are not set They are transient and are interpreted at

a moment in time by their Domains Predicate Query With an Effector Query what is

actually happening is the Effector Query attached to that State is being executed and it is

up to the designer whether the perceived state will actually change With a general Update

Query changing the state will trigger any Effector Query attached to that specified state

Again whether the state is actually changed depends on the designer

To add a Set State Request follow these steps

1 In the Query Editor select the node you wish to add a Set State Request to


3 Select Change State Action hellip A picker showing the available domains and

states will open

4 Select the desired state and the Set State Request will be added

Adding a message action

Update Queries can include Message Action Request nodes that are intended to inform

the current user of pertinent information The message can be classified as one of three

types Error Warning or Information If you specify a message type of Error then the

transaction will also be aborted


Sentences queries

347

The message can be sent to the existing Sentences Message Log a message dialog or

both Each message will produce a new row in the Message Log All messages will be

shown in one dialog together

To add a Message Action Request follow these steps

1 In the Query Editor select the node you wish to add a Message Action Request

to


3 Select Message Action hellip The new Message Request dialog will open

4 Select the desired type of message Error Warning or Information

5 Select the desired presentation Dialog Message Log or both

6 Enter an expression that will evaluate to the message This is a Sentences

expression and can use all the functionality available to existing Derived Type

nodes ndash for example referencing other nodes in the query

7 Select OK to add the request

There is a limit to the number of messages that can be sent to the current user in one

transaction See the Business Rules Reference section for details

Adding an email action

Update Queries can include Email Action Request nodes that are intended to send basic

textual emails The Sentences Server must be set up by a system administrator to use your

companyrsquos email service with one or more pre-defined From email addresses It will be

the application that is sending emails rather than an individual See the Business Rules

Reference section for details of how the email system should be set up

Once set up an Update Query can add an Email Action where the To cc Subject and

Message are derived by specifying query expressions This means that they can be

anything from a simple piece of literal text to a complex formula that evaluates to the

desired text


Sentences queries

348

The From field will be chosen from a predefined list set up by the system administrator

To add an Email Action Request follow these steps

1 In the Query Editor select the node you wish to add an Email Action Request to


3 Select Email Action hellip The New Simple Email Request dialog will open

4 Select the desired From email address

5 Enter expressions to define the To recipient(s) and the cc recipient(s)

6 Enter an expression that will evaluate to the subject

7 Enter an expression that will evaluate to the message body

These are all Sentences expressions and can use all the functionality available to

existing Derived Type nodes ndash for example referencing other nodes in the query

8 Select OK to add the email request

Grouping instances

Update Queries can include Group nodes In addition to simply grouping the results

additional actions can be performed on each group

bull Make group members equivalent to one another

bull Supersede group members

bull Delete duplicate group members

For details of grouping actions see the ldquoGrouping resultsrdquo section below

Sandbox mode


Update Queries This allows you to try your Update Query explore and check the results

and then revert to the state the database was in before execution In this way you can

experiment without fear of corrupting your data See the section on Sandbox Modes for

details


Sentences queries

349

Grouping results

Version 40 introduces the ability to group results at different levels of the results tree By

adding a Grouping Node you specify an expression that is evaluated for every result and

those results with the same value are grouped together These are displayed in folders

To create a Grouping follow these steps

1 In the Request Query Editor select the

node that you wish to group the results

for This can be the Data Request Root

or any Forward or Inverse Request

2 From the context menu select Add and

from the cascaded menu select Group

3 A Grouping Request node will be

added to the query and the Expression

Editor will be opened for you to

compose an expression

In this example the expression evaluated for each event is the year of its date so events

are grouped by year

Grouping Requests also have the ability to act on those group members The default

behaviour is to list the group members but there are five actions that can be requested

The properties of a Grouping Request allow you to change the action

bull List group members

This default behaviour lists all the group members in a folder

bull List first group member only

This action only includes the first member of each group arbitrarily The other members

are not deleted they are ignored



Sentences queries

350

This action changes the instances in each group to be equivalent to one another and

displays all of them A query that contains a Grouping Request with this action will alter

data and becomes an Update Query


This action arbitrarily takes the first group member and uses it to supersede the other

group members Only this instance is included in the results A query that contains a

Grouping Request with this action will alter data and becomes an Update Query


This action arbitrarily retains the first group member and deletes the other group

members Only the surviving instance is included in the results A query that contains a


bull Hide groups of one result

The Grouping Request hides any results that are groups of one by default If an action is

selected that results in a single item per group (list first supersede or delete duplicates)

then the checkbox is unchecked by default

If groups of one are not hidden then they appear as a direct child of the parent rather than

in a folder

The Human resources example profile that is shipped with Sentences contains a query

called Ages that demonstrates the use of a Grouping Request

Sandbox Mode





details

Reporting using SAP Crystal Reports

Version 40 introduces the ability to use the SAP Crystal Reports Software to connect to

Sentences as an XML Data Source

The exact method of connecting may differ between versions of SAP Crystal Reports but

the general outline is as follows

1 Start your copy of SAP Crystal Reports and start the Report Wizard or create a

new Data Source Connection

2 Select to create an XML Data Source

3 In the XML Data Source Connection properties elect to use an HTTP(S) Data

Source

This data source will be a URL to the Sentences XML Service in the Enterprise

Edition Installation It will be of the form

[http| https][serverport]SentencesXML[profile name] sect

[saved query]

eg

httplocalhost8090SentencesXMLAS Skills Register sect

Yearly Training Summary

4 Next specify an HTTP(S) schema This is the same as the XML URL except the

XML is replaced with the Schema URL

[http| https][serverport]SentencesSchema[profile name] sect

[saved query]


Sentences queries

351

5 By default the XML output from the Sentences XML Service is formatted into

HTML so you will also need to specify a query parameter ldquostylesheetrdquo with the

value ldquononerdquo

6 If the Saved Query requires any parameters then they must be defined here as

well

7 Once the connection is set up it can be used in SAP Crystal Reports in the same

way as other Data Sources to lay out reports


Sentences Version 40 introduced the concept of Display Name queries


Sentences interface A query can be used to define the ldquodisplay namerdquo of an entity or

association in place of the underlying data So for example rather than displaying

employees unique IDs imported from a Relational Database their first and last name can

be displayed

Creating a display name query

A display name query is no different from a standard query and can use all the available

functionality available to standard queries They cannot use functionality that is intended

for use in an Effector or Update Query as they do not execute in the context of a

transaction

In order to attach a query to a type that is to be used as a Display Name Query for that

type its data request type must be compatible with that type The first child of the data

request will be used as the display name This can be

The Target of a Forward Request

The Source of an Inverse Request or

The derived Target of a Derived Type Request

Any other supporting request nodes may be added to form the display name

For convenience the Query Editor provides the ability to add a Derived Type with the

name ldquoDisplay namerdquo as the first child and open the Expression Editor for you to create

the expression To do this select the Display name menu item from the Add menu

You can create a new Display Name query edit the existing query attach a different

query or detach the current query directly from the type in the schema pane

To create a new Display Name Query for a type follow these steps

1 Select the type in the Sentences Explorer Schema pane

2 Select the Schema menu and then select Createhellip from the Display Name

Query cascading menu

A new Display Name query will be created and attached to the type The Query editor

will be opened on the new Query for you to edit By default the Query will already

contain a Derived Type Request child for the type but you can amend the query as

normal


Sentences queries

352

To edit the existing Display Name Query for a type follow these steps


2 Select the Schema menu and then select Edithellip from the Display Name Query

cascading menu

The Query editor will be opened on the Query for you to edit

To attach a query to a type to be used as a display name query follow these steps


2 Select the Schema menu and then select Attachhellip from the Display Name


3 A dialog containing suitable queries will open Select the query you wish to

attach

To detach a display name query from a type follow these steps


2 Select the Schema menu and then select Detach from the Display Name Query

cascading menu

It must be borne in mind that the complexity of the calculation of a display name will

impact performance in the Sentences Explorer

Display names in Sentences

By default if a type has a Display Name Query then that display name will be used in the

Sentences Explorer and in Dataforms

When you open a Standard Dataform the title of the dataform and any fields for types

that have a Display Name Query will show the display name When you select the field to

edit then the underlying data will be shown When you exit that field the display name

will be shown again

When you create a Custom Dataform it is based on a standard Sentences query By

default nodes in a Sentences query do not use the Display Name Query attached to each

type

Custom Dataforms

Sentences queries

353

For each node in a query you may alter the properties to change the Display Name Query

to use

The properties allow you to select either ltDefaultgt ltNonegt or a suitable query

bull ltDefaultgt

This option will use the Display Name Query that is set for the Type

bull ltNonegt

This option will use no Display Name Query This is the default option for all query

nodes

Custom Dataforms

Custom Dataforms display a selection of associations defined by a query This is in

contrast to a base Dataform which automatically displays all the associations which have

the same source type You can use the Query Editor to define a query structure

specifically for use as the basis of a custom Dataform and you can display a custom

Dataform based on a query that you have created

To display the custom Dataform from the Query Editor select Custom Dataform from

the Dataform menu or click the Custom Dataform button on the Query Editor toolbar

To display custom Dataforms from the Sentences Explorer highlight an entity type and

select Dataforms from the shortcut menu and choose the specific Dataform you wish to

use from the sub-menu

To select or use a custom Dataform in the Explorer open the Properties dialog and select

the Custom Dataforms page For more information on selecting and using a custom

Dataform see ldquoCreating a custom Dataformrdquo Custom Dataforms can also be used with

the Dataform applet (see ldquoThe Dataform appletrdquo )



examplerdquo

Custom Dataforms

Sentences queries

354

You cannot use a query that includes a recursive or a transitive closure node for a custom

Dataform If you start a custom Dataform on a query that includes a recursive or a

transitive closure node Sentences displays an error message

Page Nodes

You can enhance the design of custom Dataforms by adding page nodes to your query

Page nodes do not have any effect on query results displayed in the Query Editor or the

Sentences Explorer or on CSV export You can define separate XSL Stylesheet options

for page nodes in a query which can effect the display of query results exported or viewed

as XML (see ldquoThe Query Editor and XMLrdquo )

Adding page nodes to your query allows you to group the query nodes When you display

a custom Dataform associations are displayed on tabbed pages according to the groups

you created in the query Page nodes can only display associations from the current level

of a query You cannot display a child association on a page node that is at a level above

that of its immediate parent unless it is part of a table display

Adding a page node

To add a page node highlight the data request node and select Add then Page from the

Edit menu You can type in a name for the page node when you create it You can also

rename a page node The name of the page node in the Query Editor becomes the name of

the tabbed page in the custom Dataform

Page nodes added automatically

The base dataform uses the following processes to create page nodes automatically

Associations that have the original selected type as their source are grouped beneath it and

not beneath a page node

When you use the Add Associations option on the Edit menu Sentences automatically

adds page nodes for any superset subset or equivalent types that are related to the

selected type and that are the source of one or more associations Sentences also adds a

page node for any instance specific associations All the associations which have one of

these related types as their source are grouped beneath the appropriate page node

Using page nodes

To ensure that a query node is displayed on a specific page drag the query node and drop

it onto the page node

Only page nodes that are immediately subsidiary to the data request node are used in the

Custom Dataform for the query Page nodes created at lower levels in the query are used

in child dataforms opened from the custom Dataform Child Dataforms opened on targets

or sources use the default Dataform for that type or the custom Dataform specified on the

Dataform page of the Query node properties dialog (see ldquoQuery node Dataform


Rules for page nodes display on the Dataform

The general rule for the display of page nodes in the dataform is that Sentences creates a

tabbed page in the dataform for each page node that has child nodes and displays the

tabbed pages in a left-to-right order that matches the top-to-bottom order of the page

nodes in the query

If the data request node of the query has any child nodes that are not allocated to page

nodes Sentences creates a tabbed page for the data request node This is known as the

default page The top-to-bottom order position of the first child node that is not allocated

to a page node in the Query Editor determines the left-to-right position of the default page

on the custom Dataform

Custom Dataforms

Sentences queries

355

If the data request node of the query does not have any child nodes that are not allocated

to page nodes then the default page displays only the name field for the type or the target

name if the data request is an association type If you do not add page nodes to your query

all the child nodes are displayed on the default page If there is a page node with the same

name as the data request node then the children of the page node and the unallocated

children of the data request node are displayed on the same page in the custom Dataform

This page is either a page created by the page node or a page created by the unallocated

child (or children) of the data request node depending on which comes first in the top-to-

bottom order of nodes in the Query Editor The order of associations on the Dataform

matches the top-tobottom order of nodes in the Query Editor

When a custom Dataform is displayed the tabbed page displayed to the user is known as

the active page On a create Dataform the active page is always the first page which

contains the instance name On an edit Dataform the active page is the one containing

data about the schema type selected in the schema pane On a child Dataform the active

page is the one with data about the instancersquos type

On a Dataform opened from the picker Applet the active page is the one containingdata

about the schema type specified in the LazyType=lttypegt parameter

Query node Properties dialog

You can display the query node Properties dialog for the root node of a query for other

data nodes and for page nodes Source and target data nodes do not have properties

To display the Properties dialog highlight the node and select Properties from the

shortcut menu or select Properties from the Edit menu or press Ctrl + p

bull Properties dialog for root nodes

The Properties dialog for the root node contains the Format properties page (see ldquoQuery

node Format properties pagerdquo ) and the XSL Stylesheet properties page (see ldquoQuery node

XSL Stylesheet properties pagerdquo ) If the root node is an association type the dialog also

includes the Dataform navigation properties page (see ldquoQuery node Dataform properties

pagerdquo )

bull Properties dialog for data nodes

The Properties dialog for data nodes contains the Format properties page and the

Dataform properties page If the node has a derivation set for it the Properties dialog

includes the Derivations properties page (see ldquoDerivation propertiesrdquo )

bull Properties dialog for page nodes

The Properties dialog for a page node contains the XSL Stylesheet properties page only

bull Properties dialog for derived type nodes

The properties dialog for a derived type node contains the Format properties page (see

ldquoQuery node Format properties pagerdquo ) and the Datatype properties page (see ldquoDerived

type node properties dialogrdquo ) The Read-only on Dataform property is always selected

on the Format page for a derived type and cannot be changed

bull Properties dialog for transitive closure nodes

The properties dialog for a transitive closure node contains the Format properties page

(see ldquoQuery node Format properties pagerdquo ) and the Transitive Closure properties page

(see ldquoTransitive Closure node properties pagerdquo )

Custom Dataforms

Sentences queries

356

Query node Format properties page

Figure 7-26 Query node properties dialog Format page

The Format page is available for the root node and other nodes in the query including

derived type nodes

This page is identical to the Format page which is available from the Sentences Explorer

for entity types and association types Format options chosen in the Query Editor apply to

the display of query results and to custom Dataforms based on queries The choices made

in the Query Editor override any choices made in the ExplorerIn the same way that you

can override the format properties of an entity type on an association type that targets the

entity type you can also override the format properties for a query node based on an

entity or association type

Sentences uses the formatting options you define for a node if the Output option chosen

for exporting or viewing XML results is Formatted If the Output option for XML

results is Unformatted the formatting options for the node are ignored For details of

each of the settings on the Format page see ldquoFormat properties pagerdquo

Effects of using the Restore Default Settings button

The effects of using the Restore Default Settings button vary according to the type of

node concerned

bull Entity type

Pressing the Restore Default Settings button for an entity type restores the format

properties to the defaults for the selected datatype (including the ltNonegt datatype)

bull Association type

Pressing the Restore Default Settings button for an association type restores the format

properties to the settings chosen for the target entity or association type If the target is an

association type the settings for its target are used (iteratively until there is a target which

is an entity type)

Custom Dataforms

Sentences queries

357

bull Query request node

Pressing the Restore Default Settings button for an query request node restores the

format properties to the settings chosen for the type that the request node is based on

bull Query derived type

Pressing the Restore Default Settings button for an query derived type restores the

format properties to the defaults for the datatype chosen on the Derived Type Datatype

Properties page

Query node XSL Stylesheet properties page

The XSL Stylesheet page on the properties dialog is available for the query root node and

for page nodes When you select View XML Results or Export XML Results and also

choose Generate as the XSL Stylesheet option Sentences uses the options defined on the

XSL Stylesheet properties page to create the stylesheet used for transforming the query

output (see ldquoXSL Stylesheet optionsrdquo )

The options selected for the query root node apply to the entire query output unless there

are page nodes which have their own XSL stylesheet properties defined

Where page nodes exist the settings defined for the page node only apply to the output of

the associations which are children of the page node and the settings for the query root

node apply to all the associations which are not children of page nodes

Figure 7-27 Query node properties dialog XSL stylesheet page

bull Layout

There are three options for the stylesheet layout

Horizontal layout (the default) gives a presentation in a simple table with multiple

associations shown as extra rows The first column of the table represents the root node or

page node with the node name as the column heading and the subsequent columns

represent the child associations of the root node or page node with the association names

(the verb names) used as the column headings Where the query results include multiple

associations each instance of the multiple association is shown on a separate row An

example of the Horizontal layout with the Show Grid option selected is given in Figure

7-28

Custom Dataforms

Sentences queries

358

Figure 7-28 Example of the Horizontal layout

Vertical (multiples in columns) gives a table presentation with multiple associations

instances shown as columns The first line of the table shows the name of the root node or

page node instance and subsequent lines show the child associations of the root node or

page node with separate columns for each instance of a multiple association An example

of the Vertical (multiples in columns) layout with the Show Grid option selected is

given in Figure 7-29 Please note that when you select Generate as the XSL Stylesheet

option the width of individual columns cannot be controlled To control column width

you need to create your own stylesheet

Custom Dataforms

Sentences queries

359

Figure 7-29 Example of the Vertical (multiples in columns) layout

Vertical (multiples in rows) gives a table presentation with multiple associations

instances shown as additional rows The first line of the table shows the name of the root

node or page node instance and subsequent lines show the child associations of the root

node or page node with additional rows for each instance of a multiple association An

example of the Vertical (multiples in rows) layout with the Show Grid option selected

is given in Figure 7-30 Please note that when you select Generate as the XSL Stylesheet



Custom Dataforms

Sentences queries

360

Figure 7-30 Example of the Vertical (multiples in rows) layout

When a query contains one or more page nodes you can define separate layout options for

each page node You may wish to experiment with the layout options to find the ideal

layout for your query results

bull Background colour

The background colour option allows you to select a background colour When you

choose the Select colour option the Choose colour button becomes active Click the

Choose colour button to select a colour from the colour palette

bull Show grid

Check the Show grid checkbox to display a table border around each table cell in the

query output

bull Show separator

Check the Show separator checkbox to display a separator line between each set of

results in the query output

bull Add printing page breaks

Check the Add printing page breaks checkbox to add a printing page break to the XSL

stylesheet When a results page based on a generated stylesheet is printed there is a page

break before each set of results produced by the node (except for the first set of results

produced by the data request node

Query node Dataform properties page

The Dataform properties page is available for nodes that are based on association types

and is used to define the behaviour of the associationrsquos target in a custom Dataform

Custom Dataforms

Sentences queries

361

To view the page select Properties from the Edit menu or from the shortcut menu on the

node

Figure 7-31 The Query node Dataform Properties dialog

The example shown in Figure 7-31 is for an association type node Next of kin that has

the target Person

You can set the following properties on this dialog



instances



Navigation





illustrated in Figure 7-31














Statistics and Graphical Output

Sentences queries

362

Transitive Closure node properties page

The Transitive Closure node properties page contains a single option to set the depth that

the closure should search to The default setting is unlimited

Figure 7-32 Transitive Closure node properties page


This section describes how you can use the Query Editor to create queries that generate

HTML containing graphical representations of data such as X-Y charts Pie Charts and

Distribution charts

If you have numerical data that you would like statistical information on such as

Averages Maximums and Minimums then the query editor has the ability to add these

top-level statistics

You can also amend queries with numerical data for graphical presentation This is done

using predefined XSL transformations and javascript libraries Sentences uses the jqPlot

javascript library For details see httpwwwjqplotcom The HTML and charts

generated by Sentences can be customised by creating a specific XSL transformation for

each chart that can take advantage of any of the jqPlot features and CSS styling available

Adding statistics to your query

You can add top level statistical results to an existing query by selecting the numerical

node that you wish to look at and which of the statistical group functions you would like

to apply

To add statistical functions to your query follow these steps

1 Open the query in the Query Editor

2 Select the Root query node and from the pop-up context menu select Create Top

Level Statisticshellip from the Chart cascading menu

The Create Top Level Statistics Dialog will open and a Node selection dialog will

appear

3 Select the Numerical node that you wish to perform the statistical functions on

and Click OK

4 When prompted choose whether or not you would like to create default node

names If so the selected node name and the function name will be used to

generate names for the top-level derived type nodes For example Amount


Sentences queries

363

Average would be generated from a Target node for the type Amount that is to be

averaged

5 Select or deselect each of the functions you wish to add

6 Optionally change the names of the top-level derived type nodes

7 Click OK to add the nodes

Figure 7-33 Adding statistical functions

Figure 7-33 shows selecting the second Value node to add statistical functions for The

first value node has already been added with the defaults

Making your query into an X-Y chart

If you have an existing query where there are two appropriate forward requests or derived

type requests as children of the Data request you can choose to turn the query into one

that will output the data as an X-Y chart The only requirement is that there are two such

numeric child requests

To change your query follow these steps


2 Select the Root query node and from the pop-up context menu select Make X-Y

Charthellip from the Chart cascading menu

The following changes will be made to the query

The query now specifies the XYChartxsl transformation

Four top level derived types will be added so that the XSL can determine

A Title

An X-axis label

A Y-axis label

Whether to show a trendline

The data request is renamed ldquoDatardquo


Sentences queries

364

The first two appropriate forward requests (or derived type requests) are renamed

xaxis1Xaxis1

yaxis1Yaxis1

The default value for the Title is the name of the query The default name for the X and Y

axis labels are the original names of the two forward requests (or derived type requests)

The default is to show a trendline by setting its value to ldquoyesrdquo the value should be blank

or the derived type removed completely to not show a trendline

Note if the first two child requests are not numeric then the chart cannot be rendered If

you are using derived types remember to set the datatype to Number in the derived type

request properties

Figure 7-34 An example X-Y chart query with trendline

Making your query into a pie chart



that will output the data as a Pie chart It expects that the first request will produce the

labels and the second request will produce numeric values (they do not need to be

percentages) If the Data request represents the Labels then you can add a Derived Type

request that simply copies the value of each data result as in the example below



2 Select the Root query node and from the pop-up context menu select Make Pie



The query now specifies the PieChartxsl transformation

A top level derived type will be added so that the XSL can determine the chart

Title



xaxis1Xaxis1


Sentences queries

365

yaxis1Yaxis1





Figure 7-35 An example Pie chart query

Making your query into a distribution chart

Distribution charts work in two ways Either the data request itself contains the data that

are to be analysed or the first child (forward inverse or derived type) will be used It is

unlikely that the data request will contain duplicates and the purpose of this chart is to

count occurrences of individual items but it is still possible

It is much more likely that multiples of the first childrsquos target will occur If a forward or

inverse request is used then it can be singular or multiple

If a suitable child request is present then this will be used in favour of the data request

node

There is also a difference when the data are numeric or not If numeric then an interval

needs to be specified This is the width of the ldquobinsrdquo that will be created and several data

points will fit in each bin If the data are not numeric then each item will produce a ldquobinrdquo

and the value will be the number of occurrences

To change your query into a distribution chart follow these steps


2 Select the Root query node and from the pop-up context menu select Make

Distribution Charthellip from the Chart cascading menu


The query now specifies the DistributionChartxsl transformation


A Title

An X-axis label

A Y-axis label

Whether the x axis labels are numeric or not


Sentences queries

366

The data request is renamed ldquoDistributionChartrdquo

If there is a child request then it is renamed inputInput

Two derived type requests are created as children of the data request

DTIntervals

DTFrequency

The default value for the Title is the name of the query The default name for the X axis

label is ldquoDistributionChartrdquo or ldquoInputrdquo depending upon whether a child request is present

The default name for the Y axis label will be ldquoFrequencyrdquo Both labels can be changed to

something more meaningful The default value for ldquonumericrdquo is derived from the datatype

of the data request (or first request child) If the values are numeric but you wish them to

be treated as labels then you can modify this value to ldquordquo or remove the XLabels derived

type node altogether

The DTIntervals value is the ldquobinrdquo size when the data is numeric This defaults to 10 but

will need to be chosen to suit the data to show the desired level of granularity In the first

example with values in the 10000rsquos a DTInterval of 10000 or 5000 is appropriate In the

third example it has the value ldquoLabelsrdquo to indicate that each value will be a ldquobinrdquo

The DTFrequency does not need altering It is populated with the frequency when the

query is executed

When the query executes it is these two derived types that will contain the results of the

distribution analysis

Three examples are given

1 The Monetary value Entity Type as the Data Request to show the distribution of

all monetary amounts

2 The Monetary value Entity Type as the target of the association ((Employee

event Date) salary Monetary value) to show the distribution of salaries and

3 The Skill Entity Type as the target of (Resource skills skill Skill) to show the

frequency that each skill is associated with an Employee

Figure 7-36 Example 1 Data request distribution

The Query Editor and XML

Sentences queries

367

Figure 7-37 Example 2 Data request child distribution

Figure 7-38 Example 3 Non-numeric label distribution


Note Access to certain XML features is controlled by settings in the

Serverproperties file For information on how to check that the features you want

to use are enabled see ldquoServlet access to Sentencesrdquo

This section describes how you can use the Query Editor to create an XML document

which you can view or export to a file and to export an XML Document Type Definition

(DTD) More information on the ways in which you can use XML including how to use

XML to import data into a Sentences database is given in Chapter 8 ldquoSentences and

XMLrdquo You can also export a Sentences schema to XML (see ldquoExport Sentences schema

to XMLrdquo )

XML properties dialog

The XML properties dialog allows you to control the characteristics of XML output from

a query To set the XML properties for a query select Properties from the Query menu

and select the XML page The properties set in this way are the default for the query

The XML page shares the Properties dialog with the General properties page (see

ldquoGeneral query properties dialogrdquo )

Each time you select Export XML Results or View XML Results Sentences displays a

version of the XML properties page which allows you to modify the settings for current

execution of the query but does not change the defaults


Sentences queries

368

Figure 7-33 The Query Properties dialog XML page

Output options

You can use the Output options to control the way Sentences converts database entities

into character strings to be placed in XML elements

bull Format

The options for Output format are Formatted and Unformatted

bull Formatted output uses the formatting defined for each type in the database schema to

control the presentation of results data with each line of a multi-line presentation

represented as a _value element

bull Unformatted output does not apply any formatting and each type is shown in its input

format

For more details on these options see ldquoOutput Format parameterrdquo

bull Element identifiers

Some data request trees include references from one node to another for example when

you bind a node to another node or use recursive closure Select the Use element

identifiers property to ensure that each node has its own unique identifier (an ID

attribute) to make sure that links between nodes are properly referenced in your XML

output Elements with the ID attribute set can be referred to by other elements using the

IDREF attribute

Check the box to select this property By default this property is not selected For more

details about this parameter see ldquoElement IDs parameterrdquo

bull Include Sentences IDs

Every type or instance in a Sentences database has a unique internal identifier (surrogate)

that is usually hidden When you rename a type or instance the internal identifier remains

unchanged

Setting this property also allows an imported document to include lazyid attributes

where appropriate For more details see ldquoInclude Sentences IDsrdquo

Check the box to select this property By default this property is not selected

XSL Stylesheet options

You can modify the presentation of XML output by using an XSL stylesheet The

stylesheet can format the output as either XML HTML or text Frequently an XSL

Stylesheet is used to convert the machine-readable XML data stream output into a human-


Sentences queries

369

readable HTML page that can be viewed in a Web browser If you have specified an XSL

stylesheet that configures the data output as HTML most browsers typically open a new

window displaying the HTML results

Sentences can automatically generate an XSL stylesheet for use with your query output

(see ldquoQuery node XSL Stylesheet properties pagerdquo )

Alternatively you can specify the URL of an existing stylesheet or use one of the

example stylesheets supplied with Sentences which can be found in the Stylesheets

directory of your Sentences installation

You may choose one of the following options for XSL Stylesheets from the XML

Properties dialog

bull None

Choose None if you do not wish to apply an XSL stylesheet to your query results

DTD reference

You can use the DTD reference property to define the way your XML output is related to

a DTD For more information see ldquoDocument Type Declaration parameterrdquo

bull Generated

If you choose Generated Sentences automatically creates an XSL stylesheet for your

query output which takes account of any formatting rules you have defined and applies

the stylesheet to the query output before displaying the output on an HTML page This

option is not available if you select Unformatted as your Output option

Sentences takes account of the XSL stylesheet options defined for the query node and for

any page nodes when it generates a stylesheet For more details and for examples of

output see ldquoQuery node XSL Stylesheet properties pagerdquo

Cascading stylesheet

You can specify a full or relative URL for a cascading stylesheet (CSS file) A cascading

stylesheet applies formatting to HTML pages produced when query output is transformed

to HTML by an XSL stylesheet

Sentences provides a default CSS file in the

ltSentences_homegtTomcat4webappsSentencesCSS directory You may add

additional CSS files to this location

The default CSS file is named QueryResultsStylesheetcss This stylesheet is set

automatically for new queries but not for existing queries

You can reference the URL for cascading stylesheets in this location as shown in the

following example

CssQueryResultsStylesheetcss

bull Server

Choose Server to specify or select an XSL stylesheet stored on the Sentences server

When you choose Server you may either type in the name of a stylesheet or select a

stylesheet by clicking the ellipsis button Sentences displays a file dialog (as shown in

Figure 7-34) starting at the directory location indicated for stylesheets in the

Serverproperties file Stylesheets parameter and including any subdirectories


Sentences queries

370

Figure 7-34 XSL Stylesheet selection dialog

You may select a stylesheet that you have previously exported from Sentences (see

ldquoExport XSL stylesheetrdquo ) if it is available in the Stylesheets directory location on the

server

bull URL

Choose URL to specify the location of an XSL stylesheet using a URL You may specify

any relative or full URL to which the Sentences server has access

Node name considerations for XML output

The name of the XML document is based on the name of the data request node at the root

of the query tree The name of each element defined in the DTD and appearing in the

XML document is based on the name of one of the request nodes in the query tree By

default these names are based on the names of the entity and association types on which

they are based

By default both the name of the file containing your XML document and the name of the

root element of the XML document itself are based on the name of the query You can

name your query with this in mind

You can determine the name of any of the child elements in the XML document by

changing the name of the corresponding request node in your query

Element type names in XML must conform to restrictions not required in Sentences

queries XML element names may contain only letters numbers and periods Spaces in

Sentences query node names are converted to periods when they are used as XML

element names

Create an XML DTD from a query

To export a query definition as an XML DTD select Export XML DTD definition from

the Results menu Sentences displays the File dialog Select the directory and file name

for your Document Type Definition and click Save You can view the resulting DTD in a

text editor as shown in Figure 7-35

ltxml version=10 encoding=UTF-8gt

lt-- DTD generated by Sentences --gt

ltELEMENT Currentemployees (Person) gt

ltELEMENT Person (_value+ lastjoined) gt

ltATTLIST Person action (create | reuse | required | delete) reusegt

ltELEMENT lastjoined (PCDATA) gt

ltELEMENT _value (PCDATA) gt


Sentences queries

371

Figure 7-35 An XML DTD

Export query results as XML

To export the results of a query as XML select Export XML results from the Results

menu Sentences displays a Properties dialog similar to the one illustrated in Figure 7-33

Select the properties you want for your results and click OK

If the query includes any parameters Sentences displays the Parameters dialogSentences

then displays the File dialog Select the directory and file name for your XML file and

click Save You can view the resulting XML in a text editor as shown in Figure 7-36

Figure 7-36 XML results viewed in a text editor

Export XSL stylesheet

To generate an XSL stylesheet which matches the query definition without exporting the

results of the query select Export XSL stylesheet from the Results menu


Sentences queries

372

Sentences displays a file dialog which allows you to specify a location on your client

machine for saving an XSL stylesheet based on the query definition which Sentences

generates automatically

View query results as XML

To view the results of a query as XML select View XML results from the Results menu

Sentences displays the XML Properties dialog as shown in Figure 7-33

Select or modify the properties you want for your results and click OK If the query

includes any parameters Sentences displays the Parameters dialog

When Sentences processes the query it produces the results as a machine-readable XML

data stream You may choose to convert the XML data stream into a more readable

format using an XSL stylesheet as described in ldquoXSL Stylesheet optionsrdquo

If you do not wish to use an XSL stylesheet the display of the XML data depends on

which browser you are using and on how your browser is configured to handle XML data

streams Some Web browsers can automatically create a human-readable display of an

XML data stream For example some versions of Internet Explorer display XML data by

default as a colour-coded and indented display of both tags and data (as shown in Figure

7-37) while Netscape 62 displays XML data by default as an unformatted display of data

only

Figure 7-37 Example of unformatted XML results viewed in Microsoft Internet Explorer

You can greatly improve the readability of the XML output by specifying formatting

instructions You can do this by using either or both of the following methods

bull setting formatting properties on query nodes see the section ldquoQuery node Format

properties pagerdquo for more details

bull specifying an XSL stylesheet see the section ldquoXSL Stylesheet optionsrdquo for more details

Example stylesheets

Sentences supplies two example stylesheets in the ltSentences_homegtStylesheets

directory


Sentences queries

373

Masterxsl example stylesheet

The example shown in Figure 7-38 shows XML results formatted with the example

stylesheet masterxsl This stylesheet specifies HTML output

Figure 7-38 XML results formatted with the masterxsl example stylesheet

The example shown in Figure 7-39shows XML results formatted with the example

stylesheet tablexsl This stylesheet specifies HTML output

Exporting query results as CSV data

Sentences queries

374

Tablexsl example stylesheet

Figure 7-39 XML results formatted with the tablexsl example stylesheet






allows you to sort and select data from the Sentences database before you export it

Running CSV Export

The CSV Export mechanism for queries is based on the type structure of the data request

The same data structure is applied to all the results derived from the query and instances

where associations do not exist are represented in the CSV file by empty values (ldquonullsrdquo)

Derived type nodes may be included in the exported query result as long as they are not

at the top level of the data request If there is a top level derived type node Sentences

cannot complete the CSV export operation and displays an error message

Hidden nodes are not included in the data that is exported

Sentences creates column headings in the resulting CSV file which are based on the node

names in the query structure

To export the results of a query open the query in the Query Editor or select the query in

the Sentences Explorer Queries folder


Sentences queries

375

Select the Export to CSV filehellip command from the Results menu In the Sentences

Explorer this command is on the Resultshellip submenu of the Query menu and also on the

shortcut menu for the query

Sentences displays a standard Open File dialog for your operating system Navigate to

the file location you require type in a name for your CSV file and click Create

You can view the contents of your CSV file using a text editor or some

spreadsheetprograms

CSV Export and multiple associations

There is a limit on the way Sentences exports the results of queries that include multiple

associations Only one multiple association can be exported in any given query and it

must be the last node of the exported query If there are two or more multiple association

nodes that share the same parent node Sentences cannot complete the CSV export

operation and displays an error message Similarly if the multiple association node is

followed by any other node Sentences cannot complete the CSV export operation and


If the data you wish to export includes a number of multiple associations you must

construct a number of separate queries each containing only one multiple association For

information on how to import multiple CSV files into one Sentences database see ldquoCSV

Importrdquo

Introducing XML

Sentences and XML

377

Chapter 8

Sentences and XML

This chapter introduces XML and explains how Sentences and XML can be used

together The topics described in this chapter are

bull Introducing XML

bull XML Support in Sentences

bull XML input and output methods

bull Exporting a Sentences schema to XML

bull Sentences XML conventions

bull Setting XML options in the Query Editor

Introducing XML

XML is the Extensible Markup Language which is the universal format for structured

data and documents on the Web developed under the auspices of the World Wide Web

Consortium (W3C) More information about XML and the complete XML standard is

available from the W3C Web site

httpwwww3corg

XML Terminology

This section provides an introduction to some of the technical terms used when discussing

XML documents and XML processing

Well-formed XML

An XML document is well-formed if it meets the well-formedness constraints defined in

the XML 10 recommendation A document which is not well-formed cannot truly be said

to be an XML document at all The rules for XML documents include the requirement

that every start-tag must be matched by the corresponding end-tag and that any element

started between a pair of start and end tags must also finish between them

The DTD

A Document Type Definition (DTD) is a series of statements that define the structure of

an XML document The DTD can be part of the document (an internal DTD) or the

document can refer to an external DTD The DTD lists the elements that are permitted in

the document and the sequences in which elements may occur

The XMLSchema

XML Schema replaces Document Type Definitions with a way of defining the structure

of an XML document that is itself XML The XMLSchema cannot be part of the

document The XMLSchema lists the elements that are permitted in the document the

sequences in which elements may occur and additional datatype information amongst

other things far in advance of a DTD

Valid XML

To be valid an XML document must meet the validity constraints defined in the XML 10

recommendation It must not only conform to the rules of the XML grammar which make

it well formed but it must also conform to the document structure laid down in a DTD A

XML Support in Sentences

Sentences and XML

378

valid XML document must contain a document type declaration that refers to the DTD for

that document

Elements in XML

An XML document contains one or more elements where an element is either text

delimited by a start-tag and an end-tag or an empty-element tag by itself

Here is an example of a start-tag and an end-tag

ltEmployeegt ltEmployeegt

Start-tags and end-tags consist of a name enclosed in angle brackets (less-than and

greater-than signs) The name is the name of an element type and must be identical in

both tags

Everything between the start-tag and the end-tag is the content of the element which may

consist of a mixture of text and other elements Elements can be nested to any depth but

they must not overlap

Attributes in XML

A start-tag may also contain attributes in the form of name=value pairs as follows

ltimg src=imagesbarneyjpggt

where img is the element type src is the attribute name and

imagesbarneyjpg is the value of the attribute

You can create a well-formed XML document using any names you choose for elements

and attributes For your XML document to be valid the element and attribute names and

the arrangement of elements must conform to the declared DTD

Extensible Stylesheet Language (XSL)

The Extensible Stylesheet Language (XSL) is a language for expressing stylesheets It is

similar in its conception to the Cascading Style Sheets language (CSS) used in HTML

but it is far more powerful

The XSL language consists of two parts

bull XSL Transformations (XSLT) a language for transforming XML documents

bull An XML vocabulary for specifying formatting semantics (XSL Formatting Objects)

Sentences does not use XSL Formatting Objects All references to XML stylesheets in

Sentences and its documentation refer to stylesheets using the XSLT language to express

XSL Transformations


The support for XML in Sentences Version 40 allows you to

bull export a Sentences schema to XML

bull generate an XML Document Type Definition (DTD) from a query

bull generate XML documents from the Sentences database using the structure defined by

the DTD and either save them in files or send them to a browser

bull return a generated XML DTD or XML document in response to an HTTP request

bull read externally-generated XML documents whose structure matches the DTD and

import the data into Sentences

Some of the detailed instructions for creating XML documents and DTDs are given in the

section ldquoThe Query Editor and XMLrdquo This chapter introduces some XML concepts and

provides guidelines for the use of XML with Sentences

Export Sentences schema to XML

Sentences and XML

379

Note When you install Sentences some XML features are disabled This is because you

must apply your own web server security settings before enabling these features For

more information see ldquoServlet access to Sentencesrdquo

Sentences Version 40 does not currently support the proposed XML Schema standard








Sentences Version 40 does not currently support the XML Schema standard other than to

provide an XMLSchema servlet that can be used with SAP Crystal Reports

You can export a Sentences database schema to an XML file This file can be saved or

viewed in a browser window This process is similar to the export of query results to

XML (see ldquoThe Query Editor and XMLrdquo )

When you select Export Schema to XML or View Schema in XML from the Schema

menu Sentences displays the XML Properties page which allows you to define XML

properties

Figure 8-40 The XML properties dialog for schema export

Output options for XML export of schema

The Output options control the way Sentences converts database entities into character

strings to be placed in XML elements

bull Format


bull Formatted

Association type names are displayed as source verb and target

XML data input and output methods

Sentences and XML

380

bull Unformatted

Association type names are displayed as verbs only

XSL Stylesheet options for XML export of schema







You can specify the URL of an existing stylesheet or use one of the example stylesheets

supplied with Sentences which can be found in the Stylesheets directory of your

Sentences installation

The option to Generate an XSL stylesheet which is available when you export the results

of a Sentences query as XML is not available when you export a Sentences schema as

XML Choose one of the following options for XSL Stylesheets

bull None

Choose None if you do not wish to apply an XSL stylesheet to your query results You

cannot specify a DTD reference when you export a Sentences schema to XML

bull Server







bull URL




There are a number of methods for getting data from XML documents into and out of

Sentences as follows

bull using the Query Editor


Sentences and XML

381

bull using a servlet

bull using command-line tools

bull using the Sentences API

Note Only the command-line tools and the Query Editor are available in the Sentences

Personal Edition

Importing XML data

You can import data from an XML document into a Sentences database when the XML

document conforms to a DTD generated from a Sentences query You cannot import data

from arbitrary XML documents into a Sentences database

Using the Query Editor

The Sentences Query Editor is the principal tool for creating XML structures that can be

used for exchanging data between Sentences and XML documents To create an XML

document from Sentences you must first create a Sentences query

Sentences uses the data request structure of the query tree to produce a DTD Sentences

produces an XML document from the query which conforms to the DTD produced from

the queryrsquos structure The XML document contains the same data as the result of the

query

The Query Editor has commands to

bull retrieve the DTD corresponding to a query and save it to a file

bull execute the query convert the results to XML optionally apply a stylesheet to it and

save the resulting document to a file


display the results in the users browser

For details of how to use these commands in the Query Editor see ldquoThe Query Editor and

XMLrdquo

Note XML documents and DTDs cannot be created from Set Queries

Using Servlets

It is possible to access the Sentences server directly by using a specific servlet Sentences

supplies a number of different servlets for different features (see ldquoServlet access to

Sentencesrdquo ) Some of these servlets are deliberately disabled when you install Sentences

and need to be enabled on your Web server before you can use them

Using a servlet to access a generated DTD

Access to some XML features is available through the servlet mechanism Sentences

generates DTDs as they are required and does not store them The Sentences Enterprise

Edition includes a special DTD servlet for this purpose

Note In the Sentences Personal Edition you can only use the DTD servlet URL internally

with the XML Import command-line program


Sentences and XML

382

You can access a generated DTD by specifying a URL which defines the profile name

and the name of a stored query for which the DTD specification is required

The following is an example of a URL to access a DTD

httplazyws308090SentencesDTDHuman20resourcesEmployeeQuery

In this example

http indicates the protocol to be used

lazyws308090 gives the host name and port number

Sentences identifies this URL as belonging to the Sentences

web application This is the servlet context defined

for the Sentences installation

DTD indicates that a DTD is required and routes the

request to the Sentences DTD servlet

Human20resources is the name of the profile with ldquo20rdquo substituted

for the space as required by URL mapping rules

EmployeeQuery is the name of the stored query whose DTD is

required

When you retrieve a DTD using a servlet there is no provision for specifying parameter

values as they cannot affect the DTD

Using a servlet to access XML





The Sentences Enterprise Edition includes an XML Export servlet which accepts URLs to

generate XML documents from stored queries An example of this kind of URL is as

follows

httplazyws308090SentencesXMLHuman20resourcesEmployeeQuery

in which






XML indicates that XML output is required and routes

the request to the Sentences XML servlet



EmployeeQuery is the name of the stored query whose DTD and

XML results are required


Sentences and XML

383

You can use an HTTP GET request with this URL to execute the query without supplying

any parameter values This generates an XML document without a document type

declaration and without any stylesheet processing You can add parameter values to

generate a document type declaration or stylesheet processing or both

Adding parameter values to servlet requests

You can add parameters to servlet requests to supply values for the parameters used in the

query and to control the way the output document is generated

There are two ways of supplying parameter values to servlet requests You can extend an

HTTP GET request with a query string consisting of name=value pairs like this

httphellipEmployeeQueryProject=CRM+developmentampSkill=Java

Alternatively you can supply the name=value pairs using an HTTP POST request for

example from an HTML form

Parameter names are not case sensitive If parameter names or values contain spaces or

other special characters Sentences uses normal URL encoding In the example URL

shown above the space in the profile name CRM development is replaced by a ldquo+rdquo sign

as in CRM+development

Some specific parameter names are used to control the XML generation process and

should not be used for parameters within queries that are to be accessed with this XML

mechanism These parameters which are described in the following sections are

stylesheet doctype format elementids and lazyids

Each of these reserved parameters corresponds to an option that can be set and saved for a

Sentences query using the Query Properties dialog (see ldquoXML properties dialogrdquo ) If

you supply a parameter value with the HTTP request it overrides the parameter value

saved with the query

bull Stylesheet parameter

Sentences can produce results in XML HTML or text format according to the stylesheet

specified The stylesheet parameter specifies the stylesheet processing on the XML

results returned from a saved Sentences query

The format of the stylesheet parameter may be one of the following

stylesheet=ltstylesheetURLgt

where ltstylesheetURLgt

represents thefull or relative URL

from which thestylesheet can be

retrieved

stylesheet=generated

Sentences uses an XSL

Stylesheetgenerated automatically

from the query

stylesheet=none no XSL stylesheet is used

For more information see ldquoQuery node XSL Stylesheet properties pagerdquo and ldquoXSL

Stylesheet optionsrdquo )If you specify a stylesheet URL you may either specify an absolute

URL or use a URL that is relative to a fixed base which is defined by the

StylesheetURLBase parameter in the Serverproperties file

When the stylesheet parameter is used Sentences retrieves the stylesheet or

generates a stylesheet and uses it to process the query results which are then returned as

the response from the servlet


Sentences and XML

384

Note Stylesheet processing is handled by the Sentences XML servlet not by the browser

A specified stylesheet must conform to the XSL Transformations specification The

content type of the resulting document is applicationxml unless the stylesheet

includes an xsl-output element defining a method of html or text For example a

stylesheet used to generate an HTML page from an XML document should start like this

ltxml version=10gt

ltxslstylesheet xmlnsxsl=httpwwww3org1999XSLTransform

version=10gt

ltxsloutput method=html gt

You can set the content type of your processed XML document to texthtml by setting

the stylesheet output method to html You can set the content type of your processed

XML document to textplain by setting the stylesheet output method to text

The Xalan stylesheet processor supplied with Sentences automatically switches the output

mode to HTML if the first element generated is ltHTMLgt but by itself this does not

produce a document with a content type of texthtml

bull Document Type Declaration parameter

You can use the doctype parameter to specify the location of the Document Type

Declaration which is required for XML results returned from a saved Sentences query

There are three possible values for this parameter

doctype=external The XML file contains a reference to a DTD

located by an external URL for example

ltDOCTYPE root-element SYSTEM

httpgt

doctype=internal The DTD is embedded in the XML document

A simple example would be

ltDOCTYPE people [

ltELEMENT people (Person)gt

ltELEMENT Person (PCDATA)gt

]gt

doctype=none The XML file does not refer to a DTD at all

If you wish to export an XML document that you later wish to import into a Sentences

database you must set the doctype parameter to external

bull Output Format parameter

You can use the format parameter to specify the format of the text included in each

element This may have one of two possible values

formatted (default) Uses the formatting defined in the schema and

query Entities with multi-line presentation are

represented as a list of _value elements as

described in ldquoSplit multiple linesrdquo

This setting is recommended if you want to convert

the XML into HTML

unformatted Formatting is not applied and each entity is shown

in its input format Each entity maps to a single

element and new lines are included in the text Use

this setting when you want to import your XML

output into another application or database


Sentences and XML

385

bull Element IDs parameter

You can use the elementids parameter to specify whether Sentences includes an XML

ID attribute on every complex element (see ldquoUsing Element IDsrdquo 7) The possible values

for this parameter are elementids=true and elementids=false

bull Sentences IDs parameter

You can use the lazyids parameter to specify whether Sentences includes internal

identifiers with every complex element (see ldquoInclude Sentences IDsrdquo 6) The possible

values for this parameter are lazyids=true and lazyids=false

bull htmlerror parameter

You can use the htmlerror parameter to specify whether Sentences displays any error

(for example the query doesnrsquot exist or you didnrsquot enter a mandatory parameter) in html

for a more user friendly response The detailed error is hidden and can be expanded but

the message is usually self-explanitory

XML import using a servlet

You can import data from an XML document into Sentences if that document references

and conforms to the DTD that would be generated from a saved Sentences query

You can then configure the Enterprise Edition of Sentences to accept an XML document

using an HTTP POST request The URL for the XML import is fixed for each Sentences

installation for example

httplazyws308090SentencesImportXML

where

http indicates the protocol being used


Sentences identifies the servlet context defined for the


ImportXML routes the request to the Sentences

ImportXML servlet

Note The host name port number and servlet context may vary from one Sentences

installation to another

The DTD that the imported document refers to must be specified as the URL of the DTD

generated from the required Sentences query This URL must refer to exactly the same

host name port number and servlet contexts that are used in the URL for the XML

Import Sentences re-generates the DTD and uses it to validate the incoming document If

the query has changed since the DTD used as a template for the import was exported the

import fails

If the incoming document specifies a stylesheet to be applied before the incoming data is

parsed the stylesheet must specify the appropriate URL for the DTD The nature of the

imported data and where it is stored are determined by the DTD referenced by the

imported document which specifies the Sentences profile and query name which are

used

Importing XML does not use parameter values as they cannot affect the import process

Stylesheet Processing

An XML document that is imported into Sentences may contain a processing instruction

to specify a stylesheet to be applied to the incoming data before it is parsed For example

it may refer to a stylesheet as follows

ltxml-stylesheet type=textxsl href=emplistxslgt


Sentences and XML

386

The stylesheet name is a URL which is either absolute or relative to the location defined

for StylesheetURLBase property in the Serverproperties file

XML Import and triggers

Whenever you use the ImportXML command Sentences checks whether there are any

triggers in the schema that are attached to the entity types affected by the import Any

triggers found are run on the data that is being imported This may affect the data that is

imported or may cause the import procedure to stop before it is completed

You can define an entity type in Sentences to have its instances named by a trigger (see

ldquoInstance name created by triggerrdquo ) When you are using XML Import with data that

includes this kind of entity type you must allow for the creation of the entity name by

including an empty value string in the format

ltvaluegtltvaluegt

If this value string is not empty the trigger produces an error message and the import

fails

XML Import in multi-user environments

Sentences does not check for the possibility of parallel updates when a database is

updated using XML Import It is possible that in multi-user environments updates may

have been made to the database between the time that an XML Export was performed and

the time that a corresponding XML Import was performed

XML Import and derivations

Using XML Import has the same effect as selecting an instance and opening a custom

Dataform for it and then updating association targets Amongst other things this means

that any Calculate once derivations that would be shown on a custom Dataform are

updated when you use XML Import If the derivation is part of the target of a multiple

association type then the derivation for each existing target instance is calculated as well

as the derivation for any instance created or updated by XML Import

Mapping XML Data

Every element in an imported XML document is mapped to an instance in the Sentences

database By default Sentences uses an existing instance where one exists If no suitable

instance exists Sentences creates a new instance

The following mappings are used

entity instance an existing entity instance with the same name

association instance an existing association instance linking the same

source and target

Action attributes

You can force the XML Import process either to create a new instance or to reuse an

existing instance by including an action attribute on the XML element as follows

ltPerson action=creategt

The default value for the action attribute is reuse The possible values for the action

attribute are as follows

action=create Creates a new instance for this element regardless

of whether a suitable instance already exists This

can create duplicates which are not permitted with

singular association types resulting in an error

To avoid this error use set rather than create

with singular association types


Sentences and XML

387

action=set If no instance exists set creates an instance If an

instance exists set overwrites it Set may only be

used with singular association types

action=reuse Refers to an existing suitable instance if there is

one and create a new instance otherwise This is

the default

action=required Refers to an existing instance If a suitable instance

does not exist then the import process fails You can

refer to an instance created earlier in the same

import process

action=rdquodeleterdquo Deletes an existing instance If a suitable instance

does not exist then the import process fails

You can use the action attribute on an element representing an entity which is not a

value or on an element representing an association You cannot use the action attribute

on elements representing values

If the XML document being imported is based on a query that uses Sentences IDs you

can require the use of a particular instance or delete a particular instance by including its

Sentences ID as a lazyid attribute as follows

ltPerson lazyid=223478gt

See ldquoInclude Sentences IDsrdquo for more information on using Sentences IDs

Do not use the action=required attribute with the lazyid attribute If the type

identified by the given Sentences ID cannot be found or if it is not an occurrence of the

correct Sentences type then the import fails

You can use the lazyid attribute on an element representing an entity which is not a

value or on an element representing an association You cannot use the lazyid

attribute on elements representing values

If the XML document being imported is based on a query that uses Element IDs then any

complex element in the imported document can be replaced by a reference element

referring to an earlier element of the same type See ldquoUsing Element IDsrdquo for details

Using command line tools

You can use a command line program to perform an XML export or an XML Import with

the Sentences Enterprise Edition or the Sentences Personal Edition Like the other

Sentences command-line tools these programs require exclusive access to the Sentences

database This means that the Sentences server or the Sentences Personal Edition

application must be closed down before you can use this command line procedure

XML Export using the command line

The command line for XML export looks like this

ExportXML [options] ltprofile namegt ltquery namegt

where ltprofile namegt is the name of a Sentences profile and ltquery namegt is the

name of a saved query in that profile and[options] includes any of the following

optional settings

-file ltoutput file namegt Specifies an output file By default the results

are written to standard output

-stylesheet ltstylesheet file namegt Specifies stylesheet processing (see

ldquoStylesheet parameterrdquo )

-parameter name=value Supplies a value for a query parameter (see

ldquoAdding parameter values to servlet

requestsrdquo ) This option can be repeated as

many times as necessary


Sentences and XML

388

-doctype[external|internal|none] Specifies the type of document type

declaration required (see ldquoDocument Type

Declaration parameterrdquo 5)

-format [formatted|unformatted] Specifies a format mode(see ldquoOutput Format

parameterrdquo )

-elementids [true|false] Defines the use of element IDs (see ldquoElement

IDs parameterrdquo 6)

-lazyids [true|false] Defines the inclusion of Sentences IDs (see

ldquoSentences IDs parameterrdquo )

Note that option names and parameter names are not case sensitive If a parameter name

or value includes spaces or an equals sign the whole name=value pair should be

enclosed in quotation marks for example

-parameter Customer name=John Smith

XML import using the command line

The XML Import command-line procedure can be used for importing data into the

Enterprise Edition in batch mode without the need to configure the XML Import servlet

or to set up security for it The command-line procedure can also be used with the


The command line for Import XML looks like this

ImportXML -file ltinput file namegt

where ltinput file namegt specifies the input file name

Any document that you import must include a reference to a DTD It may also have a

reference to a stylesheet The DTD reference should refer to a saved Sentences query and

should have the following format

httplocalhostSentencesDTDHuman20resourcesEmployeeQuery

where

httplocalhostSentencesDTD is fixed and must appear exactly as shown

(except that any port number present is ignored) and

Human20resourcesEmployeeQuery is an example of a profile name and a stored

query name Note that this URL may differ from that in the XML which would be

exported from the same query using an external DTD

When you use the command line XML import procedure Sentences generates the DTD

from the specified query and passes it to the XML parser to validate the document There

is no actual network access involved

Online importing

When you are using the Enterprise Edition you may wish to make occasional data imports

from XML documents without stopping the server If the XML Import servlet is running

you can import data from XML documents by making HTTP POST requests using any

suitable client tool For more details about the HTTP POST request seeldquoXML import

using a servletrdquo

Using the Sentences API

You can use the Sentences API for a number of XML related tasks including

bull defining a query

bull executing a query to return Java objects for use in the program

bull sending the corresponding DTD to a supplied output stream

Sentences XML conventions

Sentences and XML

389

bull executing the query and sending the results as an XML document to a supplied output

stream

bull executing the query to generate an XML document applying a stylesheet to it and

returning a URL which can be used to retrieve the resulting document

You cannot use the Sentences API for XML import tasks For more details about using

the Sentences API see Chapter 10 ldquoCustomising Sentencesrdquo

Using alternative parsers and stylesheet processors

Sentences is built with the Xerces XML parser and the Xalan XSL transformation engine

both of which have been developed by the Apache Software Foundation Sentences

accesses the transformation and parsing capabilities by using the Java API for XML

Processing (JAXP) standard published by Oracle

You can use an alternative parser or transformation engine by including the appropriate

JAR files on the servlet containers classpath in place of the JAR files supplied

When using the current version of Xerces with Sentences you must specify the class

name for XML parsing in the XmlParserClass property in the Serverproperties

file for example

XmlParserClass= orgapachexercesparsersSAXParser


Sentences uses a number of simple rules to generate XML and XML documents to be

imported into Sentences must follow the same rules If you wish to import data from an

XML document that does not conform to these rules you must create your own stylesheets

to map data using other conventions

The rules are described in the following sections

Use content not attributes

All data is held as content not attributes For example a persons telephone number must

appear as content like this

lthometelephonegt(210) 182 0932lthometelephonegt

It must not appear as an attribute like this

ltPerson hometelephone=(210) 182 0932gt

Using content results in a slightly longer representation than using attributes but it allows

for the possibility that each data value can have its own attributes

Associations appear as child elements

Associations linked to an entity or association appear as child elements of the element

corresponding to that entity or association The sample of XML output in Figure 8-1 is an

extract of employee data from the example Human resources example application and

shows associations linked as child elements


Sentences and XML

390

Figure 8-1 Example of XML output

The employees e-mail address is held in Sentences as an association and so it appears as

a child element Similarly employment events are held as associations of type

(Employee event Date) which have associations of their own in turn The event

element has a child called Date to hold its target alongside other child elements such as

event1 and jobtitle representing associations sourced on the association (Harold

Ferny event 1197)

Mixed content is not allowed

All element types are declared to have either element content or character data but not

both This ensures that the validation of imported XML documents provides a useful

check against the structure that Sentences is expecting

This rule means that where a Sentences entity has both its name and associations

included in the XML document then a new element must be created to hold the name

This element is always called _value The Employee entity in the Figure 8-1 shows

this

Derived element type names

Element type names in an XML document must follow the rules laid down in the XML

recommendation Only a restricted set of characters are allowed and names must be

unique within a document type Sentences derives element type names from query node

names which are not restricted in this way Sentences uses a simple mapping algorithm to

do this

bull if the name does not start with a letter an X is inserted at the beginning

bull any characters other than numbers letters or spaces are removed

bull all spaces are replaced by period (ldquordquo) characters

bull if the resulting name clashes with a name already used in this document type a number

is appended to make it unique

The effects of these rules can be seen in the Figure 8-1 for example event1 which is

distinguished from event and jobtitle which has a period separating the words

instead of a space

Split multiple lines

Multiple lines of data may appear as multiple elements If the format mode (see ldquoOutput

Format parameterrdquo ) is set to formatted then any entity type whose presentation is

multi-line text box has its values split into lines and each line appears as a separate

_value element as shown in Figure 8-2

ltEmployeegt

lt_valuegtHarold Fernylt_valuegt

ltemailaddressgtmailto fernyhsleepysoftcomltemailaddressgt

lteventgt

ltDategt01011997ltDategt

ltevent1gt

ltEventgtJoinedltEventgt

ltevent1gt

ltjobtitlegt

ltJobtitlegtJunior Systems AdministratorltJobtitlegt

ltjobtitlegt

ltsalarygt$35000ltsalarygt

lteventgt

ltEmployeegt


Sentences and XML

391

Figure 8-2 Example of _value elements in XML output

This format makes it possible to display the data in an HTML page with line breaks in

appropriate places which would not be possible just by including line breaks in the data

since these are not significant in HTML

If the data is not intended for mapping into HTML you may want the address text as a

single element If the format mode is set to unformatted the same data appears as

follows

ltaddressgt116 South Alfred Streetampx0aBrooklynampx0aNY 11217ltaddressgt

Line breaks in the data are shown as ampx0a which is the XML representation of a line-

feed character

Allow the action attribute

When you import data you may want to specify whether an element should cause a new

Sentences instance to be created or not See ldquoMapping XML Datardquo 8 for a description of

the use of the action attribute to control this The DTD generated for a Sentences query

always allows for the inclusion of an action attribute on every element where it applies

except for those corresponding to value types

Include Sentences IDs

You may want to configure an application program to use XML Export to retrieve data

from Sentences and then to use XML Import to make changes to Sentences For this to

work successfully you must make sure that the import process uses the same specific

instances referred to in the exported data You can do this by including Sentences IDs in

the XML document See ldquoSentences IDs parameterrdquo 6 and ldquoMapping XML Datardquo for

details of how achieve this

The lazyid attribute is optional for importing data

Combining simple elements

Sentences combines simple elements that is elements with no child elements with their

parent elements where appropriate This happens in two types of situation

bull If an entity type has no associations included in this query and it is not being split into

multiple lines Sentences does not use the _value element The name of each instance

appears as the content of the corresponding element For an example see the Date entity

type which appears as the target of (Employee event Date) in the Employee example

shown in Figure 8-1

bull If an association type has no associations included in this query and its target is a value

then the target is combined with the association The emailaddress element in the

example in Figure 8-1 shows this The full association type is

(Employee email address Hyperlink) but as there are no dependent association types

Sentences does not use the Hyperlink element

Using Element IDs

A deeply-nested query may include information about the same instance more than once

and the XML standard provides a way to avoid repeated data by allowing an element to

ltaddressgt

ltAddressgt

lt_valuegt116 South Alfred Streetlt_valuegt

lt_valuegtBrooklynlt_valuegt

lt_valuegtNY 11217lt_valuegt

ltAddressgt

ltaddressgt

Setting XML options in the Query Editor

Sentences and XML

392

have an attribute of the type id which identifies it uniquely within the document and

other elements to refer to it by means of attributes of the type idref

You can ask Sentences to include element IDs and to refer to them where appropriate by

setting the Use Element IDs option on the query (see ldquoElement IDs parameterrdquo ) This

option applies to all complex element types but not to simple element types (see

ldquoCombining simple elementsrdquo )

Including Element IDs has two effects as follows

bull Every element containing data has an id attribute which is a label generated by

Sentences for example

ltEmployee id=N1gt

lt_valuegtBarney Norrislt_valuegt

bull Wherever this element type can appear it may be replaced by a reference element

which contains no data but uses a ref attribute to refer to an earlier node for example

ltreferencetoEmployee ref=N1gt

In most cases this just serves to reduce the size of the document but sometimes it is

essential to prevent an infinite loop Whenever an indirect query node occurs both it and

the node it refers to always use element IDs to avoid the possibility of an infinite loop

occurring

When the Include Element IDs option is set on a Sentences query an XML document to

be imported can also include ID attributes and use reference elements to refer to the

earlier elements


You can use the Query Properties dialog in the Query Editor to set a number of default

properties for XML output including

bull setting a default stylesheet

bull setting the default DTD reference (external internal or none)

bull setting the output format

bull including XML Element IDs

bull including Sentences IDs

These settings apply for XML import and export operations which use the query unless

they include their own settings which would override these For detailed instructions for

these settings see ldquoXML properties dialogrdquo You can also rename request nodes in the

Query Editor to determine the name for your XML output document and the names of the

XML elements in the document For more details see ldquoNode name considerations for

XML outputrdquo

The Diagram Editor

Sentences diagrams

393

Chapter 9

Sentences diagrams

This chapter describes how to work with the Sentences Diagram Editor


bull creating diagrams

bull printing diagrams

bull exporting and importing diagrams

The Diagram Editor

The Sentences Diagram Editor displays entity and association types and other schema and

data elements in a graphical layout For example an association typersquos source and target

are displayed as graphical objects with a line connecting them to represent the association

type structure This connecting line is labelled with the association type verb

The Diagram Editor can be used to explore and clarify an existing schema It is not a tool

for editing a schema or for creating new schema elements

Starting the Diagram Editor

To start the Diagram Editor select Diagram Editor from the View Menu

Figure 9-1 The Diagram Editor

The Diagram Editor is shown in Figure 9-1 There can only be one Diagram Editor open

at any time While the Diagram Editor is open you cannot change the profile

If you close the Diagram Editor and reopen it without changing your profile Sentences

displays the last diagram you worked on If you close the Diagram Editor and change

your profile and then reopen the Diagram Editor Sentences displays a blank diagram

although your Preferences settings are retained

Diagram Editor components

The editor is made up of three components the toolbar a schema tree and the canvas

The Diagram Editor

Sentences diagrams

394

Toolbar

The toolbar gives quick access to frequently used actions All the actions are available on

the Diagram Editor File Edit or View menus or the from the Diagram Editor

Preferences dialog The toolbar buttons are described in the following table

Button Description

Export - export the diagram

Import - import an exported diagram

Stops execution of queries

Print

Delete - deletes selected diagram elements

Default Dataform - can be opened on diagram elements that

represent instances

Preferences - opens the Preferences Dialog

Diagram quality - toggles between outline quality and

presentation quality

Increase and Decrease font size

Zoom in and Zoom out

Help

Schema tree

The schema tree displays the same items as the schema tree in the Sentences Explorer

Canvas

The canvas is where diagram elements are displayed You can move elements freely on

the canvas by dragging them with a mouse or by using the Shift key and an arrow key on

the keyboard For more details see ldquoDiagram elementsrdquo 4

Diagram Editor preferences

You can control the appearance of the canvas and the Diagram Editor in general by

changing settings in the Preferences dialog These settings are not retained from one

session to another

The Diagram Editor

Sentences diagrams

395

Figure 9-2 The Diagram Editor Preferences dialog

To view the preferences dialog select Preferences from the View menu or click the

Preferences button on the toolbar The following options can be adjusted on the

Preferences dialog

bull Font

You can specify a font and adjust the size and style The Preferences dialog displays a

sample of the selected font

bull Association type and association labels

You can specify how association types and associations are labelled in the diagram The

labels may include the association verb or association verb and target or association

source verb and target

bull Zoom factor

You can set the zoom factor for your drawing The available values are from 10 25

50 75 100 and 200 You can also adjust the zoom factor directly by selecting the

magnifying glass buttons on the toolbar The zoom factor controls the

presentation of the diagram on the screen and does not affect the printed output

which is scaled automatically

bull Diagram quality

You can select either Outline Quality or Presentation Quality for the diagram

The Diagram Quality on the toolbar toggles between these two settings

bull Results limit

You can adjust the limit for the number of query results that can be placed on the

diagram The default value is 100 The Diagram Editorrsquos response time starts to slow

down if there are too many elements on the canvas and the readability of printed output is

also affected

The Diagram Editor

Sentences diagrams

396

Diagram elements

You can display Sentences schema and data items on the canvas These include entity and

association types custom Dataforms and queries You can also display query results

Only one instance of any Sentences element can be displayed on the canvas

Diagram element types

There are six types of diagram element that can be shown on the canvas All diagram

elements have their own shortcut menus for adding other relevant diagram elements

bull Entity type diagram element

An entity type is shown as a purple rectangle Subset types are shown as yellow

rectangles Value types are shown as ovals

bull Association type diagram element

Association type diagram elements are lines that join the source and target with the verb

text displayed at a point along the line In a normal diagram straight lines are used and

curved lines are shown in high quality diagrams Lines for association types are purple

except for subset association types which are yellow

You can move the point at which the verb text is displayed by moving the verb text The

direction of the association is shown by an arrow The verb text can have one of four

formats which can be selected on the Preferences dialog (see ldquoDiagram Editor

preferencesrdquo )

bull Query diagram element

The Query diagram element is a blue rectangle There is a tool tip display to indicate what

kind of query it is You can add query results to a diagram See ldquoAdding Query Resultsrdquo

bull Custom Dataform diagram element

The Custom Dataform Query diagram element is a dark grey rectangle

bull Entity diagram element

An entity diagram element is a cyan rectangle A value entity is shown as a cyan oval

bull Association diagram element

Association diagram elements are lines that join the source and target with the verb text

displayed at a point along the line In a normal diagram straight lines are used and curved

lines are shown in high quality diagrams Lines for association diagram elements are

cyan

Adding diagram elements

To add a Sentences element to the Diagram Editor canvas you can drag it from the

schema or data pane of the Sentences Explorer or from the schema pane of the Diagram

Editor or the Query Editor or from the Query Editor results pane

Sentences places the new element wherever you drop it by releasing the mouse button If

the object you are adding to the canvas is an association type or association and either the

source or the target is already present on the canvas Sentences creates a visual link to the

source or target

You can also use the Edit menu or the canvas shortcut menu and select either Add Core

Entity Types or Add All Entity Types to add elements to the canvas

Adding annotations titles and legends

You can add annotations titles and legends to the diagram on the canvas

bull Annotations

The Diagram Editor

Sentences diagrams

397

An annotation is a resizeable text box You can freely edit the text The font is the same

size and style as defined for diagram elements Annotation text boxes have a border and a

light yellow background

To add an annotation select Add Annotation from the Edit Menu or from the canvas

shortcut menu After you have created an annotation you can edit it by selecting it and

pressing F2 or by selecting Edit text from the shortcut menu

bull Titles

A title is a resizeable text box You can freely edit the text The font is the same style as

defined for diagram elements but 25 larger Title text boxes have no border and no

background

To add a title select Add Title from the Edit Menu or from the canvas shortcut menu

After you have created a title you can edit it by selecting it and pressing F2 or by

selecting Edit text from the shortcut menu

bull Chapter Legends

Chapter Legends are read-only They show the name of the profile and a list of the

chapters in it If the Chapter Number option is set then the chapter numbers are included

in the Legend You can resize a Chapter Legend box

The font used for Chapter Legends is the same style as defined for diagram elements but

15 smaller Chapter Legend text boxes have a light blue background and a border

Selecting diagram elements

You can select a diagram element by clicking on it To select more than one diagram

element hold the Ctrl key and click on the elements

You can also select elements by dragging the mouse over them The Diagram Editor

displays a selection area and all the elements inside the area or intersected by the

selection boundary are selected

To select all the elements on the canvas select Select All from the Edit menu or from the

canvas shortcut menu or press Ctrl+A

Deleting diagram elements

To delete a diagram element select Remove from the Edit menu or from the canvas

shortcut menu

To remove all elements select Remove All from the Edit menu or from the canvas

shortcut menu

Moving diagram elements

To move a diagram element with the mouse click on it and hold the mouse button while

dragging it to a different position To move a number of selected elements at the same

time press and hold the Ctrl key

You can use the keyboard to move diagram elements Select an element and hold down

the Shift key and use the up down left and right arrow keys to move the element

Consistency with Sentences Explorer

Some of the settings in the Sentences Explorer are automatically used in the Diagram

Editor

bull If Chapter numbers or Lazy IDs are displayed in the Sentences Explorer they are added

to the names of the diagram elements on the canvas

bull If you delete a schema or data element in the Sentences Explorer then any diagram

element representing or depending on that schema or data element is removed

Exporting and importing diagrams

Sentences diagrams

398

bull If you rename a schema or data element in the Sentences Explorer then any diagram

element representing or depending on that schema or data element is renamed

Adding Query Results

You can display queries and their results on the diagram

To add query results to a selected query on the canvas select Add query resultshellip from

the Edit menu or from the shortcut menu

If you select Add query resultshellip from the Edit menu when no query is selected

Sentences displays a picker showing the available queries

The Diagram Editor cursor changes to a precise cursor so that you can select the part of

the canvas where the results should be displayed To cancel placing the query results

press Esc

There is a limit to the number of results that can be placed on the diagram This limit can

be set using the Preferences dialog (see ldquoDiagram Editor preferencesrdquo )


Sentences currently does not store diagrams in the database However you can export a

diagram as a file and then import it later The export file includes all the diagram elements

currently on the canvas and all your current preferences

The export file contains data in a format that is relative to the current profile You cannot

export a diagram using one profile and import it using a different profile The export file

is also dependent on the current state of schema and data in the profile If a diagram

export file includes references to schema or data elements that have been deleted it cannot

be imported into the Diagram Editor

When you import a diagram export file that includes temporary data such as query results

based on derived types only the persistent items are displayed and the temporary items

are not displayed

Export

To export a diagram select Export diagram from the File menu Sentences displays the

file dialog for your system Select a location and enter a file name and click Export to

export the diagram or select Cancel to return to the Diagram Editor

We recommend using the file extension lzd to identify diagram export files

Import

To import an exported diagram select Import diagram from the File menu Sentences

displays the file dialog for your system Select a location and select a file name Click

Import diagram to import the diagram or select Cancel to return to the Diagram Editor

Saving as a GIF file

You may also save the current diagram as a GIF file You can then work with the GIF file

in any suitable graphics editing program or import the GIF file into any suitable word

processing program

To save a diagram as a GIF file select Save as GIF from the File menu Sentences

displays the file dialog for your system Select a location and enter a file name and click

Save to export the diagram or select Cancel to return to the Diagram Editor

Printing

You can print a diagram to a printer attached to your system Printing is only currently

supported for Microsoft Windows systems Printing on Linux and Mac OS X platforms

depends on the printing setup

Printing

Sentences diagrams

399

The Diagram Editor automatically includes all the diagram elements that are on the

canvas in the printed output The entire diagram is scaled to fit onto a single page for

printing This means that the greater the number of diagram elements present on your

canvas the smaller the size of each element when you print your diagram

The Diagram Editor displays two paper edge guide lines to showing the right-hand and

lower edge of the printed area You may not place any diagram elements outside the

printed area

You can choose either Portrait or Landscape orientation for printing The position of the

paper edge guide lines changes to match your selection To change the paper orientation

select Page Setup from the File menu

To print your diagram select Print from the File menu Sentences displays the standard

printing dialog for your system

Sentences API overview

Customising Sentences

401

Chapter 10


This chapter looks at some of the techniques you can use to customise Sentences

bull you can use the Sentences API

bull you can create database triggers

bull you can create custom datatypes

As all these techniques involve writing your own Java classes and methods and using

parts of the Sentences API the information in this chapter is written for experienced

programmers with knowledge of Java

Your Sentences installation includes some code examples that demonstrate the

implementation of custom datatypes and triggers and the client API These examples

are explained in Chapter 11 ldquoWorked examplesrdquo

This chapter also describes how to create customised Help pages for your Sentences

application and includes notes on translation and localisation


Note When you install Sentences some API features are disabled You are recommended

to implement security settings on your web server before you these features For more

information see ldquoServlet access to Sentencesrdquo

The Sentences Application Program Interface (API) is a programmatic interface to the

Sentences database It is a collection of Java classes which can be used to extend the

functionality of Sentences Using the Sentences API programmers can write their own

Java programs to customise and extend the functionality of Sentences

To use the Sentences API effectively you should have some understanding of the

associative model of data and of Sentences as well as experience in software

development and thorough knowledge of the Java programming language Instructions on

how to write Java code are not given in this book

This section provides an overview only of the Sentences API and is designed as an

introduction to the more detailed information given in the online documentation

Sentences API

Sentences provides two different API systems one for use on the client (the Client API)

and one for use on the server (the Server API) Access to these API systems is through

one or other of the gateway classes ClientApi or ServerApi which are both part of

the package comsentencesapi

Sentences Version 40 introduces a User Security model which requires the authentication

of a user when connecting to the Sentences Server

For the Server API exclusive access to the Sentences database is required and so the

current user in a Server API session is automatically the System Administrator

For the Client API a client programme must authenticate its user to set the current user

and gain their privileges



402

The comsentencesapiClientApi class allows the programmer to create a Client

Session The comsentencesapisessionClientSession in turn provides the

method authenticate(String username String password) to facilitate this

Once authenticated the current user is available through the method

public User getCurrentUser()

which the ClientSession inherits from the DatabaseSession interface

A LazyException is thrown if the user is unknown or the password is incorrect

Comparing the Sentences Client API and Server API





The Sentences Client API allows Java programs to access the Sentences database

alongside other clients such as the Sentences applet You must make sure that your server

is configured to allow Client API access by verifying the settings in the

Serverproperties file (see ldquoServlet access to Sentencesrdquo ) An example of a client

API program is given in the section ldquoClient API examplerdquo The Client API can execute

queries With regard to updates the Client API like the Sentences applet packages

transactions and only writes updates to the database when a transaction is committed (this

is analogous to a user clicking the Save button on a parent Dataform)

The Client API is not available with Sentences Personal Edition

The Sentences Server API is used by standalone Java programs which are executed on the

server machine The Server API cannot execute queries Java programs that use the

gateway class ServerApi require exclusive access to the database Triggers are also

written with the Server API but they do not use the gateway class ServerAPI

With regard to updates the Server API writes updates to the database immediatelyEven

though these updates are not made permanent until the transaction is committed they are

immediately available to the Server API program that made them This makes the Server

API useful for writing programs which must make very large updates to the database



ltSentences_homegtDocapihtml The Javadoc files for the Sentences API can be

found in ltSentences_homegtDocjavadoc

Example code and online documentation

This Userrsquos Guide does not include code examples but examples are included in the

Sentences distribution

These items of example code can be found at

ltSentences_homegtExamplescomsentencesexamples

The publicly-available classes and methods of the Sentences API are described in

a series of online documents for programmers which can be found at

ltSentences_homegtDocapihtml

Program build and execution

All Sentences API programs must be written in the Java programming language All the

tools and components necessary to build and run Java programs with Sentences are



403

contained either in the standard Sentences Enterprise Edition delivery or in the Java

Software Development Kit which is available from Oracle

The current version of the Java Software Development Kit can be downloaded from the

Java website

httpwwworaclecomtechnetworkjavajavaeedownloadsindexhtml

Sentences API programs can be built and run using the standard Java compilation

(javac) and execution (java) utilities

API packages

The Sentences API is divided into nine packages as follows

Package name Area

comsentencesapi factory and helper classes for the API

comsentencesapievent interfaces for observing things stored in the

Sentences database

comsentencesapiexceptions exception classes used in the API

comsentencesapiobject classes and interfaces for Sentences

datatypes

comsentencesapiobjectui panels for changing the property values of a

particular datatype

comsentencesapirequest interfaces for creating and executing

queries

comsentencesapisession interfaces for accessing the database

comsentencesapithings interfaces for manipulating things in the

database

comsentencesapitrigger classes and interfaces for triggers

Class hierarchy

The database class hierarchy as used by the Sentences API is shown in Figure 10-1

below

Figure 10-1 Class hierarchy for API Session view of database structure

The terms entity association entity type and association type used in Figure 10-1 have

the same meaning for the API as they have for any user of a Sentences schema or of

Sentences data Within the database they may also refer to and serve to store system

defined properties schema definition components and other components used by

Sentences for internal purposes

Anything that is stored in a Sentences database is represented as an object of one of the

LazyThing subclasses shown above The source or target of any association is a

Triggers


404

LazyThing This class includes methods that apply to all database items including

deleting the item retrieving associations involving the item and many others

The subclasses of LazyInstance represent instance data rather than schema data A

LazyEntity corresponds to an entity instance A LazyAssociation corresponds to

an association with a defined source and target

A LazyType is part of the schema It represents anything that can have instances The

LazyType class includes methods relating to instances and methods relating to

supertypes and subsets

LazyEntityType and LazyAssociationType represent entity types and association

types respectively

Triggers

Triggers in Sentences are similar to ldquostored proceduresrdquo in some other databases To use a

trigger you first create your own Java code for the trigger using the Sentences API To



the Serverproperties file Trigger code is assigned to an entity or association type

in Sentences using the Triggers page of the Properties dialog

You can create generic trigger code that can be attached to more than one Sentences type

For example you could create a trigger that would reject a delete request and attach it to

one or more entity or association types Whenever a user tried to delete an instance of a

type that had this trigger attached the delete action would not be allowed

Note It is possible to prevent the deletion of instances in Sentences by selecting the

Instances cannot be deleted property in the Properties dialog for the entity type or

association type

When you design triggers remember that one trigger may be used with more than one

type and make sure your trigger can handle not only relevant notifications but also any

non-relevant notification it may receive Give your trigger a meaningful name and make

the triggerrsquos package and class names clear as well This helps ensure that your trigger is

assigned to appropriate cases

Server-side triggers

Triggers are instances of Java classes which implement the LazyServerTrigger

interface You can associate a server side trigger with types through the Properties dialog

(see ldquoTriggers properties pagerdquo )

Sentences triggers on relevant entity and association types can be invoked for the

following database update events

Event When Fired

Create an instance is created

Delete an instance is deleted

Rename an instance is renamed (only available for entity

types)

Association Moved a sequenced association is reordered (only

available for association types)

Triggers


405

Event When Fired

Attribute Changed

an instance of the type has become or has

ceased to be the source of an association

when an association is re-sequenced deleted

added or superseded an Attribute Changed

event is fired for the source of that association

type

Supersedes Added an instance is superseded

Target Changed the target of an association is changed (only


Set Equivalent an instance has an equivalent assigned

Remove Equivalents an equivalent instance is removed

When invoked a trigger can retrieve information related to the update event which has

triggered it

Trigger code usually has dependencies on the Sentences schema it has been designed to

work with If the schema is changed triggers may not operate correctly until the

Sentences server has been stopped and restarted following the changes The trigger code

itself may need to be changed

Trigger examples

For examples of how triggers may be used see Chapter 11 ldquoWorked examplesrdquo Java

source code and a JAR file for some example triggers can be found in the Examples


Triggers and the Sentences API

The Sentences API is described in a series of HTML files in the Doc directory of your

Sentences installation There is an overview of the Sentences API in Docapihtml

This document contains links to sections on different aspects of using the Sentences API

including how to create triggers and custom datatypes

Installing a trigger

To use a trigger you must write your own Java code compile the code into a Java archive


the Serverproperties file You can then use the Triggers properties page to assign

the trigger to a particular entity or association type The detailed steps for attaching a

trigger to an entity or association type and how to edit trigger assignments are given in

the next section

Attaching a trigger

To view the list of triggers available on the Sentences server select Triggers from the

View menu Sentences displays the Available Triggers list

Triggers


406

Figure 10-2 The Available Triggers list

You can expand a trigger node in the Available Trigger list to show the Java class name

for the trigger a brief description of the trigger and a folder listing all the types currently

using the trigger

To attach a trigger to an entity or association type follow these steps

1 Open the Properties dialog for the type and then open the Triggers page shown

in Figure 10-3

Figure 10-3 The Triggers page before triggers are assigned

2 Click the Add button Sentences displays the Add Trigger Assignment dialog shown

in Figure 10-4 This shows a list of all available triggers in the left hand list box and the

set of possible trigger events shown on the right-hand side Only the trigger events that

Triggers


407

are relevant to the type selected (entity or association) are available Choose All to

activate the trigger for all update events

If there are no server triggers available Sentences displays an error message

Figure 10-4 The Add Trigger Assignment dialog

3 Select a trigger from the triggers list and select a trigger event or All trigger events

and click OK

4 The Triggers page now lists the assigned triggers and trigger events as shown in Figure

10-5

Figure 10-5 The Triggers page showing assigned triggers

If you have more than one trigger for the same event you can change the order in which

they are activated by highlighting a trigger event row and using the Move Up and Move

Down buttons

To remove one or all triggers use the Remove or Remove All button

You can change the trigger event assignment for a trigger by highlighting a trigger event

row and clicking the Edit button Sentences displays the Edit Trigger Assignment

dialog This is similar to the Add Trigger Assignment dialog shown in Figure 10-4

except that the All option is not available

Triggers


408

Trigger threading issues

The Sentences server ensures that all transactions against a profile and all updates within

each transaction are processed in series As chapters may be shared between multiple

profiles all chapters in a profile are locked during the processing of a transaction Trigger

code execution is completed within transaction processing and hence trigger code

execution is always single-threaded

A single trigger class may be used by multiple profiles if appropriate A new instance of

the trigger is created for each profile This means that when you write a Sentences trigger

you only need to be concerned with threading issues with regard to class variables in your

trigger classes and any shared instances of non-Sentences classes which their trigger code

may make use of

Trigger invocation

The notify()method of one or more triggers may be invoked one or more times when a

given update is applied to the database It is possible for a given trigger to be invoked

more than once for what might appear to the end-user to be a single update

Triggers are only invoked as a result of updates being made to the database using the

Sentences user interface the Sentences API by other triggers or by the trigger itself

while the trigger is active Triggers are not invoked on instances of entity or association

types which existed prior to the trigger being registered

Details of the update events for which triggers notify() methods are invoked can be

found in the Javadoc for the LazyServerTriggernotify() method

The notify() method is invoked before the transaction is confirmed as being

committed to the database Transactions may be aborted if any update within it is vetoed

either by data validation rules built in to Sentences or by a trigger or if some unexpected

failure occurs For all events other than Delete events the trigger code in the notify()

method sees the content of the database as if the entire transaction had been committed

even though the database has not yet been updated For Delete events the trigger code in

the notify() method sees the content of the database before the update has been made

and so a delete trigger can inspect the database before any changes are made

In general a trigger needs to inspect the event type that invoked it the instance which was

updated and possibly also other instances in the Sentences database in order to determine

what kind of update caused its invocation and what action should be taken


are invoked as normal when you click the Save button (see ldquoCustom Dataform

restrictionsrdquo )

Trigger actions

When the notify() method of a trigger is invoked it can either veto the triggering

update by throwing a LazyRuleViolation exception or perform some other action

which is appropriate when that update occurs

Trigger code and system validation rules that test for cardinality violations occur together

for each distinct update in a transaction For each update action in the transaction any

notify() methods which exist for the affected types are called followed by the

application of the system checks The updates are processed in series in the order in which

they occur in the transaction

Customised validation (rules)

A trigger can veto its triggering update by throwing a LazyRuleViolation exception if

it considers that the update would be invalid and this results in the update being aborted

Custom datatypes API


409

If the aborted update is part of a transaction containing other updates then all the updates

in the transaction are aborted

If a trigger throws a LazyRuleViolation exception Sentences alerts the user that

unacceptable data has been entered The trigger writer has a choice of constructors for the

LazyRuleViolation and this choice affects how Sentences communicates the error to

the user

When an update initiated by a user is vetoed by a trigger an error message is displayed in

the Sentences Message Log This is either the message returned by the triggerrsquos

getDescription() method or the message encapsulated in the LazyRuleViolation

depending on which LazyRuleViolation constructor was used

In addition in cases in which the trigger has provided the information Sentences

highlights the data which is invalid This may not be possible in all cases for example

where that data was entered on a child Dataform which has already been closed

Customised actions

You can design a trigger that can take any action in response to a given update eventFor

instance the trigger might make further updates to the Sentences database

To do this the trigger creates a new child transaction of the transaction whichcontained

the triggering update so that the further updates are either committed or aborted along

with the triggering update A trigger should not attempt to add further updates to the

transaction which contains the triggering update

When you write a trigger you must make sure that any new child transactions the trigger

creates are either committed or aborted prior to the return from the notify() method

because otherwise the parent transaction containing the triggering update and possibly

containing other updates too is aborted After a trigger has committed a child transaction

system validation rules and trigger code notify() methods invoked on any following

updates see the contents of the database as modified by that child transaction The

notify() method can also take account of Client Parameter settings for determining

trigger actions

You can write a trigger that may take some action outside the Sentences database such as

sending an email message External actions are taken without reference to the success or

failure of the triggerrsquos actions inside the Sentences database For example if you write a

trigger that sends an email message the message would be sent even if the triggering

update itself was aborted

For more information please refer to the online documentation for the Sentences API in

the Doc directory of your Sentences installation

Using triggers with import and export

Trigger code is not invoked when you import or export a Profile (see ldquoExporting and

importing databasesrdquo )

Triggers are optionally applied to data from CSV files (see ldquoCSV Importrdquo ) and to data

from XML files (see ldquoImporting XML datardquo 0)


The Sentences datatype mechanism controls the format in which entity names are entered

by or presented to users and also controls some aspects of entity behaviour such as

whether an entity can participate in arithmetic or not Several datatype classes are

provided as part of Sentences including Number Timestamp and Text When you

assign any one of the datatypes provided with Sentences to an entity type you may

convert it to a value type The behaviour of value types is described in ldquoValue types and

datatypesrdquo



410

A Java programmer can also create tailored datatypes known as custom datatypes by

writing Java classes which implement the LazyDatatype interface It is possible to

create a custom datatype that controls the formatting of an entity type but does not make

the entity type behave as a value type There is a detailed example of a custom datatype in

Chapter 11 ldquoWorked examplesrdquo

Custom datatypes behave in virtually the same way as the Sentences-supplied datatypes

and both can control the behaviour of an entity type Details of the behaviour which can

be controlled and how such a class can be programmed can be found in the online

documentation for the custom datatypes in the Doc directory of your Sentences

installation (see the document datatypeshtml) and also in the Sentences Javadoc

documentation (see the section on the comsentencesapiobjectLazyDatatype

interface)

A custom datatype class may be produced either by implementing the LazyDatatype

interface from scratch by subclassing LazyAbstractDatatype or by subclassing

another Sentences-supplied datatype To assist with the subclassing options the source

code of the Sentences-supplied datatypes is supplied in

ltSentences_homegtExamplesExistingDatatypesjava

Datatype capabilities are programmed into the Java class which provides the datatype

and cannot be changed by the Sentences end-user When correctly configured a custom

datatype appears as an available choice in the Datatype page of the Properties dialog for

entity types A schema designer or administrator can set the datatype of any entity type as

required and can choose a suitable output format from those offered by the datatype

When an entity type is created which has the same name (case-sensitive) as a custom

datatype then the datatype of that entity type is by default set to the custom datatype

The Java source code and JAR file for an example custom datatype can be found in the

ltSentences_homegtExamplescomsentencesexamplesdatatypes

subdirectory


Sentences Version 40 extends the existing Custom Datatype API

Two new methods allow you to override the default field width for your custom datatype

and to override the default format pattern if applicable

Answer the default field length used for the format when

creating a new EntityType

Override to change the default of ltVariablegt

return int

since 40

public int getDefaultFieldWidth()

Answer the default field format pattern (Style) used for

the format when creating a new EntityType

Override to change the default of ltDefaultgt

return String

since 40

public String getDefaultFormatPattern()

Installing a custom datatype

To install a custom datatype you must write your own Java code compile the code into a

Java archive (JAR) file and place the JAR file in the directory listed in the

DatatypePath property in the Serverproperties file By default this directory is

Adding custom Help topic pages


411

ltSentences_homegtDataypes The custom datatype appears in the list of datatypes

available in the Datatype properties page

The Java class for the custom datatype must implement the LazyDatatype interface

which is part of the Sentences API

Custom datatypes and import and export

Any custom datatype that is installed according to the instructions in the previous section

is available for use with the Sentences serverrsquos import and export routines

Removing custom datatypes

To unload a custom datatype remove its JAR file from the directory referenced in the

DatatypePath parameter of the Serverproperties file When you have done this

the custom datatype is no longer available for assignment to any types

However if you do not delete all the existing references to a custom datatype from the

database itself Sentences displays an error message each time the undefined datatype is

referenced The references that need to be removed are

bull all entity type properties specifying the datatype as in use for an entity type

bull all entity instances created when any datatype specification was in place and all

associations to those instances

Where the datatype represents a value type which is the default complete removal of the

value instances can only be achieved by removing the affected chapter from all profiles

If it is not possible to remove the chapter in which the custom datatype was used you

must export your profile and then import it in order to remove references to the custom

datatype


You can add custom Help for any Sentences Dataform To do this you need to create Help

topic pages and a Help topic mapping file

The Help pages you create are displayed as HTML pages in a Web browser when a user

clicks a Help button on a Dataform

Help button display

The Dataform Help button is created automatically by Sentences for any Dataform that

has a Help page listed for it in the mapping file An example of a Dataform with a Help

button is shown in Figure 10-6

The Dataform can display only one Help button The Help page called by clicking the

Help button is the page mapped to the source type of the Dataform or in the case of

custom Dataforms the page mapped to the custom Dataform name



412

Figure 10-6 Example of a Help Button on a Datatform

Precedence of Help pages

If a Help page has been mapped for a custom Dataformrsquos name that page is displayed

when the Help button is selected For all other Dataforms and for custom Dataforms for

which there is not a specific mapping the page displayed when the Help button is

selected is the page mapped to the Dataformrsquos source type

Updating Help topic mappings

Help topic mappings are only read by Sentences when the Sentences applet is loaded by

the Java Plug-in and therefore any changes made to the mapping file are only effective

after the applet is restarted

Creating Help topic pages

You can use any suitable HTML editor or text editor to create your Help topic pages The

pages must be formatted as HTML files that can be opened in a Web browser The Help

pages may contain any combination of text graphics and hyperlinks that is supported by

the HTML standard

The Help topic pages should be saved in a format that can be served by a Web server and

displayed in a Web browser for example as HTML pages with the suffix html or

htm

You may choose to create a separate file for each Help topic page you create or to create

one file containing a number of topics each identified by an HTML anchor tag

ltA NAME=rdquoanchor namerdquogtanchor nameltAgt

Creating a Help topic mapping file

The Help topic mapping file is a plain text file which contains a list of name=value

pairs These pairs map the Sentences elements (entity or association types or custom

Dataforms) to their associated Help topic pages



413

Name and location of the Help mapping file

The name of the Help mapping file must have the following name

DataformHelpTopicsproperties

This file must be located in the Web application directory for Sentences The full path for

this directory is

ltSentences_homegtTomcat4WebappsSentences

In Sentences Personal Edition this file is in the ltSentences_homegt directory

Mapping Sentences elements to a Help topic

To map a Sentences element to a Help topic create a line in the help mapping file with

the Sentences element as the name and the URL for the Help topic file as the value in a

name=value pair

When you create a mapping line you must follow these guidelines

bull For all the Sentences elements use the same capitalisation as is used in the schema

bull Replace any spaces with underscore characters

bull Enclose all association type names in parentheses characters ( ldquo(rdquo and ldquo)rdquo ) using nested

parentheses for nested associations

bull Separate the source verb and target of association types with commas

bull Do not use a space after a comma or before or after a parenthesis character

The URL for a Help topic file can be relative in which case the Web application directory

for Sentences is the reference base for the URL For more information about using

relative URLs see the sections ldquoFile system permissionsrdquo and ldquoVirtual directoriesrdquo

bull Entity type mapping example

To map the entity type Employee to a Help topic page named Employee_helphtml

located in the Web application directory for Sentences use the following line in the

mapping file

Employee=Employee_helphtml

If you use HTML anchor tags in your Help topics file you can append anchor names to

the Help topic file URL for example

Employee=Employee_helphtmlanchor

bull Association type mapping example

To map the association type (Employee next of kin Person) to a Help topic page

named Next_of_kin_person_helphtml located in the

ltSentences_homegtTomcat4WebappsSentences directory use the

following line in the mapping file

(Employeenext_of_kinPerson)=Next_of_kin_person_helphtml

To map the nested association type ( (Employee next of kin Person) lives in Town)

to a Help topic page named Lives_in_Town_helphtml in the

ltSentences_homegtTomcat4WebappsSentences directory use the following line

in the mapping file

((Employeenext_of_kinPerson)lives_inTown) sect

=Lives_in_Town_helphtml

bull Custom Dataform mapping example

To map the custom Dataform EmployeeDataform to a Help topic page named

EmployeeDataformhtml located in the

Localisation notes


414

ltSentences_homegtTomcat4WebappsSentencesCustomHelp directory

use the following line in the mapping file

EmployeeDataform=CustomHelpEmployeeDataformhtml

You can map child Dataforms opened from the custom Dataform to specific Help files or

to named anchors in specific Help files

To map the child Dataform Person opened from the custom Dataform

EmployeeDataform to the named anchor Person on a Help topic page named



in the mapping file

EmployeeDataformPerson=EmployeeDataformhtmlPerson

Child Dataforms other than those opened from custom Dataforms use the Help mapping

for their default type if any exists

Localisation notes

Sentences includes native methods for localising both system text and application text

which are described in this section Sentences does not provide an automatic capability

for translating texts You must prepare the translated text independently

Localising Sentences system text

Sentences system text includes all menus buttons messages system folder names and

system dialog labels but not type and instance names or Dataform field labels All the

system text is included in one message file Messagesproperties which is compiled

into the Sentencesjar file Sentences system text can be localised using a customised

message file distinguished by a Java Locale identifier

The Java programming language uses the Locale object to define a userrsquos language and

geographical location using standard ISO codes For example the Locale identifier

en_US represents United States English and the identifier fr_CA represents Canadian

French The Locale object is used to make sure that culturedependent items such as

language numbers and dates and times are presented to the user in an understandable

way

The Java plug-in that runs the Sentences applets can recognise a client machinersquos Locale

setting and select messages from the appropriate message file for that Locale if one

exists You can create multiple versions of the messages file each for a different Locale

to allow different clients in different Locales to use the same server

All Sentences system text is identified by numeric codes If a localised text for a specific

code is not found the English language text is used More information on the way Java

uses the Locale object can be found on the Oracle website


Extracting the Messagesproperties file

Translations of Sentences system text should usually be based on the original English

messages file Messagesproperties This is contained in both the client and server

Java archive files for Sentences (JAR files) You can extract a copy of the

Messagesproperties file using any software that can manipulate JAR files for

example the jar program that is part of the Java SDK

To extract the Messagesproperties file first make sure that the jar program is on

your path for program files and then open a command prompt and navigate to the

Localisation notes


415

directory that contains the file SentencesServerjar Then run the following

command

jar xvf SentencesServerjar Messagesproperties

This extracts the file to the current directory

Naming the translated messages file

The name of the translated messages file must conform to the following pattern

Messages_ltLocalegtproperties

where ltLocalegt is the Java Locale identifier for example

Messages_fr_CAproperties

where fr_CA represents Canadian French

Example translated messages file

The Sentences installation includes an example translated messages file

Messages_de_CHproperties with message texts translated into Swiss German

Directory location for the translated messages file

In Sentences Enterprise Edition the translated messages file must be placed in two

directories as it is used by both the server and the client These directories are the Web

application directory for Sentences and the classes sub-directory for the Sentences

Web application The full paths for these directories are


ltSentences_homegtTomcat4WebappsSentencesWEB-INFclasses

In Sentences Personal Edition place the translated message file in the


There is no need for the translated files to be compiled into the SentencesServerjar

or Sentencesjar archive files

Translating Sentences application text

Sentences application text includes the names of entity types and association types You

can use Sentencesrsquo Profile and Chapter features to create localised versions of

application text

Sentences allows the creation of separate profiles for different users and groups of users

(see ldquoUsing multiple profilesrdquo and ldquoCreating database views using profiles and chaptersrdquo

)

You can localise your application text by applying the Rename command to each entity

type or association type for which you wish to have a translated name using a separate

schema changes target chapter for each language and then making that chapter available

only in the profile accessed by users of that language

A suggested procedure would be as follows

1 Create a new chapter and add it to your profile

2 Designate the new chapter as the target chapter for schema changes

3 In your Sentences application apply the Rename command to each entity type or

association type for which you wish to have a translated name

4 To view the application text in the original language remove the chapter used as target

for the Rename actions from the profile To view the application text in the translated

language include the chapter used as target for the Rename actions from the profile

The Human resources example application

Worked examples

416

Chapter 11

Worked examples

This chapter contains an introduction to the Human resources example application

and step-by-step worked examples of a number of Sentences features as follows

bull CSV Import example

bull Derivations example

bull Trigger examples

bull Custom datatype example

bull Client API example

bull Integration with Microsoft Office applications

The examples in this chapter refer in general to the Sentences Enterprise Edition but

most of them can also be run with the Sentences Personal Edition Where this is not

possible it is noted in the text

Throughout this chapter the symbol sect indicates that a line in a file has been split to

allow display in this book only You should type in the text as one line


The Human resources example application supplied with Sentences is intended as an

uncomplicated introduction to the core features of Sentences and is used to illustrate

Sentences features throughout this Users Guide The example application is designed to

illustrate a range of features in Sentences and it is not intended to be a prototype of a

genuine human resources application Some of the choices made in developing the

database for this application might not be appropriate in other circumstances For

example the Human resources example application uses an Employee entity type In

some situations it might well be preferable to model employment as an association type

between a Person and an Organisation

This section is an overview of the example application including notes on some of the

features illustrated More information can be found in the relevant feature specific

sections of this guide You may find it useful to have the Human resources example

application available to you as you read this section

The application domain for the example application is human resources management for

the Sleepy Software group of companies Sleepy Software is a fictional global corporation

with multiple subsidiary companies These companies share resources and projects The

main uses of the application are illustrated by the entries in the Core types folder

Current employee Employee Group company and Project

The Employee entity type

People are clearly central to any human resources application The Human resources

example application includes a number of related entity types that represent people

Person Employee and Current employee

The Person entity type is used to record personal details about any person not just

employees An Employee is a Person who is or has been an employee of one of the

Sleepy Software group of companies and is defined as a subtype of Person

CSV Import example

Worked examples

417

Using Person as a supertype of Employee allows for the personal details of employees

and of their next-of-kin to be stored using the same schema elements while maintaining

the important distinction between employees and other persons

A Current employee is a Person who is an employee of one of the Sleepy Software

group of companies Current employee is implemented as a subset of the type

Employee The other subsets of Employee are Resource skills and Project Resource

Only Resource skills is the source of any association types

Dataforms automatically display tabbed pages for any supertypes or subsets of a given

type that are the sources of associations (see ldquoDataform tabbed pages with subsets and

supertypesrdquo ) Therefore the dataform for an Employee has three tabs Person (which is

the supertype of Employee) Employee and Resource skill (the only subset of

Employee that has association types sourced on it) These three tabs present associations

showing general personal details employee information and skill data respectively

Some Employees are also classified as Project resources who maybe assigned to

Projects based on the Project resource association

The Event table in the Dataform records employment history including when employees

join and leave This data is used by the query for the Current employee subset as well

as for the Latest Salaries query

The details of an employees next of kin can be accessed by viewing the Next of Kin

target instance Double-click the next of kin name or use the Viewhellip options on the

Dataform shortcut menu The Dataform for the Next of Kin selected is either a simple

Person Dataform (where the next of kin is not an employee such as Harold Ferny) or a

full Employee Dataform information (where the next of kin is an employee such as

Mary Venice)

The Group company entity type

All the fictional companies in the Sleepy group are represented using the Group

Company entity type The association types that are sourced on this entity type relate to

the companyrsquos location phone number and so on The subsidiary of association type is

an illustration of an association type that has the same type as both its source and its

target

The Project entity type

The Project entity type represents corporate projects The allocation of people (ldquohuman

resourcesrdquo) to projects is recorded using the Resources association type which has the

subset Company Resource as its target The query for the Company Resource subset

uses the association type Project resource defined on Employee to determine

whether an Employee is currently a valid resource or not

This means that you must define an employee as a Company Resource before you can

assign him or her to a Project

The query for the Company Resource subset also takes a Group company as an

optional parameter This allows use of the Target Parameters mechanism to restrict the

resources available for assignment to a project to those recorded as employed by the

single Group company selected as the Private to company For more information on

using the Target Parameters mechanism see ldquoTarget parametersrdquo

CSV Import example

CSV Import is a server-side procedure and needs to be run from the command line when

the Sentences server is not running To complete the steps in the example you also need

access to the file system to move image files to a new location

CSV Import example

Worked examples

418

The following example uses the CSV Import procedure to import information about five

new employees into the Human Resources example application The example uses a

series of example files located in the Sentences installation under the directory

ExamplesCSVImport

You can find both CSV (Comma Separated Value csv) files and jpg image files in

this location

The CSV Import procedure can only be used for adding data to an existing database and

it cannot be used to alter or create a database schema

When you use the CSV Import procedure the order in which you import data is very

important particularly if you use supertypes and subtypes in your database You must

always import subtype instances before you import supertype instances to avoid creating

duplicates

The Human Resources example application uses supertypes for example Person is a

supertype of Employee This means that when you want to add data that relates to a

Person who is also an Employee you must create the individual as an Employee first

and then add their associations as a Person In order to do this you must import the CSV

files for this example in the specific order given later in this chapter

Preparing a profile for the example CSV Import

Before you import the sample CSV files create a new profile based on the Human

resources profile This means that the original Human resources profile is not

modified and allows you to switch between the original profile and the new profile to see

the changes that you make The new profile has an additional data chapter which you

must add before importing data as CSV Import files cannot be used to make changes to a

database schema

To set up a profile for the example CSV Import procedure follow these steps

1 Open the Human resources profile

2 Open the Edit Profile dialog Type in a new profile name HR CSV Example Create a

new chapter HR CSV data and add it to the profile Do not remove either of the existing

chapters Make the new chapter HR CSV data the Data changes chapter Set the

Schema changes and Query changes chapters to (none) The Edit Profile dialog

should look like Figure 11-1 Save the profile

Figure 11-1 The Edit Profile dialog for the CSV import example

CSV Import example

Worked examples

419

3 Close Sentences and shut down the Sentences server If you are running the Sentences

Personal Edition you do not have a separate server process and so you only need to close

the program

Importing the example CSV files

To see the effect of importing CSV files you must import a number of sample files using

the CSV Import procedure for your platform Details of this procedure are given in ldquoCSV

Importrdquo You need to run the procedure separately for each file you want to import The

sample files are located in the directory

ExamplesCSVImport

The order in which the sample files should be imported is as follows

1 Employeescsv

2 Personscsv

3 Next of Kincsv

4 Resourcescsv

5 Employmentcsv

After each file is imported Sentences displays a message on the command line display as

follows

ltngt lines read

Committing changeshellip

Although you may import any of the sample CSV files more than once without affecting

the resulting data you must take care to import the files the first time in the specific

sequence given above because the HR CSV example application uses subtypes and

supertypes and therefore you must import the subtype data first to avoid duplication

Employeescsv or Employmentcsv must be imported before Personscsv or

Next of Kincsv This is because Employee is a subtype of Person Employee

instances must be created before any use is made of them as Persons

Importing data for associations targeted on associations

If you are interested in seeing how to import associations targeted on associations using

CSV import you can look at the Group company and Location columns of

Employmentcsv file using a spreadsheet program or text editor

For each line for which data exists in these columns in the Employmentcsv file

Sentences creates an association of the type Group company location Location These

associations are used as the targets for the association type employed by (Group

company location Location)

Viewing the imported data

After you have imported all the example CSV Import files start your Sentences server

and start or refresh your Sentences client Open the profile HR CSV Example and select

Employee in the schema pane as shown in Figure 11-2

CSV Import example

Worked examples

420

Figure 11-2 New Employee instances displayed

You can see that the five new employees created by the CSV import procedure are listed

in the data pane Margaret Pattison Cynthia James Tam Dreisbach Keith

Dreisbach and Nancy Williams

Figure 11-3 Dataform for Cynthia James

Highlight the name of Cynthia James and open a Dataform Look at the values for the

associations on the Employee Person and Resource tabs as shown in Figure 11-3

Adding image data

Look at the value for the Photograph association in the Dataform for Cynthia James

shown in Figure 11-3 You can see file path data and not the image itself This path

information was part of the data in the CSV file but the image file is not yet in the correct

location To view the Photograph images for the new Employees you must copy the

image files to your default image location

You can check what the default image location is for your system by checking the value

of the ImageURLbase parameter in the Applicationproperties file in the Personal

Edition or in the jnlp or javascript definition in the Enterprise Edition For more details

see ldquoAbout the ImageURLBase parameterrdquo

When you know your default image location copy the image files which all have the

suffix jpg from their delivered location ExamplesCSVImport to the LazyImages

subdirectory of the default image location

CSV Import example

Worked examples

421

After you copy the image files re-open the Dataform for Cynthia James The

Photograph association now displays the correct image as shown in Figure 11-4

Figure 11-4 Dataform showing Photograph image

Viewing additional data

The files you imported have also added three new Person entities to the application

These represent people who are not Employees but are used in the application as the

targets for Next of kin associations

To see some of this imported data select the Person entity type and open a Dataform on

either David Webb or Eddie Williams or Michael James Data related to these

individuals comes from the files Personcsv and Next of Kincsv

The files you imported have also added additional employment history data for the

existing employee Mark Goldstone You can use the Open Profile command on the File

menu to switch between the original Human resources profile shown in Figure 11-5

and in the HR CSV example application shown in Figure 11-6 to compare the contents

of the Employee event Date associations table for this employee before and after the

import

Figure 11-5 Original data for Mark Goldstone

Derivations example

Worked examples

422

Figure 11-6 Data for Mark Goldstone after importing sample CSV files

Restoring the original Human Resources profile

As you imported the CSV file data to a new profile the original Human Resources

profile was unaffected To restore the original Human Resources profile choose Open

Profile from the File menu and select the profile name

Repeating the CSV Import example

If you want to repeat this demonstration of CSV data import remove the HR CSV data

chapter from the HR CSV example application in the Edit profile dialog and then

create a new chapter with a different name and add it to the profile as the Data Changes

target

Derivations example

The Order Entry example application demonstrates the use of derivations in the Query

Editor and the resulting appearance and functionality of the custom Dataform It also

demonstrates the use of a trigger to create entity instance names when the Instance name

created by trigger option has been selected for an entity type (see ldquoInstance optionsrdquo )

The example application includes the following features

bull a custom Dataform

bull page nodes

bull derived types

bull derivations

bull derivation calculation properties

bull custom Dataform navigation properties

bull the Picker applet

bull the use of a trigger to generate instance names

Note The example application uses a simplified schema that is constructed to highlight

these features It is not intended to represent the way to implementing a real order entry

system

You can view all of the features of the Order Entry example application except the

demonstration of the Picker applet with either the Enterprise Edition or the Personal

Derivations example

Worked examples

423

Edition of Sentences Version 40 You must have the Enterprise Edition in order to view

the demonstration of the Picker applet

Setting up the Order Entry example application

Before you can start the Order Entry example application you must import the

application and make the RenameInstance trigger available to Sentences The

Sentences server must be closed down before you perform both of these actions

Importing the Order Entry example application

To view the Order Entry example application you must import the profile file

OrderEntrylze into Sentences This file is located in the ExamplesDerivations

sub-directory of your Sentences installation Follow the procedure for importing profiles

described in ldquoExporting and importing databasesrdquo An example command line is given

below

Remember that the Sentences server must be closed down before you run the Import

procedure Use the -renumber option when you import this file to create a profile

automatically

Open a command prompt and navigate to the ltSentences_homegt directory and enter

the following command line

ltSentences_homegtimport ndashrenumber sect

ExamplesDerivationsOrderEntrylze

Making the RenameInstance trigger available

The Order Entry example application uses a trigger named RenameInstance which

is included in the ExampleTriggersjar file Make sure that this JAR file is located in

the SentencesTriggers directory so that it is available to Sentences If necessary

copy the JAR file from the ExamplesJars directory

Starting the Order Entry example application

After running the Import procedure and making sure that the RenameInstance trigger

is available start the Sentences server and run Sentences You can now select the Order

Entry example application from the Open Profile dialog box

In the Order Entry example application the entity type Order has the property Instance

name created by trigger defined for it This means that when you create an instance of

the Order entity type you do not need to enter an instance name The name is created

automatically by a trigger The name field on the create Dataform is disabled

The RenameInstance trigger is attached to the Create event for the Order entity type

When this trigger is invoked it renames the instance on which it has been

invoked to a numeric value based on the current time In the Order Entry example

application this is used to assign a unique order number to each order as it is created

The Order Entry example application uses a simple schema based on four main entity

types Customer Order Stock item and Tax Type as shown in Figure 11-7

Derivations example

Worked examples

424

Figure 11-7 The Order Entry example application

Order Entry base Dataform and custom Dataform

The Order Entry example application illustrates the use of Query Editor features to

create a powerful custom Dataform alongside the automatically generated base Dataform

In the following steps you can examine the differences for yourself

1 Highlight the order 1000000001235 in the data pane and right-click to display the

shortcut menu

2 Select ltOrdergt from the Dataform sub-menu This displays the base Dataform for the

Order entity type as shown in Figure 11-8

Figure 11-8 The Order Entry base Dataform

3 Close the Dataform

Derivations example

Worked examples

425

4 Now select Order Entry from the Dataform sub-menu This displays the custom

Dataform for the Order entity type as shown in Figure 11-9 and Figure 11-10

Figure 11-9 Order Entry custom Dataform Order page

Figure 11-10 Order Entry custom Dataform Order details page

The custom Dataform was designed using a query The query includes derivation fields

which are used to calculate values Although these fields can be seen in the base Dataform

they cannot be used

Base Dataform behaviour

The following steps demonstrate the behaviour of the base Dataform for the Order entity

type

1 In the Sentences Explorer highlight the Order entity type and right-click to display the

shortcut menu

2 Select Order ltdefaultgt from the Dataform sub-menu This displays the a blank base

Dataform

3 Type in the following data

Customer Barney Norris

4 The custom Dataform displays the Delivery address for an order and not the

Customer address When you create a new customer in this example system you must

create the customer address in a child dataform Right-click the customer name you have

Derivations example

Worked examples

426

just entered (Barney Norris) and select View ldquoBarney Norrisrdquo from the shortcut menu

Type in the following data

Address 123 Main Street Anytown

Click Apply and then Close

5 The address information is not transferred automatically to the base Dataform and you

need to enter it again manually in the Delivery address field

6 Right-click in the table for associations display area next to Order lines and select

Create ( order lines stock item) which opens a child Dataform

7 In the child Dataform use the picker buttons to select the following data

Stock item Porsche racing bike

Quantity 1

Price 2375

The child dataform is shown in Figure 11-11

Figure 11-11 Order line details on the child Dataform

8 Click Apply then Close to return to the Order Dataform

9 In the Tax type field use the drop-down button to select National rate

10Click Save amp Edit

Sentences does not accept this update Some Dataform fields are highlighted in red and

Sentences displays the Message Log with the message Error 1682 At least one

instance is required of the association type (Order Tax amount

Currency)

The Tax Amount association has been defined in the schema as Mandatory and so the

Dataform update is not accepted However you cannot edit the Tax Amount field

directly as it is an example of a field calculated using a derivation which has also been

defined in the Explorer as Read-only To verify this highlight the Tax Amount

currency association in the Explorer schema pane and open the Format page of the

Properties dialog The Read-only checkbox has been selected

The Order field is also highlighted in red This is because the instance name for a new

order is created by a trigger and the trigger is not activated until all the required data has

been validated

11Close the Dataform without saving the data you entered

Custom Dataform behaviour

The following steps demonstrate the behaviour of the custom Dataform

1 Highlight the Order entity type and right-click to display the shortcut menu

2 Select Order entry from the Dataform sub-menu This displays the a blank custom

Dataform with two tabbed pages

Notice that the Placed on and Last updated fields have been filled automatically

Derivations example

Worked examples

427

3 On the Order page of the Dataform type in the following data as before


4 Remember that the custom Dataform displays the Delivery address for an order and

not the Customer address When you create a new customer in this example system you

must create the customer address in a child dataform Right-click the customer name you

have just entered (Barney Norris) and select View ldquoBarney Norrisrdquo from the shortcut

menu Type in the following data


Click Apply and then Close Sentences copies the customer address details to the

Delivery address field You may change the delivery address in the custom Dataform

5 Click the page tab to display the Order details page and use the picker button to select

National rate for the Tax type field


Create ( order lines stock item) to open a child Dataform



Quantity 1

8 Click Apply Note that the Price and Line total have been calculated automatically

Close the child Dataform

9 In the custom Dataform you can see that the Tax Amount and Gross Total fields have

been calculated as shown in Figure 11-12

Figure 11-12 Calculated values on the Order Entry custom Dataform


11On the Order page the Order field has now been completed with a new order number

as shown in XYZ This number was generated by the RenameInstance trigger which

was invoked when the Dataform was saved

Derivations example

Worked examples

428

Figure 11-13 Completed Dataform with Order number generated by the trigger

12Close the Dataform

The Order Entry query

This section looks in greater detail at the Order Entry query that was used to create the

custom Dataform

The Order Entry profile includes a query which is used to build a custom Dataform The

root of the query is the Order entity type To view the query highlight the query named

Order custom Dataform in the Explorer schema pane and select Edit query from the

shortcut menu The query is shown in Figure 11-14

Figure 11-14 The Order custom Dataform query

The query includes request nodes for the associations directly sourced from Order and

Order lines and the additional information needed for Customers Stock items and

Tax rate which allows the order to be linked to the corresponding address current price

and current Tax rate

The order details section of the query has been placed after the query nodes for the total

and the tax amount This demonstrates that you can place derivations anywhere in a

query In particular the variables used within the derivation expression can refer to nodes

anywhere else within the query

Derivations example

Worked examples

429

The query includes derivations that have been added to delivery address price and Tax

Rate to copy to corresponding value from the targetrsquos association to the order

association

Page Nodes

In the Dataform for Order (Figure 11-8) all the associations sourced from Order appear

on a single page In the custom Dataform there is a division between the details of the

customer and the actual items ordered and their cost To do this two Page nodes have

been added to the query and given suitable names The request nodes corresponding to the

associations sourced from Order have then been moved into the appropriate page The

custom Dataform (Figure 11-9 and Figure 11-10) has two pages with names

corresponding to the page node names and each tabbed page contains the associations as

specified in the query

Derivations

The Order custom Dataform query uses a large number of derivations In order to

differentiate between different associations with the same target types (such as Currency

or Percentage) a number of target nodes in the query have been renamed

Renaming nodes makes them uniquely identifiable but has no other effect

The query contains the following derivations

bull delivery address

This is calculated by copying the address of the customer This derivation is set to

Calculate once and the Editable property is also set which means it can be changed by

the user On the custom Dataform if the field is blank the customers current address is

copied into this field when the Dataform is saved or refreshed Anything that the user

types into this field is retained - a recalculation does not replace it

bull placed on

This association has the Read-only property set in the schema which means users cannot

enter values into this field The Editable property is disabled because of this The

derivation expression uses TimestampNow() which obtains the current date and time

whenever the expression is evaluated The request node in the query is set to Calculate

once which means that it is only calculated when an Order instance is first created

bull last updated

This is similar to the placed on node except that the derivation is set to Calculate on

Save This causes the value to be recalculated when an order is first created and whenever

it is subsequently updated

bull price

This is similar to the delivery address This derivation calculates the ordered itemsrsquo

current price by copying it from the current price association for the item Users may

modify this value

bull line total


enter values into this field on the Dataform The Editable property is disabled because of

this The target is calculated by the derivation expression that multiplies the item price by

the quantity ordered This derivation is set to Calculate always so that if any of the

details on the order line are edited the new total is recalculated

bull Net Total

In this Order Entry example system there is no requirement to store the net total for an

order Therefore this derivation is attached to a derived type which is only displayed in

Derivations example

Worked examples

430

the query results or on a custom Dataform The derived type expression sums all the line

totals and always recalculates which is the standard behaviour for derived types The

properties of the derived type have been set to the Currency datatype with a display style

C000C-000 so that the custom Dataform displays this value as a formatted

currency

bull Tax Rate

This is similar to the delivery address This derivation calculates the Tax percentage to

be applied by copying it from the current rate for the selected Tax type

bull Tax amount


enter values into this field on the Dataform The target is calculated by the derivation

expression that multiplies the result of the Net Total derivation by the result of the Tax

rate derivation to give the amount of tax to be added to the order

This derivation is set to Calculate always so that if any of the details on the order are

edited the Tax amount is recalculated

bull Gross Total


enter values into this field on the Dataform This derivation is set to Calculate always

and is the sum of the Net Total and Tax Amount derivations

Dataform Navigation

Using a custom Dataform gives application designers control of which fields target

dataforms can be accessed by users and so limits the data that users have access to and

can change In the Order Entry example application the custom Dataform allows users to

create new customers or to update customer details when they enter or amend orders It

prevents users from creating or changing Stock items and Tax types

Figure 11-15 Properties dialog for the Customer node

Derivations example

Worked examples

431

Figure 11-15 shows the Properties dialog for the Customer node in the query This

illustrates settings that allow users to select Customer values (can select Customer) to

follow links to child Dataforms (Navigation Default Dataform for Customer) and to

create Customer values (can create Customer)

Figure 11-16 Properties dialog for the Tax Type node

In contrast Figure 11-16 shows the Properties dialog for the Tax type node in the query

This illustrates settings that only allow users to select Tax type values (can select Tax

type) but not to follow links to child Dataforms or to create Tax type values

(Navigation Prohibited)

Figure 11-17 Tree style picker for Customer

In the profile schema the Picker property for the Customer association is set to Tree

This means that items listed in the Picker for this association appear in a tree format

which enables users to identify customers with similar names by checking their addresses

Derivations example

Worked examples

432

The Picker applet for the Order Entry example

An additional way of restricting access to Sentences data is to use an applet embedded in

an HTML page such as the Picker applet based on the Picker available on the Sentences

Dataform

You can only view the Picker applet if you are using the Sentences Enterprise Edition

To view the Picker applet copy the file OrderEntryhtml from the

ExamplesDerivations sub-directory of your Sentences installation into the

ltSentences_homegtTomcat4webappsSentences directory

To examine the parameters for the picker applet open the file OrderEntryhtml using

a text editor and compare the settings with the list of parameters in ldquoApplet parameters

for the Picker appletrdquo

Using the Picker applet to enter and update orders


You can view the Picker applet for the Order Entry example file in your browser by

entering a suitable URL If you are using the default installation of Sentences with

Tomcat the URL you need to use is

httplocalhost8090SentencesOrderEntryhtml

You may need to adjust this URL for your installation

Figure 11-18 The Picker applet for the Order Entry example application

The Order Entry browser page presents a Picker display that lists all the existing orders

The positioner and filter fields are available as in any Picker and can be used to locate

items in the displayed list

To edit an existing order double-click on the order or select it and click Edit To create a

new order click Create

Derivations example

Worked examples

433

The picker launches the custom Dataform for Order This Dataform can be used in

exactly the same way as a Dataform launched from the Sentences Explorer

You can now experiment with creating new orders by following the steps given in ldquoOrder

Entry base Dataform and custom Dataformrdquo

Design assumptions used in the Order Entry example

application

The Order Entry example application is a simplified Sentences schema for a fictitious

Order Entry system The design assumptions used in creating this profile are given below

as an example of the kind of issues that you need to consider when designing an

application

The design assumptions for the Order Entry system are as follows

bull Every order has an automatically generated order number assigned to it when it is first

placed

bull Users can create new orders or select and amend existing orders

bull The system automatically records the date and time at which an order was created This

value cannot be changed

bull Orders can be amended at any time The system automatically records the date and time

of the last modification This value is updated every time an order is amended but cannot

be changed by the user

bull The system records all customer names and their address When an order is placed the

name of the customer and the delivery address is recorded in the order The delivery

address is normally the same as the customerrsquos address but it can be modified on the

order

bull Users entering orders can select the name of an existing customer or enter the details of

a new customer

bull There is a fixed list of items in stock that may be ordered Each stock item has a current

price which may change at any time The current price of an item is stored with the order

when the order is created Any changes to the current price of an item must not affect

orders that have already been placed

bull Users entering orders can only select stock items that already exist They cannot create

new items or view or modify the details of any existing stock items

bull An order is made up of one or more order lines Each order line details a specific item

the quantity required the unit price at the time the order is placed and the line total

(quantity unit price)

bull The unit price of an item is taken from the stored current price for the item Users

entering or modifying an order can adjust this price for example for special promotions

or discounts

bull The net total for all items ordered is displayed on the orderrsquos Dataform but is not stored

in the database

bull Tax is added to the net total of an order The tax rate is selected by category The actual

percentage rate is taken from the current rate when an order is placed The current rate can

change at any time and must not affect any orders already placed The actual rate applied

is stored with the order

bull The Tax category selected and the corresponding percentage rate applied is stored with

the order and added to the net total to create the gross total which is also stored with the

order The user cannot modify any of these values Whenever an order is changed (by

adding deleting or amending ordered stock items) these totals are recalculated

Trigger examples

Worked examples

434


As you imported a separate profile for the Order Entry example the original Human

Resources profile was unaffected To restore the original Human Resources profile

choose Open Profile from the File menu and select the profile name

You can completely remove the Order Entry example application by choosing Delete

Profile from the File menu and selecting the profile name and then deleting Order Entry

profile chapters from your chapters directory

Trigger examples

Note The symbol sect indicates that a line of text has been split to allow display in this book

only You should type in the text as one line

A number of example Sentences triggers which can be used with the Human resources

example application are included in the Sentences installation under the Triggers

directory This section describes how these triggers work with the Human resources

example application

The triggers are

bull Refuse Update trigger which can check and refuse any update with which it is

associated

bull Email Address trigger which can test and if necessary refuse updates to email

addresses

bull Auto Number trigger which can create new associations with uniquely numbered

targets for an instance

bull RenameInstance trigger which is used to demonstrate the automatic generation of

entity instance names when the Instance names created by trigger is selected for an

entity type (see ldquoInstance optionsrdquo ) This trigger is demonstrated in the ldquoDerivations

examplerdquo

More details about the function of each of these triggers are given in the relevant

examples

The example procedures for demonstrating the trigger examples refer to the Sentences

Enterprise Edition The triggers can also be demonstrated with the Sentences Personal

Edition

Example trigger classes

The example triggers are implemented as Java classes as follows

bull RefuseUpdateTrigger

bull EmailAddressTrigger

bull AutoNumberTrigger

bull RenameInstanceTrigger

These classes along with other classes located under comsentencesexamples

which they make use of form a Java package named

comsentencesexamplestriggers and are built into a Java archive file

ExampleTriggersjar

Loading the example triggers

If you install the Sentences Application Suite the example triggers file

ExampleTriggersjar is copied from its default location in

ltSentences_homegtExamplesJars to the triggers directory

ltSentences_homegtTriggers This directory is listed in the TriggerPath property

Trigger examples

Worked examples

435

in the Serverproperties file and therefore the triggers are loaded when you start


If you did not install the Sentences Application Suite you must copy the example triggers

file ExampleTriggersjar from its default location in


ltSentences_homegtTriggers and then restart the Sentences server

The following trigger initialisation messages should be visible along with other Sentences

server messages for example in the Tomcat MS-DOS window

Administrator info trigger Refuse Update instantiated All updates of

associated type and event combinations will be refused

Administrator info trigger Email Address instantiated

Associated hyperlink instances must start with the email HTTP protocol

mailto

Administrator info trigger Auto Number instantiated Update events for any

associated type will generate autonumbering on instances

These messages are not visible when using the Sentences Personal Edition

If you are using the Sentences Enterprise edition and these messages are not visible

check that the Triggers directory is listed in the TriggerPath property in the


Viewing enabled triggers

To view a list of triggers currently enabled on the server select Triggers from the View

menu in the Sentences Explorer Sentences displays the Available triggers list as shown

in Figure 11-19

Figure 11-19 The Available triggers list

Attaching triggers and editing trigger assignments

Triggers are attached to entity and association types by using the Triggers page of the

Properties dialog for the selected type An example of the Triggers page isshown in

Figure 11-20

Trigger examples

Worked examples

436

Figure 11-20 The Properties dialog Triggers page

Details of how to attach a trigger to an entity or association type and how to edit trigger

assignments are given in the section ldquoAttaching a triggerrdquo

Refuse Update trigger example

The Refuse Update trigger simply refuses any update with which it is associated This

action is completely generic and therefore the trigger can be assigned to any Sentences

type and any trigger event and to as many type and event combinations as required

Subsequent transactions which include an occurrence of that event for that type are

refused Schema designers can therefore use this trigger to enforce the refusal of any user

updates they wish

Refuse Update on deleting an Employee

The following procedure shows how the Refuse Update trigger is used to prevent the

deletion of any instance of Employee in the Human resources example application

1 Open the Human Resources example application You should create a new chapter in

the Human Resources profile for this demonstration This enables you to restore the

original profile later

Open the Edit Profile dialog Click Add and then New and create a new chapterwith the

name Refuse Update Example and click OK to add it to the profile Do not remove

either of the existing chapters Select the new chapter as the target chapter for Schema

changes Data changes and Query changes The Edit Profile dialog should look like

Figure 11-21

Trigger examples

Worked examples

437

Figure 11-21 Edit Profile dialog for the Refuse Update trigger example

2 Click OK to save the profile

3 In the Sentences Explorer highlight the Employee entity type open the Properties

dialog and select the Triggers page If there are any existing entries on the Triggers

page they need to be deleted for this demonstration If this is the case you may wish to

consult your Sentences administrator before continuing

4 Click the Add button Sentences displays the Add Trigger Assignment dialog Select

Refuse Update from the list of triggers and Delete from the list of Trigger Events and

click OK

Figure 11-22 The Triggers page with the assigned trigger

The triggers page should now look as shown in Figure 11-22

Trigger examples

Worked examples

438

5 Click OK to save and then click Close to close the Properties dialog

6 In the Sentences Explorer data pane and select any of the Employee instances for

example Barney Norris

7 Try to delete the selected Employee using either the context menu Delete option or the

tool bar Delete button

Figure 11-23 The Impact of deleting window for the instance Barney Norris

8 Sentences displays the Impact of deletinghellip window showing the list of all the data

affected by the delete action as shown in Figure 11-23 Click the Delete button on this

window to confirm the delete action

Figure 11-24 The Message Log when the delete action is refused

9 Sentences displays the Message Log window with an error message as shown in

Figure 11-24 This error message text is generated by the trigger code For the deletion of

Barney Norris the full text of the message reads

Delete Instance operation on type Employee is refused for instance Barney Norris

by association with trigger Refuse Update

If you are using the Sentences Enterprise Edition you can see a server message in the

servlet container window confirming that the trigger has been assigned

The text of the message is

Administrator info trigger Refuse Update trigger initialised for type Employee

This message is only displayed on the first occasion that the trigger is applied to the type

10Click Close on the Message Log window The selected Employee is still displayed in

the data pane This demonstrates that the trigger has successfully refused the Delete

action

Trigger examples

Worked examples

439

The Refuse Update trigger with subsets and subtypes

Triggers assigned to types automatically apply to subsets of the type You can

demonstrate the application of the trigger to a subset without changing the trigger

assignments as follows

1 Highlight the Current employee subset

2 Select an instance of the subset for example Barney Norris and try to delete it

The deletion is refused in the same way as trying to delete an instance of Employee

Triggers assigned to types automatically apply to subtypes of the type If you want to

demonstrate the application of a trigger to a subtype you need to change the trigger


1 Open the Properties dialog for Employee and select the Triggers page

2 Remove the Refuse Update trigger and click OK then Close

3 Open the Properties dialog for Person a supertype of Employee and select the

Triggers page

4 Add the Refuse Update trigger for Delete events using the procedures shown in the

section ldquoRefuse Update on deleting an Employeerdquo

5 Select any of the Person instances in the data pane for example David Quentin and

try to delete it

This action is refused in the same way as the deletion of an Employee previously The

Message Log displays the message

Delete Instance operation on type Person is refused for instance David Quentin by

association with trigger Refuse Update

You can see the same result - that is an attempt to delete is refused - if you try to delete an

instance of a subtype of Person for example the Employee instance Barney Norris

The attempt to delete the employee is refused in exactly the same way as previously when

the trigger was assigned directly to Employee This time however the trigger invocation

occurred because it was assigned to Person the supertype of Employee

Restoring the original Human Resources example application

If you created a new chapter Refuse Update example as suggested and used it as the

target for both schema and data changes in the profile you can restore the Human

Resources profile by simply editing the profile and removing the new chapter Restore

the original schema and data changes chapters and save the profile

If you did not use a new chapter you must use the Triggers page of the Properties dialog

to remove any trigger assignments from the entity types in the profile

Email Address trigger example

The Email Address trigger is another example of a validation trigger which checks and

may refuse certain updates Its purpose is to check that email addresses are entered in the

correct format

At the time you assign a trigger to a type Sentences cannot check whether the assignment

is valid or logical This means that the trigger code must be able to check that the

assignment is valid each time it is invoked

Email addresses are usually stored in Sentences using the Hyperlink datatype

Values of this type represent email addresses when they commence with the HTTP email

protocol designator which is the string mailto However the Hyperlink datatype is

Trigger examples

Worked examples

440

also used for other kinds of hyperlinks for example Web addresses which commence

with the string http

The Email Address trigger may be applied either to an association type or to an entity

type The example procedure shows how the Email Address trigger is applied to the

association type Employee email address Hyperlink and ensures that all existing and

new target values for instances of the association type pass its check

It would not be appropriate to attach the Email Address trigger to the Hyperlink entity

type in the Human Resources example application This is because this entity type

like the Hyperlink datatype is used for all kinds of hyperlinks and not just for

email addresses However it is appropriate to restrict Hyperlink instances to those

commencing with the string mailto when they are used as the target of an email

address association

Rejecting incorrect values for email addresses

Use the following steps to demonstrate the behaviour of the Email Address trigger

1 Open the Human resources example application You should create a new chapter in



Open the Edit Profile dialog Click Add and then New and create a new chapter with the

name Email Address example and add it to the profile Do not remove either of the

existing chapters Select the new chapter as the target chapter for Schema changes Data

changes and Query changes The Edit Profile dialog should look like Figure 11-25

Save the profile

Figure 11-25 Edit Profile dialog for the Email Address trigger example

2 In the Sentences Explorer highlight the Employee email address Hyperlink entity

type open the Properties dialog and select the Triggers page If there are any existing

entries on the Triggers page they need to be deleted for this demonstration If this is the

case you should check with your Sentences administrator before continuing

3 Click the Add button Sentences displays the Add Trigger Assignment dialog

Select Email Address from the list of triggers and Create from the list of Trigger

Events and click OK

4 Repeat the previous Add step and select Target Changed from the list of Trigger

Events and click OK

Trigger examples

Worked examples

441

Figure 11-26 The triggers page for the Employee email address Hyperlink association

5 The assignments are displayed on the Triggers page as shown in Figure 11-26 Click

OK on the Properties dialog to apply the assignments

6 In the Sentences Explorer data pane select an instance of Employee for example

Barney Norris and select Default Dataform from the shortcut menu

7 Click the ellipsis button for the Email address association and select a value

from the picker list which is not a valid email address for example the value

httpwwwsleepysoftcom Click Save

8 The trigger prevents Sentences from accepting this association instance update because

the association target fails the triggerrsquos checks This is indicated in two ways both shown

in Figure 11-27

bull the Dataform highlights the incorrect data and the page it is on in red

bull the Message Log displays an error message

Trigger data error An instance of the entity type Hyperlink has been found

with a value of ldquohttpwwwsleepysoftcomrdquo This fails the requirements of the

type (Employee email address Hyperlink) enforced by the trigger Email

Address

Figure 11-27 Email Address trigger rejects incorrect update

Trigger examples

Worked examples

442

9 If you are using the Sentences Enterprise Edition an initialisation message is displayed

in the servlet container window as this is the first invocation of the trigger against this

type

Administrator info trigger Email Address trigger initialised for type

(Employee email address Hyperlink)

10 Click the ellipsis button for the Email address association again and select a value

from the picker list which is a valid email address for example

mailtobarneynsleepysoftcom Click Save

This update is accepted and the fields and text revert to their normal colours


If you created a new chapter Email Address example as suggested and used it as the


resources profile by simply editing the profile and removing the new chapter Restore




Auto Number trigger example

The Auto Number trigger is an example of a trigger which adds data to an update It

automatically creates positive integer numbering for instances of any type it is associated

with when an instance is updated provided the requirements detailed below are met The

data generated by this trigger cannot be changed by users

This trigger is an example of how a generically coded trigger can achieve its purpose with

a minimum set of fixed dependencies and can be applied as widely as necessary by the

schema designer

Remember that Sentences server triggers act on user updates but not on data that is only

viewed Triggers are not applied to existing data until that data is the subject of a user

update

The Auto Number example trigger has the following requirements

bull A single entity type named Auto number must be defined by the profile

bull The datatype of that entity type must be Number

bull Any type to be auto-numbered must be the source type for an association type with Auto

number as its target type

bull Instances of that association type must obey the Singular inverse cardinality rule (see

ldquoSingular inverserdquo )

bull Target values for all instances of the association type must be positive and integer

When the Auto Number trigger is invoked for the first time it executes an initialisation

method which checks these requirements If the requirements are not met the trigger does

not operate on the assigned type

You can define an association type as Read only by checking the Read only check box

on the Format page of the Properties dialog In this case values cannot be added through

the Dataform If the Auto Number association type is defined as Read only then the

numbering is purely automatic If the Auto Number association type is not defined as

Read only then you can enter numbers on the Dataform and these number values are

checked by the trigger code

Defining the Auto Number association type as Singular inverse guarantees the unique

numbering which the trigger checks for when it initialises

Trigger examples

Worked examples

443

The trigger can be applied to many Sentences types simultaneously The same entity type

Auto Number must be used as the target type for all the numbering association types

The numbering is applied independently for each Auto Number association type so each

numbered source type is numbered independently in ascending sequence

Auto-numbering always uses the next available increasing positive integer for a new

numbering association If the association type is not defined as Read only you can enter a

number value on the Dataform which becomes the new starting value for numbering of a

type

Use of the Number datatype for the numbering entity type Auto number allows that

type to support the triggerrsquos operation because value instances cannot be deletedor

renamed (see ldquoBehaviour of value types and valuesrdquo )

Setting up the schema to use the Auto Number trigger

Before you can run the demonstration of the Auto Number trigger you need to make some

changes to the schema of the Human resources example application

1 Copy the file Human resources employee id schemachap from the

ExamplesChapters directory to the directory where your chapter files are located

If a copy of this chapter already exists in your chapters directory it is possible that this

demonstration has already been run on your installation In this case the Auto Number

trigger may generate different values from those shown in this text

2 Shutdown and restart the Sentences server so that Sentences recognises the new chapter

file If you are running the Personal Edition restart Sentences

3 When the server has restarted open the Sentences client and select the Human

resources profile If this profile is already running in the client refresh the display

4 Open the Edit Profile dialog Click Add and then New and create a new chapter with

the name Auto Number example and add it to the profile Do not remove either of the


changes and Query changes

5 Click Add again and add the chapter Human resources employee id schema to

the profile The Edit Profile dialog should look like Figure 11-28 Save the profile

Figure 11-28 Edit Profile dialog for the Auto Number trigger example

Trigger examples

Worked examples

444

6 In the Sentences Explorer schema pane select the Employee entity type and then select

one of the instances of Employee in the data pane for example Barney Norris Open

the Dataform on this instance The Dataform includes the newEmployee ID association

type as shown in Figure 11-29

Figure 11-29 Employee Dataform showing Employee ID association

If the new association type does not appear in the Dataform check the Edit profile dialog

to verify that the additional chapter Human resources employee id schema has

been added to the profile

If the additional chapter is listed in the Edit profile dialog but the Employee ID field is

not shown in the Dataform it may mean that another user has made changes to your copy

of the Human resources profile You can restore the original Human resources profile

chapters by copying the original chapter files from the Exampleschapters directory

of your Sentences installation

If the Employee ID association shows a target value for Employee number in the

Dataform this means that this trigger has already been demonstrated on your system You

should create a new temporary chapter for example Auto Number Example 2 and try

again

1 In the All types folder of the Sentences Explorer schema pane select the Auto number

entity type Open the Properties dialog and select the Datatype page as shown in Figure

11-30

Trigger examples

Worked examples

445

Figure 11-30 The Datatype page for the Auto Number entity type

The datatype of Auto number should be defined as Number and the maximum number

of decimal places as zero The code for this example trigger is designed to work when

instances of Auto number can be treated as numeric values and when the Auto number

entity type and all its instances use the same datatype

The Number datatype in Sentences defines a value type Value instances cannot be

deleted or renamed This complements the function of the trigger by ensuring that values

once created cannot be changed by a user

When these settings are correct close the Properties dialog

2 In the All types folder of the Sentences Explorer schema pane expand Employee and

select the association verb employee ID Open the Properties dialog and select the

Format page Make sure that the Read only on Dataform check box is selected as


Trigger examples

Worked examples

446

Figure 11-31 Format page for the Employee ID association

When the Read only on Dataform property for an association type is set Sentences does

not allow users to enter association values When you have checked that this setting is

correct close the Properties dialog

Demonstrating the Auto Number trigger

The following procedure shows how the Auto Number trigger creates employee

numbering data for the Human resources example application To do this each time an

Employee instance is the subject of an update the Auto Number trigger checks if there is

a target value for the Employee ID association If no value exists the trigger assigns the

next available number to the Employee If the user has entered a number the trigger

checks its value

When the Auto Number trigger is invoked it finds the highest existing target value of an

Employee ID association and uses that number plus one as the starting value for

subsequent numbering If no instances of the association are found the default starting

value of 1 is used



page they need to be deleted for this demonstration If this is the case you should check

with your Sentences administrator before continuing


Auto Number from the list of triggers and Create from the list of Trigger Events and

click OK

3 Click the Add button again and select Auto Number and Attribute Changed in the

list of Trigger Events and click OK

4 The two assignments should be displayed in the trigger assignments table as shown in

Figure 11-32 Click OK on the Properties dialog to apply the assignments

Trigger examples

Worked examples

447

Figure 11-32 The triggers page for the Auto Number trigger on Employee


Barney Norris and select Default Dataform from the shortcut menu You should see

Employee ID ltAuto numbergt as the first association on that Dataform as shown in

Figure 11-29

If a value is already shown for ltAuto numbergt this means that residual data remains in

the database from a previous demonstration of this example

6 In the Sentences Explorer schema pane All types folder select Auto number At this

stage you should not see any values in the data pane If values are present they are left

over from a previous demonstration of the Auto Number trigger and you should be able

to remove them by removing the temporary chapter in which they were created If you do

not remove this chapter the values that Sentences displays for Employee ID may be

different from those described in the following steps

7 In the Sentences Explorer schema pane select Employee and open the Dataform to

create a new instance The first page displayed is the Person page Select the Employee

page and check that no data is shown for this new person

You cannot type in the Employee ID target field Although you can place your cursor in

this field and select the field value Sentences does not accept any keyboard input for this

field because the association type has been defined as Read only This is because the

values for this field are to be generated by the trigger code

8 On the Person page type in a name for a new employee Steve Meyer Click Save

and Edit

9 Select the Employee page The next available Employee number value 1 has been

used as the target for an automatically generated Employee ID association 10If you are

using the Sentences Enterprise Edition an initialisation message is displayed in the

servlet container window as this is the first invocation of the trigger against this type

Administrator info trigger Auto Number trigger initialised for type Employee

Numbering of instances will begin at 1

11Click the Yes radio-button for Project resource and click Save Steversquos employee

ID still shows as 1 Once calculated it should never change Click Close

Trigger examples

Worked examples

448

12Select Barney Norris and open the Dataform To create an Employee ID value for an

existing employee you must update the database in a way that references the Employee

An update which results in no net change to the database does not invoke a trigger

13Click the Project resource radio-button again and click Save The next available

value 2 should show as the Employee ID for Barney Click the radiobutton again to

restore its original value and click Save and then click Close

14In the Sentences Explorer schema pane All types folder select Auto number The

values just created (1 and 2) are shown

Cases in which the Auto Number trigger is not invoked

The Auto Number trigger is only invoked when the instance to be numbered is either

created or updated The following procedure illustrates an action that can be taken that

involves an instance of Employee but does not update the instance In this case the Auto

Number for the Employee ID association is not created

1 Select the Employee instance Freda Quentin in the data pane and open the Dataform

The Employee ID association has not yet been set for Freda

2 Select the Resource skills page Double-click over the table line Java Novice to open

a child Dataform on this association Click the ellipsis button for Expertise and select the

value Competent Click Apply and then click Close

3 Click Save on the Resource page The changed data is now displayed in the table

4 Select the Employee page The employee ID value is still not set

This is because although an update was submitted and committed to the database it did

not reference an Employee as its subject or source Instead the source type for the update

was Employee skill Skill

5 Select the Resource skills page Right-click over the empty table space and select

Create (hellip skill Skill)hellip from the shortcut menu In the child Dataform that opens use

the picker to select a skill of C++ and an expertise of Novice

Click Apply and then click Close and then click Save on the Resource Skills page

6 Select the Employee page The Employee ID value has now been set The new skill

association you created had an Employee as its source As a result the trigger was

invoked and was able to update that Employee and create an Employee ID association

for Freda

Using the Auto Number trigger when user entries are allowed

The following steps illustrate how the Auto Number trigger can be used when users are

allowed to enter numbers that is when the association type is not defined as Read only

1 Select the association type Employee employee ID Auto number in the schema

pane and open the Properties dialog and select the Format page Clear the Read only

checkbox and click OK and Close

2 Select any Employee in the data pane If you select an Employee who already has a

number for example Barney Norris you can replace that number with a new value

(This action does not succeed if the Refuse Update trigger is currently loaded) If you

select an Employee who does not yet have a number for example John Atkins you can

enter a number for the first time For the purposes of this demonstration select an

Employee who does not yet have a number for example John Atkins

3 Select and type into the Employee ID target field This is now enabled as the Read

only setting on the association type has been removed Enter an unacceptable value for

example ndash1 and click Save The trigger detects that a value has been entered and checks

it The value entered is not acceptable and hence is rejected The Message Log displays

an error message

Trigger examples

Worked examples

449

Trigger data error An instance of the autonumber entity type Auto number has

been found with a value of -1 Values are required to be greater than zero by

trigger Auto Number

4 Repeat the above step entering a positive but non-integer value for example 25 This

value is also not acceptable to the datatype setting of zero decimal places The datatype

check is applied before the user trigger is invoked hence this value is rejected by the

datatype The Dataform highlights the incorrect data and the page it is on in red If Save

is clicked the Message Log displays an error message

1622 Bad value for ldquoEmployee IDrdquo

5 Repeat the above step entering a value which is already in use for this association type

for another employee for example 2 The trigger detects that this value is already in use

for this association type and rejects the update with the error message

Trigger data error An instance (2) of the autonumber entity type Auto number

has been found to be the target for more than one instance of the numbering AT

(Employee employee ID Auto number) eg (Barney Norris employee ID 2) This

condition is disallowed by the trigger Auto Number

Having demonstrated the error detection capabilities of the trigger for data entry we can

now illustrate how the auto-numbering uses the highest existing target value for the

association type to determine the next number to assign

1 Select an Employee who does not yet have a number for example John Venice and

open the dataform Select and type into the Employee ID target field a new high value

for example 100 and click Save

2 Now select another Employee who does not yet have a number for example Mark

Goldstone and open the dataform Click the Project resource radiobutton and click

Save The next available value 101 should show as the Employee ID for Mark


To restore the Human resources example application you must first edit the profile and

remove the additional schema chapter Human resources employee id

schemachap from the profile If you created a new chapter Auto Number example as

suggested and used it as the target for both schema and data changes in the profile you

must remove this chapter as well the new chapter Restore the original schema and data

changes chapters and save the profile



Disabling the example triggers

To unload the example triggers you should use the following procedure

1 Remove all assignments of the triggers to any type in the schema for example by

following the procedures to restore the original Human resources example application

for any of the trigger demonstrations which you have used

2 Remove the trigger JAR file from the defined location for triggers on the Sentences

server This location is specified by the TriggerPath property in the

Serverproperties file The default location is

TriggerPath=ltSentences_homegtTriggers

3 Restart your Sentences server and refresh any open profiles at the running clients If

you are using the Personal Edition restart Sentences

Custom datatype example

Worked examples

450


A simple example custom datatype which can be demonstrated with the Human

resources example application is available in your Sentences installation

The example implements a datatype called TelecomsNumber as the Java class

Telecoms which is itself defined in a Java package called

comsentencesexamplesdatatypes (in the subdirectory

comsentencesexamplesdatatypes) The example consists of a source code file

Telecomsjava and a built Java archive ExampleDatatypejar

About datatype classes

A Sentences custom datatype can only be created as a Java class which implements the

Sentences LazyDatatype interface An effective way to achieve this is to extend the

default implementation of this interface in the class LazyAbstractDatatype Another

way to do this is to sub-class an existing specific Sentences datatype The directory

ExamplesExistingDatatypes contains the source files for the interface

LazyDatatype and for its top-level implementations LazyAbstractDatatype

LazyNumber and LazyString as well as for the other Sentences datatypes The

interface and the listed classes are described within the Javadoc documentation for the

API

Loading the custom datatype example

If you install the Sentences Application Suite the example datatype file

ExampleDatatypejar is copied from its default location in

ltSentences_homegtExamplesJars to the datatype directory

ltSentences_homegtDatatypes This directory is listed in the DatatypePath

property in the Serverproperties file and therefore the datatypes are loaded when

you start the Sentences server

If you did not install the Sentences Application Suite you must copy the example datatype

file ExampleDatatypejar from its default location in

ltSentences_homegtExamplesJars to the datatypes directory

ltSentences_homegtDatatypes and then restart the Sentences server

Checking the example custom datatype

1 Select the Telecoms number entity type and open the Triggers page of the Properties

dialog to make sure that no trigger has been enabled for it If a trigger has been enabled

you cannot test the custom datatype properly See the section ldquoDisabling the example

triggersrdquo for instructions on how to remove any of the example triggers if necessary

2 Restart the Sentences server and open the Sentences client Open the Properties dialog

for any entity type and select the Datatypes page TelecomsNumber should now be

found in the drop-down Datatype list

If the new datatype is not visible this may be because of the way that data caching is

implemented on the computer running the Sentences client Check your browser and Java

Plug-in settings You may need to shut down and restart your Web browser and servlet

container to try and resolve this problem

If Sentences displays an error message at the client check the Sentences trace file at the

server for details If no trace file is present check the configuration changes made to the

servlet container configuration for example in the tomcatbat file

References to datatype classes including custom datatypes are used at several levels

within Sentences For example references to datatype classes are stored with any entity

instances which were created with their use Because of this custom datatypes should be

used with caution when only being demonstrated or still under development


Worked examples

451

Unloading the example custom datatype

To unload a custom datatype remove the custom datatype JAR file from the defined

location for datatypes on the Sentences server This location is specified by the

DatatypePath property in the Serverproperties file The default location is

DatatypePath=ltSentences_homegtDatatypes









which is why we recommend using a new data chapter specifically for the purpose of

demonstrating custom datatypes



datatype

Custom datatype example TelecomsNumber

The TelecomsNumber datatype is a simple example datatype for telephone numbers

which extends the base Sentences datatype of LazyString This datatype only accepts

numbers beginning with a plus sign (+) and consisting of digits parentheses and spaces

only

This custom datatype supports two format styles

bull Full which displays the number formatted as entered

bull Number only which displays the number as only the leading plus sign and digits

This example datatype is provided to illustrate the datatype mechanism and not as a

suggestion of how telecoms numbers should be implemented in Sentences applications

Note The symbol sect indicates that a line of code has been split to allow display in this

book only You should type in the code as one line

Using the example custom datatype

Use the following steps to try out the behaviour of the TelecomsNumber example

custom datatype with the Human resources example application

1 Open the Human resources example application and open the Edit Profile dialog

You must add a new chapter to the Human Resources profile for this demonstration and

use it as the Data changes chapter If you do not use a new chapter as the Data changes

chapter it may be difficult to remove all references to the custom datatype after you

complete this demonstration (see ldquoUnloading the example custom datatyperdquo )

2 In the Edit Profile dialog click Add and then New and create a new chapter named

HR custom datatype test data and add it to the profile Use this chapter as the target

chapter for Data changes but do not remove either of the existing chapters Check that

the Edit Profile dialog looks like Figure 11-33 and save the profile


Worked examples

452

]

Figure 11-33 Edit Profile dialog for the Custom Datatype example

3 Highlight the Telecoms number entity type from the All types folder in the Sentences

Explorer schema pane and select Properties from the shortcut menu Select the Datatype

page and check that the Datatype field is set to ltNonegt

If this field shows any value other than ltNonegt then your database may have already

been customised by another user

Figure 11-34 Selecting the TelecomsNumber datatype

4 Click the down arrow on the Datatypes field and scroll through the list of available

datatypes and select the example custom datatype TelecomsNumber as shown in Figure

11-34 and click OK and then Close to close the Properties dialog

5 Reopen the profile to refresh the schema or select Refresh from the toolbar


Worked examples

453

6 Select Telecoms number again You can see that there are now no values displayed in

the data pane This is because when an entity type has a datatype assigned to it only the

instances that have the same datatype are displayed

If you can see instances of Telecoms number at this stage it means that your database

may have already been customised by another user or that you did not create a

completely new chapter as the Data changes chapter for this demonstration

The TelecomsNumber datatype is defined as a value datatype and Telecoms number is

therefore a value type and can only be used as a target and not as the source of

association types

The TelecomsNumber datatype requires that all instances start with the + character and

only contain numerals and parentheses characters ( ( and ) )

1 Highlight the Person entity type and open the Default Dataform from the shortcut

menu Create a new instance with the name Arthur Test and enter the following value in

the Home telephone association field

1 (212) 262 4515

This value is not valid Click Save amp Edit or tab out of the field Sentences indicates an

invalid value by highlighting the Person page and the Home telephone number field in

red Sentences also displays an error message in the Message Log because the value does

not commence with the character +

2 Enter the value

+ 1 [212] 262 4515

the Home telephone number field and tab out of the field

Sentences rejects this value also because the value contains square bracket characters ( [

and ] ) that the datatype does not allow The Home telephone number field remains

highlighted with a red background and displays the string +12 (345) 678 9123 which is

an example of the correct format for a valid value

3 Enter the value

+ 1 (212) 262 4515

the Home telephone number field and click Save amp Edit followed by Close Sentences

accepts this value and display it in the data pane when you select Telecoms number in

the schema pane

4 In the Sentences Explorer schema pane select the Person entity type and select an

instance of Person for example Barney Norris Open the Dataform for Barney Norris


Worked examples

454

Figure 11-35 Previous data no longer visible in Dataform

The Home telephone and Work telephone associations on the Person page of this

Dataform are empty and display the place-holder text ltTelecoms numbergt as shown

in Figure 11-35 This is because these association types use Telecoms number as their

target As you have just changed the datatype for this Telecoms number any instances

created before the change of datatype are no longer visible

5 Click the ellipsis button on the Home Telephone association field and select the

only available value from the picker list This is the new value you have just created +1

(212) 262 4515 Click Save

6 Type in a valid value for the Work telephone association field for example +1 (212)

544 6241 and click Save Sentences accepts the update Click Close on the Dataform

7 Select Telecoms number in the Explorer schema pane Only the newly created valid

values for Telecoms number are displayed in the data pane

The default Style for the TelecomsNumber datatype is its Full format You can select

Full or Number only by using the Style field on the Format page of the Properties

dialog Select the Telecoms number entity type in the schema pane and open the

Properties dialog and select Number only for the Style field and click OK on the dialog

to apply the change then click Close

8 Click the Refresh button on the toolbar The display of values for Telecoms number

throughout Sentences now appears in the Number only style as a leading + followed by

digits only

9 Select Telecoms number and select Properties from the shortcut menu Select the

Datatype page and set the datatype to ltNonegt Click OK and Close

10Click the Refresh button on the toolbar The original values for Telecoms number

are now visible Scroll to the end of the list of instances in the data pane using the

Morehellip prompt if necessary The newly created values are visible and are listed after the

original instances This is because datatype ltNonegt allows visibility of all other

datatypes The new values are in a separate group because values are sorted in

independent groups by datatype These instance are displayed in the default style for their

datatype as they are not of the current datatype for the entity type

Restoring the original Human resources example application

To restore the original Human resources example application follow these steps

1 Set the datatype of Telecom number back to TelecomsNumber

Client API example

Worked examples

455

2 Open the dataform on the Person you edited (Barney Norris) Delete the instances

you created for the Home telephone and Work telephone associations Click Save and

Close

3 Delete the additional Person instance you created (Arthur Test)

4 Reset the datatype of the entity type Telecom number to ltNonegt Refresh the data

pane display of Telecom number instances

5 Open the Edit Profile dialog Highlight the HR custom datatype test data chapter

and click remove Make the existing chapter Human Resources data the Data changes

chapter and save the profile

6 Remove the custom datatype JAR file from the defined location for datatypes on the

Sentences server This location is specified by the DatatypePath property in the



Alternatively set the datatype of the entity type Telecom number to ltNonegt and

remove the HR custom datatype test data chapter from the profile

Client API example

A simple example of using the Sentences Client API is included in the Sentences

installation This is a Java program called SalaryUpdate implemented in a Java class

SalaryUpdate and defined in a Java package called

comsentencesexamplesclient (under the directory Examples) The example

consists of a source code file SalaryUpdatejavaand a built Java archive

SalaryUpdatejar in the subdirectory Jars

This section demonstrates the use of SalaryUpdate with the Human resources

example application As this program uses the Client API it can run alongside other client

access to the Sentences database The Sentences server must be running to allow the

SalaryUpdate program to access the database

In the Human resources example application Employees have employment history

events including salaries recorded by date The SalaryUpdate program takes two

arguments on its command line which are the Employee to be updated and the new

Salary value to assign The program first lists all the existing salary events for the

Employee then creates a Raise event assigning the new salary with effect from todayrsquos

date

Preparing to run the demonstration

This example is a standalone Java program which must be run using a Java 13 or higher

compliant virtual machine The following instructions are based on the following

assumptions

bull You are running the Sentences server on a Microsoft Windows operating system

bull Your installation of Sentences is in CProgam FilesLazySentences40

If your copies of Java and Sentences are in different locations you must modify the path

names in these instructions accordingly

Using the Salary Update example

The client-side API used by this example program requires that the Sentences servlet is

running and therefore it cannot be used with the Sentences Personal Edition

The following conditions must be met before you can run the example program All these

conditions are met automatically if you are using a default installation of Sentences with

Tomcat The conditions are

Client API example

Worked examples

456

bull The example program must be run on the machine where the Sentences server is

installed This is because the example code uses a fixed value for the Sentences

connection host (localhost) It also guarantees local access to the required Sentences

JAR file and Java installation

bull The Sentences server must be serviced by a Web server responding to a fixed IP port

number port 8090 This is because the example code uses a fixed value for the port

number

bull The Web server and servlet container for Sentences must be running and able to start the

Sentences servlet

bull You must know the location of and have access to the Sentences Enterprise Edition

installation and an installation of the Java 2 Runtime Environment (J2SE JRE)

In addition to these conditions you must adapt your Sentences installation to enable Client

API connections as described in the following section

Enabling Sentences Client API connections

You must make sure that client API access to Sentences is enabled for your installation

Although access is enabled in the default installation of Sentences the default setting may

have been changed for some reason To verify that access is enabled follow these steps

1 Using a text editor open the Serverproperties file and locate the section headed

Access to the different Sentences Servlets

2 Find the setting for the client API servlet which is

ClientApiAccess

3 Make sure that this setting is set to true as follows

to

ClientApiAccess=true

4 Save the file then stop and restart your Sentences server

Setting up the demonstration profile

You need to create a new profile to demonstrate the SalaryUpdate program

1 Ensure that your Sentences server is running start the Sentences client and open the

Human resources example application

2 Open the Edit Profile dialog and create a new profile named Human resources API

updates

3 Use the Add and New options to create a new chapter The chapter can have any name

you like for example API updates chapter Use this chapter as the target for Data

changes Set the target for Schema changes to (none)

4 Click OK and Yes to save this new profile

Creating a command file

The example SalaryUpdate program must be run from a command line The actual

command needed to run this program may be quite long (depending on the actual file

paths used on your system) so you must create a batch file to run the program as follows

1 Make a copy of the batch file lazystartbat in the

ltSentences_homegtResources directory and name it SalaryUpdatebat Move

this file to the ltSentences_homegt directory and open it using a text editor

2 In the CP (classpath) section add the following two new lines immediately after

the line set CP=SENTENCES_HOME

set CP=CPSENTENCES_HOMETomcat4webappssect

Client API example

Worked examples

457

SentencesSentencesjar

set CP=CPSENTENCES_HOMEExamplesJarsSalaryUpdatejar

3 In the Java Execution command section edit the last line of the file to include the

path to the Salary Update example classes as follow

_RUNJAVA JVM_OPTS -cp CPsect

comsentencesexamplesclientSalaryUpdatesect

1 2 3 4 5 6 7 8 9

4 Save the file as plain unformatted text in the Sentences_home directory The

Salarybat file you have created invokes the Java interpreter passes it the example

specific and Sentences client Jar files as a classpath argument then specifies the example

specific class as the program entry point and passes it up to nine arguments as entered on

the command line

Demonstrating the Salary Update example

The following procedure demonstrates how the example client API program can submit

updates to the database It assumes that all the previous procedures within this section

have been successfully completed

1 Ensure that the Sentences server is running start the Sentences client and open the

Human resources API updates profile

2 Highlight the Employee entity type in the Explorer schema pane select the Employee

instance Barney Norris and open the Default Dataform

In the dataform for Barney his employment history is shown in the table titled Event

His last salary change from 01-May-2000 shows that his latest salary is $76500 Itrsquos

time for Barney to get a raise Leave the dataform open

3 On the host where the Sentences server is installed open an MS-DOS prompt window

and navigate to the Sentences installation directory where you saved the command file

SalaryUpdatebat

4 At the MS-DOS prompt enter the following command

SalaryUpdatebat ldquoBarney Norrisrdquo USD83500

5 As it is running the salarybat command should output messages similar to the

following

6 If the final line of the message is not Successful completion there has been an

error and you may see the text

User message ERROR in class SalaryUpdate ERROR exit

followed by a description of the error

If the entered Employee was not found the error description is similar to

The requested Employee Barney Norriss was not found

CProgram FilesLazySentences22gtSalaryUpdatebat Barney Norris

USD83500

User message class SalaryUpdate Sentences Example code started

Human

resources API updates

User message class SalaryUpdate Opening Sentences client session to

host localhost port 8090 and profile Human resources API updates

Salary history for Employee Barney Norris

01-Jun-1997 Joined $47000

01-Feb-1999 Raise $58500

01-May-2000 Promoted $76500

User message class SalaryUpdate Salary update performed

Successful completion

Integration with Microsoft Office applications

Worked examples

458

If the entered Salary was not valid the error description is similar to

The supplied salary value USD 83500 was incorrectly formatted

Other possible causes of error include

bull mistakes in the SalaryUpdatebat file

bull mistakes in the entered arguments

bull the Sentences server is not running

bull you have not enabled Client API connections at the server

bull you are running the Sentences Personal Edition instead of the Enterprise Edition

7 Return to the open dataform on Barney Norris in your Sentences client The data

displayed is unchanged as Sentences does not push data changes to clients

8 Close and re-open the dataform on Barney Norris The Event table now shows his

updated employment history including his new salary $83500 with todayrsquos date

9 You can repeat these actions with other inputs to demonstrate the program further


To restore the database to its original condition do the following

1 Delete the profile you created for this demonstration Human resources API

updates

2 You may wish to disable subsequent client API connections to the Sentences server To

do this reverse the steps you took to enable client API connections (see ldquoEnabling

Sentences Client API connectionsrdquo )


You can use CSV Export (see ldquoCSV Exportrdquo ) and CSV Import (see ldquoCSV Importrdquo ) to

integrate data from Sentences with Microsoft Office applications

For example you can use Sentences data with Microsoft Word to create Mail merge

documents and email messages and with Microsoft Outlook create Contacts data

You can also import data from Microsoft Outlook Contacts into Sentences In some of the

following procedures you can use data exported from Sentences directly in a Microsoft

Office application and in other procedures you need to modify the data using another tool

such as Microsoft Excel before it can be used

The procedures in this section have been tested with Microsoft Office 2000 running on

Windows 98 and Window NT 40 operating systems Some of the commands used in

these examples may be slightly different in other versions of Microsoft Office

These procedures can be used with either the Sentences Enterprise Edition or the


Creating Mail merge letters from Sentences data

You can use information from a Sentences database as a data source when you create a

Mail merge letter in Microsoft Word You must first use a query in Sentences to select

the data you want to use and then export the query result as a CSV file

To generate a Microsoft Word Mail merge letter using names and addresses from a

Sentences database follow these steps

Exporting address data from Sentences

1 In Sentences create or configure a query to return names and addresses for the

intended recipients This may be either


Worked examples

459

bull using an existing query or create a new query or

bull using a parameter to select the correct recipients for each letter or

bull adding one or more entity types or association types to define letter types and who

should receive them

An example query for this purpose which returns the names and addresses for

Employees from the Human resources example application is shown in Figure 11-36

Figure 11-36 Sentences query for Employee mail merge

2 In the Sentences Explorer highlight the query name and select Export to CSV filehellip

from the Results option on the Query menu or from the shortcut menu

3 Sentences displays a Windows file dialog Select a suitable location for the CSV export

file on your system and save the file The default file extension for Sentences CSV output

on Windows is csv

4 Using Microsoft Notepad or a similar text editor open the CSV file you saved The file

should look like the one shown in Figure 11-37

Figure 11-37 CSV Export output file in a text editor


Worked examples

460

Importing address data into Microsoft Word

1 In Microsoft Word create your form letter and use place-holders such as name and

address where you want merged data to appear

2 In Microsoft Word select Mail mergehellip from the Tools menu Word displays the

Mail Merge Helper dialog This dialog asks you to make selections in three steps

3 In step 1 Main document select Create and then Form letters and specify the form

letter you have prepared

4 In step 2 Data source select Get data and then Open data source and then navigate

to the directory where you saved your CSV file Microsoft Word does not include the

csv extension in the list of file options so you need to select All types to select your

file When you have selected your file click OK

Microsoft Word prompts you to return to your main document

5 Highlight one of the place-holders in your document and select Insert Merge field

from the Mail merge tool bar If the Mail merge tool bar is not visible select Toolbars

and then Mail merge from the View menu

6 Select the field you want to use from the list of fields for example Employee You

must repeat this step for every field you want to insert The merge field names are derived

from the first line of the CSV file which is treated as a line of column headings Second

and subsequent columns of the CSV file are named by Sentences with a combination of

their entity type and association type verb As an example the Employee address column

from the example application appears as merge field Addressaddress Do not change the

column headings line

7 Select the Merge button and in the dialog box select New document and then click

Merge Microsoft Word creates a new document containing one form letter for each set of

data in the CSV file This document can be saved printed and also edited as you require

Creating Mail merge emails from Sentences data


Mail merge electronic mail messages (emails) in Microsoft Word You must first use a

query in Sentences to select the data you want to use and then export the query result as a

CSV file You must the edit the CSV file in Microsoft Excel before you create your

emails

The Mail merge email procedure requires you to have a Messaging Application

Programming Interface (MAPI) compliant email package such as Microsoft Exchange

installed on your system

To generate a Microsoft Word Mail merge email using names and addresses from a


Exporting email data from Sentences

1 In Sentences create or configure a query to return names and email addresses for the


bull using an existing query or create a new query

bull using a parameter to select the intended recipients for an email

bull adding one or more entity types or association types to define email types and who

should receive them

An example query for this purpose which returns the names and email addresses for



Worked examples

461

Figure 11-38 Sentences query for Employee email mail merge





on Windows is csv

Figure 11-39 Email query output in Microsoft Excel

Modifying the email data CSV file in Microsoft Excel

1 Open your CSV file in Microsoft Excel The file should look like the one shown in

Figure 11-39 Note that any Employee who does not have an email address in the

Sentences database is shown without an email address in the CSV file

2 Sentences requires the protocol string mailto in email addresses but the MAPI mail

program does not To remove it select the Replace option from the Edit menu and type


Worked examples

462

in the string mailto (with a space at the end) in the Find what field Leave the

Replace with field blank and click Replace all

3 Save the CSV file from Excel using the Save as type option CSV (Comma

delimited)

Importing email data into Microsoft Word

1 In Microsoft Word create the text of your email and use a place-holder such as name

where you want merged data to appear The email address does not need to appear in the

standard document

2 If you want your the text from your main document to appear in the body of your

email you should save the document as plain text with no formatting Use the Word Save

as type option Text Only If you save your document as a formatted Word document it is

sent as an email attachment




email you have prepared

5 In step 2 Data source select Get data and then Open data source and navigate to

the directory where you saved your CSV file from Excel Microsoft Word does not

include the csv extension in the list of file options so you need to select All types to

select your file Be sure to select the file with edited email addresses as saved from

Excel not the file as output from Sentences When you have selected your file click OK


6 Highlight one of the place-holders in your document such as name and select Insert

Merge field from the Mail merge tool bar If the Mail merge tool bar is not visible select

Toolbars and then Mail merge from the View menu

7 Select the field you want to use from the list of fields for example Person You need to

repeat this step for every field you want to insert

8 Select the Mergehellip button and in the dialog box select Electronic mail and then click

Setup

9 In the field Data field with MailFax addresses select the column name from the CSV

file which contains the email addresses With the Human resources example application

this column is named with a combination of its entity type and association type verb as

Hyperlinkemail_address

10Type in some text for the email subject line in the Mail message subject line field

11If you have created a formatted document select the Send document as an

attachment checkbox If you have created a plain text document leave this checkbox

clear Click OK to return to the Mergehellip dialog box

12In the Mergehellip dialog box click Merge Microsoft Word creates an email message

which is sent to each email address in the CSV file A copy of each message is placed in

your Sent Items folder

Creating Microsoft Outlook Contacts from Sentences data

You can export data from Sentences to for use in a Microsoft Outlook Contacts folder

You must first use a query in Sentences to select the data you want to use and then export

the query result as a CSV file You then need to edit the CSV file in Microsoft Excel

before you import it into Microsoft Outlook After import you need to configure the

Outlook folder for use as an address book


Worked examples

463

Exporting Contacts data from Sentences

To create a CSV file follow these steps

1 In Sentences create or configure a query to return the data you want for each person

such as name address phone number email address and so on This may be either


bull using a parameter to select the correct recipients for each letter


should receive them

An example query for this purpose which returns the name address home telephone

work telephone email address and date or birth for Persons from the Human resources

example application is shown in Figure 11-40

Figure 11-40 Sentences query for Outlook contacts

2 In the Sentences Explorer highlight the query name and run Export to CSV filehellip

from the Results option on the Query menu or on the right-click context menu



on Windows is csv


Worked examples

464

Figure 11-41 Outlook contacts query results in Microsoft Excel

Modifying Contacts data in Microsoft Excel


Figure 11-41

2 Sentences requires the protocol string mailto in email addresses but the Outlook

does not To remove it select the Replace option from the Edit menu and type in the

string mailto (with a space at the end) in the Find what field

Leave the Replace with field blank and click Replace all


delimited)

Note You do not need to delete any duplicate columns in your file If you are planning to

import data from an Outlook Contacts folder into the same Sentences database then you

can refer to this CSV file to learn what column structure matches the database

Importing Contacts data into Outlook

To import the data into Outlook follow these steps

1 Open Microsoft Outlook and select the Contacts folder You may want to create a new

contacts folder for the data imported from Sentences To add a new folder right click the

Contacts folder and select New Folder from the shortcut menu

2 Highlight the target Contacts folder and select Import and Export on the File menu

This displays the Import and Export wizard

3 The steps in the Import and Export wizard are as follows

bull Select Import from another program or file and click Next

bull Select the option Comma separated values (Windows) and click Next

You may be need to install an additional software module if you have never imported this

kind of file into Outlook before

bull Use the Browse button to navigate to the directory where you saved your CSV file from

Excel Be sure to select the file with edited email addresses as saved from Excel not the


Worked examples

465

file as output from Sentences Choose one of the options for dealing with duplicate data

and click Next

bull Select the destination folder and click Next

bull In the next screen select the checkbox next to the option Import

ltfilenamecsvgt into ltfoldernamegt Click Map custom fieldshellip if the Map custom

fields dialog does not open automatically

bull In the Map custom fields dialog choose the way you want the columns in your CSV file

to map to the fields in the Outlook contacts folder Mappings can be created by dragging

and dropping values from the From list to the To list

An example of a finished mapping from the Human resources example to Outlook may

look like the list below

Field Mapped from

Name Person

Home Address Address address

Business Phone Telecoms number work telephone

Home Phone Telecoms number home telephone

Name Person


bull At this stage you should ignore duplicate fields in your file After completing the

mapping of your fields click OK and then click Finish

bull Outlook should now import your data to the target folder and create or populate

Contact records with the data from Sentences

Configuring the new folder as an address book folder

To configure the new contacts folder as an address book folder follow these steps

1 Highlight the new contacts folder right-click and select Properties from the shortcut

menu

2 Select the Outlook Address book page and select the check box Show this folder as

an email address book and click OK

3 Select the Services command on the Outlook Tools menu

4 On the Addressing page below the box marked When sending mail check names

usinghellip click Add

5 Select the new contacts folder and click Add then click Close Apply and OK

6 Now when you type the contacts name into the address field of an email Outlook can

find the corresponding email address

Creating Sentences data from an Outlook Contacts folder

Microsoft Outlook allows you to export Contacts data to a CSV file and you can use this

feature to take data from Outlook and import it into Sentences

You must make sure that the layout of the data in your CSV file matches the schema of an

existing Sentences database One way to do this is to examine a CSV file exported from a

Sentences database for example one created by the procedure described in ldquoCreating

Microsoft Outlook Contacts from Sentences datardquo 4


Worked examples

466

You can edit the CSV file derived from Outlook in Microsoft Excel or in a text editor to

make sure that it conforms to the structure you need You may need todivide the data

from Microsoft Outlook into two or more CSV files before importing the data into

Sentences

Creating a CSV file from Microsoft Outlook

1 In Outlook select Import and Export from the File menu

2 In the Import and Export wizard follow these steps

bull Select Export to a File and click Next

bull Select Comma separated values (Windows) and click Next

bull Select the folder you want to export from in this case a Contacts folder and click Next

bull Type in a path and file name for your CSV file or click Browse to select an existing

file and click Next

bull Select the check box next to Export Contacts from the Contacts folder

Click Map custom fieldshellip if the Map custom fields dialog does not open automatically

bull In the custom fields dialog select the fields you want to export and click OK If you

have recently imported a CSV file into Outlook the field names from that file are shown

in the custom fields dialog

bull Click Finish

Editing the Outlook CSV file for import into Sentences

You need to edit the CSV file that is created by Outlook before you can import the

Contact data into Sentences You can do this in Microsoft Excel or using a text editor

When you edit the file you should note the following points

bull The values created by Outlook for Name fields are based on the value stored in the ldquoFile

asrdquo field You may want to change this value when you edit the file

bull You may need to rename the column headings - the values in the first row of each

column - to match the type names required by Sentences

bull If you want to import email addresses into Sentences you need to add the string

mailto to the start of each email address To do this in Excel follow these steps

1 Open your CSV file in Microsoft Excel

2 In the first new column paste the string mailto into every cell

3 In the second new column give row 1 the value of row 1 in the column containing the

email addresses from Outlook for example ldquoHyperlink email addressrdquo

4 In all other cells paste an Excel function to concatenate these values together if the

Outlook email address is not blank eg

ldquo=IF(ISBLANK(E2)CONCATENATE(G2E2))rdquo

5 Add a new sheet to the Workbook

6 Cut and Paste the original column of email addresses into the first column of the new

sheet

7 Repeat for the column of mailto values into the second column of the new sheet

8 Save the file to a new CSV file

bull You should now be able to import these contacts into Sentences using the CSV Import

command

Integration with Crystal Reports

Worked examples

467

Copying Excel Data to and from Sentences

Contiguous selections of cells in Microsoft Excel can be pasted into a Sentences

Dataform table Any empty cells will be ignored but incompatible values will produce an

exception After pasting the data the Dataform can still be saved or canceled in the usual

way

The context menu on the first column of a Dataform table includes a Copy menu item that

copies the table contents onto the clipboard in the format that Excel is expecting


Crystal Reports can use an XMLSchema definition and XML data as a source input to

Reports See ldquoReporting using SAP Crystal Reportsrdquofor details

Sentences Explorer menus

Menus and Commands summary

469

Appendix A


All the following menu command key combinations and shortcut keys are valid in the

Microsoft Windows operating system environment only This summary has not been

updated for Version 40


Menu namehellip contains these commands Keyboard

sequence

Shortcut

File New Profile 1 Alt+f n Ctrl+n

Open Profile 1 Alt+f o Ctrl+o

Edit Profile 1 2 Alt+f e

Delete Profile 1 2 Alt+f d

Refresh Profile Alt+f r

Reload data Alt+f a F5

Exit (Personal Edition

only)

Alt+f x

Edit Cut 3 Alt+e t Ctrl+x

Copy 3 Alt+e Ctrl+c

Paste 3 Alt+e p Ctrl+v

Delete 2 3 4 Alt+e d Delete

Rename 2 3 4 Alt+e m Ctrl+ r

Properties 5 Alt+e r Ctrl+p

View Default Dataform Alt+ v f Ctrl+ d

Show source and target Alt+ v s

Follow hyperlink Alt+ v h

Retrieve by source Alt+ v b

Retrieve sorted Alt+ vs



470

Menu

name

contains these commands Keyboard

sequence

Shortcut

Retrieve unsorted Alt+ v u

New Explorer Tab Alt+ v n

New Explorer Tab on Target Alt+ v t

Delete Explorer Tab Alt+ v d

Expand All Alt+ v x

Collapse All Alt+ v c

Expand Node Alt+ v p

Collapse Node Alt+ v l

Stop Execution (Q) Alt+ v q

Messages Alt+ v m

Triggers Alt+ v i

Options Alt+ v o

Diagram Editor Alt+ v a

Schema Create Entity Type 2 Alt+ s e

Create Association Type 2 Alt+ s n

Insert Association Type Above 2 Alt+ s a

Display in Core types folder 279 Alt+ s o

Display in Core queries folder 27 Alt+ s o

Attach Set Query 6 Alt+ s u

Attach Query 2 Alt+ s y

Tables and Views 8 Alt+ s l

Export Schema to XML Alt+ s t

View Schema in XML Alt+ s v



471

Menu

name


sequence

Shortcut

Query Create Set Query 6 Alt+ q s

Create Query 2 Alt+ q c Ctrl + q

Edit Query 2 Alt+ q q

Execute Query Alt+ q x

Results Export to CSV file Alt+ q r v

Results Export XML results Alt+ q r e

Results Export XML DTD Alt+ q r o

Results Export XSL Stylesheet Alt+ q r x

Results View XML results Alt+ q r i

Help Help Topics Alt+ h t

Tutorial Alt + h u

About Alt+ h a

Notes

1 Not shown when the profile cannot be changed

2 Not shown when user cannot edit schema

3 Not shown when user can deleterename data but not schema

4 Not shown when user cannot edit schema or data (in addition to 2)

5 Properties are read-only when the schema is read only

6 Not shown when Set Queries are not selected in the Edit Profile dialog

7 The Display in Core types folder command is only available for types and the Display

in Core queries folder command is only available for queries

8 The Tables and views command is used only with the LazyView tool For more

information please refer to the LazyView Guide

9 The Display in Core types folder command is only available if the Core types arenot

being created automatically

Sentences Explorer function keys


472


Key combination Action

F1 Sentences help (in Sentences Personal Edition) Browser

help (Sentences Enterprise Edition)

F2 Allows in-place renaming

F5 Reload data in the Explorer or execute the selected query in

the explorer

F6 Toggle between data pane and schema pane

F8 Select vertical divider for resizing

F10 Select first menu on menu bar

Alt + F4 Closes current window

Shift + F10 Displays browser shortcut menu

Tab Moves to next control in sequence (sequence includes Filter

and Positioner fields)

Alt + Tab Move to next operating system application

Shift + Tab Moves to previous control in sequence (Sequence includes

toolbar)

Dataform function keys




Alt + F4 Allows in-place renaming

Alt+F6 Sentences help (in Sentences Personal Edition) Browser


Shift F10 Allows in-place renaming

Tab Reload data in the Explorer or execute the selected query in

the explorer

Alt+Tab Toggle between data pane and schema pane

Shift+Tab Select vertical divider for resizing

Ctrl+Tab Select first menu on menu bar

Ctrl+Shift+Tab Closes current window

Query Editor menus


473

Query Editor menus

Menu

name contains these commands

Keyboard

sequence Shortcut

Query Save Query 1 Alt+ q s

Save as 1 Alt+ q a

Properties Alt+ q r

Close Alt+ q c

Edit Add Alt e + a

Add submenu

Associations Alt e + a s

Add submenu

Instance Specific Associations Alt e + a n

Add submenu

Derived type Alt e + a d

Add submenu

Selection Alt e + a i

Add submenu

Sort Alt e + a o

Add submenu

Page Alt e + a p

Hide Branch Alt e + h

Show Branch Alt e + s

Bind to instance Alt e + b

Bind to node Alt e + o

Make recursive closure 2 Alt e + k

Add transitive closure 3 Alt e + n

Set Required Alt e + i

Set Derivation Alt e + v

Edit Expression Alt e + x

Properties Alt e + r Ctrl + p

Cut Alt e + t Ctrl + x

Copy Alt e + c Ctrl + c

Paste Alt e + p Ctrl + v

Delete Alt e + d Del

Rename Alt e + m

View Expand All Alt v + x

Collapse All Alt v + c

Expand Node Alt v + p

Collapse Node Alt v + l

Create Parameter Alt p + r

Set Type Alt p + t

Set Default Value Alt p + f

Query Editor function keys


474

Menu


Keyboard

sequence Shortcut

Set Mandatory 3 Alt p + n

Results Execute Query Alt r + x

Reload data Alt r + a F5

Stop Execution (Q) Alt r + q

Export to CSV file Alt r + v

Export XML results Alt r + e

Export XML DTD Alt r + o

Export XSL Stylesheet Alt r + p

View XML Results Alt r + i

Dataform Default Dataform Alt d + f Ctrl + d

Custom Dataform Alt d + u

Help Menu Help topics Alt+ h t

Tutorial Alt+ h u

About Alt+ h a

Notes

1 Not shown when the user cannot save changed queries

2 Displays Make recursive closure or Break recursive closure depending on the status of

the selected node

3 Displays Add transitive closure or Remove transitive closure depending on the status of

the selected node

4 Displays Set mandatory or Set optional depending on the status of the selected

parameter



F1 Sentences help

F2 Allow in place renaming

F5 Executes the current query





Alt + F6 Toggle to Java console display


Tab Moves to next control in sequence


Shift + Tab Moves to previous control in sequence

Diagram Editor menus


475


Menu Command Keyboard

sequence

Shortcut

File Export Diagram1 Alt f + e

Import Diagram Alt f + i

Save as GIF Alt f + s Ctrl S

Page setup Alt f + u

Print Alt f + p

Close Alt f + c

Edit Add association types Alt e + a

Add query results Alt e + q

Copy Alt e + c

Paste Alt e + p

Remove Alt e + r

Remove all Alt e + m

Select all Alt e + s

Add core entity types Alt e + e

Add all entity types Alt e + y

Add annotation Alt e + n

Add Title Alt e + t

Add Chapter Legend Alt e + l

Refresh Chapter

Legend

Alt e + f

Increase font size Alt e + I

Decrease font size Alt e + d

Increase zoom Alt e + z

Decrease zoom Alt e + o

View Default dataform Alt v + f Ctrl-D

Follow Hyperlink Alt v + h

Expand all Alt v + x

Collapse all Alt v + c

Expand node Alt v + p

Collapse node Alt v + l

Diagram Editor function keys


476


sequence

Shortcut

Stop Execution Alt v + q

Preferences Alt v + r Ctrl-P

Draw finished diagram 1 Alt v + g

Help Help Topics Alt h + t

Tutorial Alt h + u

About Alt h + a

Notes

1 Displays Draw finished Diagram or Draw outline diagram depending on the current

drawing mode



F1 Sentences help (in Sentences Personal Edition)

Browser help (Sentences Enterprise Edition)

F6 Toggle between canvas pane and schema pane



Alt+F4 Closes current window


Tab Moves to next control in sequence (sequence does

not includes toolbar) Includes individual diagram

elements


Shift + Tab Moves to previous control in sequence (Sequence

does not includes toolbar) Includes individual

diagram elements

Ctrl+Tab Moves to next control in sequence including out of

the diagram canvas

Shift+Ctrl+Tab Moves to previous control in sequence including

out of the diagram canvas

Viewing Sentences statistics

Statistics and analysis

477

Appendix B


This chapter contains information covering topics intended for use by a System

Administrator who needs to monitor the usage and statistics of the Sentences Server

as follows

bull Viewing Sentences message statistics

bull Viewing Sentences user statistics

bull Viewing Sentences profile statistics

bull Viewing Sentences chapter statistics

bull Viewing scheduled process list status

bull Detailed Chapter statistics

bull Chapter file analysys


When you install Sentences with Tomcat a statistics servlet is installed alongside the

main Sentences servlet The statistics servlet has the class name

comsentencesservletStatsServlet

You can control the access to Sentences servlets including the statistics servlet by setting

parameters in the Serverproperties file (see ldquoServlet access toSentencesrdquo on page 1-

75) By default access to server statistics is set to true and access to chapter statistics is

set to false

The Sentences installation links this servlet to the URL path Statistics If access to

the statistics server is allowed you can access the statistics servlet by entering a URL in

your browser for example

httplocalhost8090SentencesStatistics

You must substitute the name of your installationrsquos Sentences host for localhost8090

in the example

If you are not using Tomcat you need to configure your web server and servlet container

to use the statistics servlet

The statistics servlet returns a standard HTML page which can be viewed in any browser

without needing an applet The page is not dynamic which means that it is not

automatically updated as the data changes Use your browserrsquos Refresh command to re-

load the page with more current data

The page contains four tables covering messages profiles users and chapters and a

memory usage summary



478

Message statistics

Figure B-1 Server message statistics

Figure B-1 shows the message statistics for the host named in the table heading The first

data line shows total counts since the server was started and the second line shows counts

for a recent one-minute period

The columns in the table are as follows

Column Description

Time Period The time period for which counts are shown

Messages In The number of messages received during the time period

Average Delay If messages have been delayed by the throughput limiting

mechanism this column shows the average time in milliseconds

by which messages have been delayed

Max Delay If messages have been delayed the maximum time that any

message has been delayed in milliseconds

Messages Out The number of message responses sent during the time

period

Average Time The average time in milliseconds taken by the server to

respond to a message

Max Time The maximum time in milliseconds taken by the server to


User statistics

Figure B-1a User statistics

Figure B-1a shows user statistics for the host named in the table heading There is one

data line for each user that has logged onto the system on this server The ldquologged inrdquo

column will only show ldquonordquo if the user explicitly logged out of the system Simply

closing their client browser will not log them out of the system

Open profile statistics

Figure B-2 Open profile statistics



479

Figure B-2 shows the open profile statistics for the host named in the table heading There

is one data line for each profile that is currently in use on this server The system profile

Profiles is always shown as currently in use ldquoCurrently in userdquo means that the profile has

been opened and that the server has not yet closed it The server closes a profile after it

has remained inactive (has received no requests) for a period of time determined by the

ProfileTimeout value in the Serverproperties file

The columns in the table are

Column Description

Profile Name The name of the profile Any profile that is not available to be

opened by users for example one that has been edited but

not saved is marked with an asterisk

Opened Time The time that the profile was opened

Requests

The number of requests that this profile has processed since

it was opened Each message from the client is a request

but requests are also generated internally so that in general

the total number of requests is higher than the total number

of messages received

Pending Results

Whenever a client result includes a continuation marker

shown in the Sentences Explorer as the Morehellip prompt the

server retains data about the request so that more data can

be supplied if requested These pending result sets are

discarded when the client indicates that they no longer

required or after a period of time determined by the

ldquoPendingTimeoutrdquo parameter in the Serverproperties file

This column shows the number of such result sets currently

held by each profile

Open Queries

Whenever a query is to be executed it must first be

validated The server keeps a list of validated queries

This column shows how many are held by each

profile

Visible Hidden

Trans

These columns show the number of references held in the

profiles visibility cache the number of database items

known to be visible the number known to be hidden and

the number of transactions known to have been validly

committed The visibility cache contributes to the memory

requirement of each open profile these numbers provide an

indication of the size of that contribution



480

Chapters statistics

Figure B-3 Chapters statistics

Figure B-3 shows the chapters statistics for the host named in the table heading There is

one data line for each available chapter on this server


Column Description

Chapter Name The name of the chapter as shown in the Edit Profile

dialog

Cache Size The amount of memory currently in use as a database file

cache for that chapter

Disk Requests The number of requests made by the profiles for database

objects from that chapter file since it was opened

Cache Hits The number of requests for database objects that were met

from the database file cache

Cache Hit Rate The number of cache hits expressed as a percentage of the

total number of disk requests

Detailed chapter statistics

More detailed statistics on chapter files are available Before you can view these detailed

statistics you must enable the Chapter Statistics servlet For details of how to enable the

Chapter Statistics servlet see ldquoServlet access to Sentencesrdquo

After you have enabled the Chapter Statistics servlet each of the chapter names shown in

the Chapters statistics table (Figure B-3) is an active hyperlink Clicking the link displays

a summary page for the chapter as shown in Figure B-4



481

Summary page

Figure B-4 Chapter summary page

The summary page heading is the chapter name as shown in the Edit Profile dialog The

Chapter UID is the internal identifier by which the chapter is known to Sentences The

Path is the pathname of the disk file for the chapter If the SpatialAccess property in

the Serverproperties file is set to false meaning that access to the Spatial view is

not allowed the summary page displays the message Spatial view unavailable

The following sections give more details of the Spatial view Block statistics and Triple

counts options

Spatial view

Access to the spatial view is controlled by a separate servlet listed in the

Serverproperties file (see ldquoServlet access to Sentencesrdquo ) By default access to the

spatial servlet is set to true

Click the link to the Spatial view to see a three-dimensional graphical representation of

the data stored in the file as shown in Figure B-5

Figure B-5 Spatial view of chapter file

The spatial view uses an applet to show a three-dimensional map (a cube shape) of the

distribution of triples within the chapters triple store The three axes of the cube represent

source IDs (red axis) verb IDs (green axis) and target IDs (blue axis) Each triple is



482

represented by a white dot at the point corresponding to its source verb and target The

cube is intersected by orange lines which represent the boundaries of triple pages The

applet allows you to rotate the cube by dragging the mouse pointer over it You can also

zoom in to display a section of the cube at higher magnification and zoom out to return to

the less detailed view

Note Displaying the spatial view or triple counts on a large chapter is a resource

consuming operation which may have a noticeable impact on a running server

Block statistics

The block statistics page shown in Figure B-6 displays a table of information about the

contents of the blocks used by the chapter file

Figure B-6 Block statistics

The left-hand column of the Block statistics table headed Type lists the various block

types that are used within the file The following table describes the information given for

each type

Column Description

Blocks The number of blocks of that type in the file

Entries The total number of entries Each block type has its own

specific type of entry for example each entry in a triple

store block is one association

Bytes free The total amount of free space within the blocks of that type

Bytes available The total amount of usable space within the blocks

Percent free The fraction of the usable space which is currently free

shown as a percentage

The block types used are shown in the following table

Type Description

File Header The header of the file This holds datatype information and

data about other chapters referenced from this one

Entity Types An index to the entity types which have instances held in this

chapter Each entry is an entity type

Atom Store

Entity instances both values and non-values are held in the

atom store which provides access by type and name Each

entry is an entity instance This includes entities with long

names (see Long Atoms below)



483

Type Description

Long Atoms

Entity instances which are too long for the name index

structure are held in a separate area of the file Each entry is

one entity instance with a long name

Atom ID Table The index to entity instances by Sentences ID Each entry is

one entity instance

Triple Index An index to the pages of the triple store Each entry holds

information about one triple page

Triple Store The pages holding associations Each entry is an

association

Triple ID Table The index to associations by Sentences ID Each entry is an

association

Triple B-Tree A secondary index to associations by target Each entry is an

association

Triple counts

The triple counts page counts the numbers of triples of various kinds in the triple

store and displays the result in a table as shown in Figure B-7

Figure B-7 File triple counts

The information in this table allows you to judge whether exporting and reimporting the

data is likely to improve performanceThe column headed This chapter refers to triples

whose source is in this chapter the column headed Other chapters refers to triple whose

source is in some other chapter

Each row shows the number of triples of specific types

bull Stop triples are created when a database item is deleted Stop triples whose source is in

this chapter are removed by exporting and re-importing the data

bull Rename triples are created when a type or an entity is renamed Like stop triples rename

triples whose source is in this chapter are removed by the export process

bull A transaction start triple is created for every transaction started in this chapter

bull If the transaction has user text associated with it a transaction text triple is created as

well

bull When the transaction is successfully committed a transaction commit triple is created

The export process removes transaction triples of all three types

Memory usage summary

At the end of each statistics page there is a summary line showing the server memory

usage in the following format

Server memory 419 GB of 502 GB

Chapter file analysis


484

The first figure shows the amount of memory currently being used and the second figure

shows the total amount of memory allocated to the server process These figures are totals

for the Java Virtual Machine that the Sentences servlet is running in and so include other

memory than that used by the Sentences server

You can change the amount of memory that the Java Virtual Machine allocates to a

process by adjusting the -Xmx or the -Xms parameter on your servlet container If you

select the Custom installation option for Sentences you can set the Java memory

parameters during the installation procedure (see the Sentences Installation Guide for

more details)

You can set the Java memory parameters for server utilities such as Export and Import in

the lazystart script file (see ldquoThe lazystart script filerdquo )

If you are using Tomcat you can add the server memory specification to the

Catalinabat file (or Catalinash file for Linux Unix) which is in the Tomcat4bin

folder of your Sentences installation If you are not using Tomcat the memory parameter

should be specifiable in your servlet container See the documentation for your servlet

container for details

If you are using Tomcat you can add the line below in the section headed Verify and Set

Required Environment Variables

set JAVA_OPTS=-Xmx4096m -Xms2048m

where -Xmx specifies the maximum of memory that can eventually be used (shown here

with the example value 4096m meaning 4GB) and -Xms specifies the initial amount of

memory to be allocated at the start (shown here with the example value 2048m meaning

2GB)

Scheduled process status

Sentences will display the outcome of the currently running Scheduled Process List once

complete but until it is complete only the fact that it has started will be shown The

Statistics servlet has an option to view more granular information about which items in

the list have completed so far

To view the progress of the currently running Scheduled Process List follow these steps

1 In your browser enter the URL for your Sentences Server Statistics page with

the process query parameter

httplthostgt[ltportgt]SentencesStatisticsprocess

For example in the default installation using the Tomcat test web server

theURL will be

httplocalhost8090SentencesStatisticsprocess

2 The web page returned will either state that there is no currently running process

or will display the name of the Scheduled Process List the status (which is the

currently running item) and a list of all the items

Each item listed will state whether it has been completed or not


You can use the InspectChapter command-line tool to analyse the structure of a

chapter file and create a more detailed listing of its contents To use this tool open a

command prompt and navigate to your ltSentences_homegt directory and enter the

following command

InspectChapter ltchapter filegt ltoptiongt



485

where

ltchapter filegt is the file name of a Sentences chapter file to be analysed

ltoptiongt is a keyword specifying the information to be listed

The available keywords are described below

Keyword Description

header

Lists information from the file header including its block

size its internal identifier and the names and internal

identifiers of chapters that are referenced from within this

chapter

blockstats

Lists block statistics This is the same information as

displayed on the block statistics HTML page described

above

atoms Lists all the entity instances in the chapter by name within

entity type

atomIDs Lists all the entity instances in the chapter by ID

tripleIDs Lists all the associations in the chapter by ID

triplepages

Lists information about all the triple pages showing the

range of associations held in each one but without

listing the associations themselves

triples Lists all the triple pages in the chapter including all the

associations held in each one

rtree Lists the R-tree index used to access triple pages

The InspectChapter command does not use the ChapterPathList setting from the

Serverproperties file and does not check for the existence of the databaselock

file You must therefore use the fully-qualified path and file name for example


It is strongly recommended that you shut down the Sentences server before running this

command

Server request statistics

Sentences can record the number of requests received by the Sentences server in a text

file This file is created if you set the optional parameters StatisticsPath and

StatisticsPoll in the Serverproperties file (see ldquoStatistics propertiesrdquo )

The file created by this setting is named Statisticsxxxtxt (where xxx represents a

timestamp and the file lists the date and time of each record followed by the number of

server requests received in the previous time period

Glossary

Glossary

This glossary gives definitions of terms as they are used in Sentences

Glossary Term Description

All types folder A folder in the Sentences Explorer schema pane where all entity types are displayed

All queries folder A folder in the Sentences Explorer schema pane where all queries are displayed

applet A program written in Java for displaying data in a web browser The Sentences client for the Enterprise Edition is a Java applet that runs in a Web browser

association An association stores data about the interaction between two other things which may be entities or associations An association is an instance of an association type

association type An association type is part of the database schema and is used to define some of the attributes of the associations that are based on it

associative

model

A new model for the structure of computer databases of which Sentences is an implementation

bind In a query to force a request node to return only an instance specified in some way either a fixed instance a parameter value or the result of some other node

bound Of a request node in a query forced to return a specified instance See bind

branch In a query request tree a group of request nodes originating with one common parent node

Business Rule There are two kinds of Business rule used to prevent defined state changes or act on a state change

Change Rule A Change Rule is a Business Rule that mandates an action when it detects a change of state

chapter A logical repository within a Sentences database for schema data or query information stored on disk as a chapter file A chapter may be included in zero one or many Sentences profiles

child Dataform A second or subsequent Dataform opened from an association on another Dataform

child node In a schema or query tree a node other than the root node A child node always has only one parent node

client A device that displays data and allows user interaction but does not store data

Core types

folder

A folder in the Sentences Explorer schema pane used to display selected entity types from your schema In any profile you can choose between manual or automatic selection of entity types for this folder If you choose automatic selection then entity types are shown in the Core types folder when they are the source of an association which is itself the source of further associations

Glossary


Core queries

folder

A folder in the Sentences Explorer schema pane used to display selected queries from your schema Queries in the Core queries folder are always selected manually by the user

custom datatype A datatype defined by a user using the Sentences API and the Java programming language

Data page See Page

data pane The right-hand pane of the Sentences explorer used primarily for viewing and selecting instances and associations

data request In a query the request node at the root of the request tree

database All the data and schema information in one or more Sentences chapters that are used in a profile or a in a set of related profiles

Dataform One of the major parts of the Sentences user interface used for dynamic data viewing and data entry

datatype A way of defining certain attributes of an entity type Applying a Sentences-supplied datatype or a custom datatype to an entity type may make it a value type

Diagram Editor An editor for the basic graphical representation of database elements may also be used for exploring or documenting a schema

Diagram element A graphical representation in the Diagram Editor of an element in the Sentences database also applies to text labels and annotations

Display Name

Query

This is a type of Sentences Query that has been created to provide an alternative name for an instance

derivation A calculated value on a forward request query node that may populate or replace the target of its association

derived type In a query an operator request which specifies that new values should be created based on a calculation or other derivation from other results

drill-down The process of viewing database information by moving through the data pane or schema pane in the Sentences Explorer

DTD A Document Type Definition for an XML document

Effector Query A Sentences Update Query that is either attached to a particular State Domain State or mandated in a Change Rule in order to effect a change when that state change is detected

Enterprise

Edition

The Sentences configuration that uses a Web server and servlet container with the Sentences client running on the same machine or on a remote machine for example as a Java applet in a Web browser

entity An entity stores data about something that has an independent existence in the real world An entity is an instance of an entity type

entity type An entity type is part of the database schema and is used to define some of the attributes of the entities that are based on it

Glossary


equivalent Two types in Sentences that represent the same real world thing may be defined as equivalent types Two instances in Sentences that represent the same real world thing may be defined as equivalent instances

filter tool A tool for selecting data according to criteria entered by the user

forward request In a query a request for associations in the forward direction

GUID A Globally Unique Identifier is an identifier that can be generated automatically as an ID for an Entity

hidden node In a query a request node whose results are not included in the returned result tree A hidden node is usually included to provide data for an expression

HTML The HyperText Markup Language an international standard file format based on SGML used for hypertext documents on the World Wide Web

HTTP The Hypertext Transfer Protocol an Internet protocol based on TCPIP used to fetch hypertext documents from remote hosts on the World Wide Web

Inactive

instances

An inactive instance is one that is no longer valid to be used in new data entry but is still required for historical references An Association Type can be used to identify itrsquos sources as being invalid when an instance exists

instances A collective term for entities and associations

Internet A global network of computer networks The World Wide Web is part of the Internet

Intranet A private closed network that uses the same communications protocols as the Internet

inverse

association

An instance of an association type as referred to from its target to its source

Inverse request In a query a request for associations in the reverse direction

inverse verb The verb associated with the inverse component of an association type

items A generic term for instances and types

J2EE The Java 2 Enterprise Edition the Java standard for multi-tier enterprise applications

J2SE JRE The Java 2 Standard Edition Runtime Environment including the Java Virtual Machine Java core classes and associated resources

Java A programming language developed by Sun Microsystems Inc now owned by Oracle Sentences is written in Java

Java SDK The Java 2 Standard Edition Software Development Kit a development environment for the Java programming language

Java Web Start A Desktop application that allows Java Applets to be run outside a browser as a Desktop Application

JAR file A file in the Java Archive file format typically containing a bundle of Java class files and additional resources associated with a Java applet

Glossary


JDBC Java Database Connectivity technology provides a means of connecting from Sentences to many Relational Databases Each Database Vendor requires a JDBC Driver in the form of a JAR file

LazyView LazyView is a technology whereby one or more Relational Databases may be dynamically viewed in Sentences or a static snapshot of data may me imported A LazyView chapter defines the relational database to connect to and the mapping between the Relational Schema and the Sentences Schema

local mode A method of running the Sentences Enterprise Edition in which the Sentences server and the Web browser client are installed on the same computer

Mapping

Definition

A LazyView Mapping Definition defines how Sentences transforms the Relational Schema into the Sentences Schema using the Associative Model of Data

node A named point in a schema or query tree for example a type or instance

operator request In a query a request node that modifies the results returned by its parent

Page Schema Pages are used to organise Association Types into logical groups They are used in base dataforms to generate Dataform Tabbed Pages They are also used to generate Data Pages in the same positions in the data pane Page Nodes can be manually added in a Custom Dataform and when adding Association Types to a Custom Dataform Query the Association Type Schema Pages can be used to generate default Page Nodes

parent Dataform A Dataform opened from the Explorer from which one or more child Dataforms may be opened

parent node In a schema or query tree any node that is the parent of one or more child nodes

Personal Edition A special Sentences configuration intended for evaluation purposes only that has a Sentences client and server bundled into a single Java application

positioner tool A tool for positioning the data pane display according to criteria entered by the user

profile A selection of one or more of the chapter files which

form a Sentences database A profile also defines a collection of chapter files and how they operate together to produce a view of their combined schema query and data information

privilege A User is granted privileges to perform certain tasls by

being assigned User Roles

query A way to specify data to be extracted from the database A query can be used to return selected data from the database or to create XML output or to define a custom Dataform

Query Editor One of the major elements of the Sentences user interface used for creating queries

Glossary


query parameter In a query a value which can be supplied to modify the execution of the query in some way

recursive

closure

A query operation that follows a transitive relationship as far as it goes

request node In a query one element of a request tree

request tree In a query a structure of request nodes that a user builds to define a query

result tree In a query a data structure holding the results of a query

root The point of origin of a schema or query tree The root is always displayed at the top of the tree

Sandbox Mode A Sandbox is a term used to describe a mode of operation where any changes are only temporary and the system can revert to the state it was in prior to entering Sandbox Mode There are two types of Sandbox in Sentences Full and Data In Data Sandbox mode any schema changes will be permanent but data changes are transient In Full mode any changes to schema or data are transient

Scheduled

Process List

A list of processes that are scheduled to execute at a particular time or reglar intervals on the server

Scheduler The Sentences Server includes a Scheduler that can execute processes at regular intervals

schema The sum of the type and properties information for all data in the database

Schema page See Page

schema pane The left-hand pane of the Sentences Explorer Used for building and viewing the database schema

selection

request

In a query a request node that filters the results returned by its parent

Sentences An implementation of the Associative Model of Data written in Java by Lazysoft

Sentences Explorer

One of the major elements of the Sentences user interface Used for browsing and viewing schema and data information

sequenced Arranged in an explicitly assigned order The order can be changed only be an explicit re-sequencing action

server A device that runs programs and stores data and supplies data for display on a client in response to a request

servlet A Web server component written in Java that provides dynamic content

servlet container A Web server component written in Java that provides network services for servlets (previously known as a servlet engine)

servlet context A collection of resources associated with a servlet that can be shared which is often used as part of a URL

set query A query based on the Set Query Editor used in Sentences Version 1

Glossary


Set queries

folder

A folder in the Sentences Explorer schema pane where all Set queries are displayed This folder is only available if you have chosen to show Set queries in your profile

sort request In a query a request node that re-orders the results returned by its parent

sorted Arranged in a value determined order for example alphabetical

source An item which is the origin of an association or association type

source request In a query a request node representing the source of an inverse request

State Domain You may define State Domains for Sentences Types Each of these Domains has a set of States that instances of the Type can exist in together with an assumed ldquoundefinedrdquo State

State Rule A State rule is a Business Rule that prevents a given change of state

subset A subset is defined by a query against a superset The subset is named and appears as a new type Its members are all those instances of the superset type which match the criteria of the subset query Subsets and their supersets must both be either entity types or association types

subtype When defined as a subtype a type automatically assumes all of the association types defined with its supertype as their source or target Subtypes and their supertypes must both be either entity types or association types

supersede The supersedes command is used to replace one instance by another

superset A type from which one or more subsets is derived

supertype A type from which one or more subtypes is derived

System State

Domain

This is a State Domain that describes states internal to Sentences (such as Existence) as compared with User-defined State Domains

target An item which is the forward end-point of an association or association type

target request In a query a request node representing the target of a forward request

Transaction

Visibility

Transaction visibility is the mechanism for displaying the Sentences database at a point in time in the past

transitive

closure

A query operation that follows a transitive relationship to a specified depth but displays the results as a single level

Translation List A Translation List (in the context of LazyView) is a list of words phrases and letter combinations that should be replaced in the Relational Schema names to make more meaningful Schema names in Sentences

tree A graphical representation of a data structure in Sentences schemas and query requests and results are displayed as trees The root is always displayed at the top of the tree

Glossary


trigger Custom code that enforces rules and takes actions when the database is updated

types A collective term for entity types and association types

Update Query A Sentences Query that executes in the context of a transaction to make changes to data and perform other actions such as notifying the user and sending simple emails

URL Abbreviation for Uniform Resource Locator an address for data on the Internet or an intranet

User A Sentences database user who is assigned Roles and privileges such as the ability to Manage Sheduled Processes

User Role Sentences User Roles are defined in the User Security system to be assigned to Users in order to grant them privileges to certain functionality

value An instance of value type such as a number or a date

value type A representation of a real-world thing about which you do not need to record additional information such as numbers or dates

verb A name used to define the nature or significance of a particular association type

W3C Abbreviation for the World Wide Web Consortium an international body that develops and maintains standards for Web technology

WAR file A Web Archive file used by a Web Application Server

Web Abbreviation for the World Wide Web (WWW) a graphical part of the Internet

Web Application

Server

A Java technology-based application deployment environment for the World Wide Web

Web mode A method of running the Sentences Enterprise Edition in which the Sentences server runs on one computer and the Web browser client is installed on one or more different computers

Web Start A Java Technology that is part of the Runtime environment for launching Java Applets as Desktop Applications

XML The Extensible Markup Language a standard for structured data and documents on the Web developed by the W3C

XSL In a query a request node representing the target of a forward request

Index

A

Action attributes 386

Add a chapter 143

additional expression capabilities 325

All queries folder 121

All types folder 121

Allowing in XML 391

allowing the action attribute 391

API 402

and triggers 405

and user defined parameters 47

building and running programs 402

class hieracrchy diagram 403

class hierarchy 403

custom datacodes 409

example code 402

example program 455

introduction to 401

online documentation 402

packages 403

triggers 404

use of 389

applet

classpath 38

CLASSPATH 39

classpath argument 38

client

Sentences client 52

Dataform applet 244

Picker applet 248

Query applet 251

Senteces applet window 159

Sentences applet 21 263

Sentences applet parameters 42

using applets 110

using colour in applets 253

application suite 26 28

arithmetic operations

with date and time datatypes 313

arithmetic operators 306

example 307

assigning datatypes 190

association types 169

cardinality 171

creating verbs 108

defining source verb and target in 170

instant specific 109 219

inverse verb 170

metatype targets 238

properties 185

properties page 213

renaming 176

retrieval methods 213 216

sequencing 184

singular inverse property 171

sorting and sequencing 184

subsets 204

targets 238

associations

creating 174 237

databases

comparison with relational databases

75

display order 172

introduction to 71


associative model

comparison with relational model 74

further reading 71

available chapters 143

B

background colour

BackgroundColour parameter 247 250

XSL background colour option 360

backup

backing up and restoring data 49

backing up data 49

copying chapers for backup 51

exporting a profile for backup 51

online backup 49

base dataform 235

batch files

parameter limit 156

binding nodes 296

to an instance 296

to other nodes 297

to parameters 297

block size 146

block statistics 482

changing 158 484 485

Border parameter 247 250 253

browsing transactions 163

business rules 220

change rules 228

domains and states 221

effector query parameters 226

effector triggers 227

reference 230

state rules 227

system state domains 221

using states

in dataforms 225

in queries 225

C

can create target 212 361

can select target 212 361

canvas 394

cardinality 171

and data display 171

cascarding stylesheet 369

certificate 53

changes chapters 143

changing block size 158

changing user 149

chapter files

analysis 484

deleting 146

design considerations 109

duplicate chapter files 56

format 158

locations 136

naming 145

properties 146

statistics 480

system chapters 136

Chapters 135

add a chapter 144



chapter properties 146

commands 137

copying 158

deployment 158


export and import single chapter 159

importing

and profile visibility 156

importing 154

internal identifiers 158

new chapter 145

renaming 145

restrictions on copying chapter files 158

use in database design 109

working with chapters 144

checkbox presentation option 195

child dataform

opening from a table row 239

choosing entity association or value types

107

client API 402

example 455

use of 111

client parameters 46

client server interaction diagram 264

closure

recursive 321

transitive 319

code example

picker applet 249

collapse view 295

colours

applet colour features 253

using in Sentences applets 253

combo presentation option 195

commands

ExportChapter 159

ImportChapter 159

comparison operators 307

example 308

concatenation operator 306

conditional operator 310

configuration 22

optional parameters 43

configuration files 39

the lazystart script file 37

configuring with non-J2EE Web servers 25

contacting Technical Support 56

context menu

see shortcut menu 127

copying and pasting actions 115

core queries 121

core queries folder 121

core types 120

generate core types automatically 143

core types folder 120

behaviour 143

setting display in 187

create Dataform 235

CreateButton parameter 251

creating


custom Dataforms 241

custom help 413

entity types 164

new profile 138

parameters 323

CSS 369

CSV 255

exporting query results as 374

file structure 256

CSV Export 258

and multiple associations 375

CSV Import 255

and cardinality rules 256

example 417

on Solaris Linux or AIX 257

on Windows 257

rules 256

running command 257

with supertypes and subsets 256

CSV Import Example

adding image data 420

data targeted on associations 419

CSV Import Example

importing example files 419

preparing a profile 418

CSV Import Example

viewing imported data 419

CSV Import Example

viewing additional data 421

CSV Import Example

repeating the demonstration 422

Currency 192

international considerations 192

Currency datatype 192

custom Dataform 110

properties dialog page 208 209 210 211

212

refresh button 243

restrictions 243

selecting 243

custom datatype example 451

telecoms number 453

custom datatypes 409

API 410

import and export 411

installing 410

loading custom datatype 450

unloading custom datatype 451

custom Help

adding custom help 411

creating 412

file name and location 413

help button display 411

help mapping 412

mapping to help topics 413

precedence of help pages 412

updating help topic mappings 412

custom Help mapping

association type mapping 413

custom dataform mapping 413

entity type mapping 413

D

data

demand loading of 178

data changes 135

data changes chapter 143

data exchange 255

data items

size of 165

data models

associative 72

comparing associative and relational 74

data pane 121

features 117

icons 117

data request node 291

data request nodes

creating 291

data visibility 152

database

benefits of exporting 152

class hierarchy in 403

database lock file 55

Dataform 128 232

default export behaviour 153

design 71

assumptions for Order Entry example

433

creating verbs for association types

108

design guidelines 75

design skills 75

export

and internal identifiers 152

export and import 152

export file 153

exporting 153

importing 154

modelling 108

queries 290

views

creating using profiles and chapters

275

example 275

Dataform

appearance 265

appearance with supertypes 266

base Dataform 235

changing targets in 240

create Dataform 235

default Dataform 235

example with subsets 269

instance specific 240

labels and fields 129

parent and child Dataforms 265


shortcut menu 130 238

tabbed pages 129 232 233 234

targets that are subsets 240

targets with duplicate names 240

update dataform 236

use of 110

Dataform applet 244

colours 253

parameters 245

Dataform based updates 265

Dataform is read only 212 361

Dataform navigation

in derivations example 430

Dataform parameter 247 250

Dataform quick tour 128

Dataforms

different kinds of 128

underlined targets 239

datatype classes 450

datatype method example 313

datatypes 189

ltnonegt 190

assigning 190

changing 167

currency 192

date 193

date and time 192


default directory 27

deleting types 167

hyperlink 190 191

image 166

image 190

methods 313

mixed currency 192

number 191

numeric types 191

output style 197

percentage 192

presentation methods 193

properties 189

string types 190

text 190

time 193

timestamp 193

undefined 190

value types 167

date and time datatypes 192


date datatypes 193

date formats

presentation 199


default target 215

using expression 216

using instance 216

default value 311

DeleteButton parameter 251

deleting 174 175

impact of deleting dialog 174

profiles 144

deletion

implicit deletion 175

deployment

copying chapter files 158

deployment

exporting and importing profiles 151

derivation properties dialog 303

derivations 301

and XML import 386

calculation settings 303

example 422


recalculation rules 302

setting 304

derivations example 422

base and custom Dataform 424

design assumptions 433

importing order entry profile 423

order entry query 428

page nodes 429

setting dataform navigation 430

derived type node

expressions 304

properties dialog 300

derived type properties 300

derived types and derivations 299

description 207

design

associative database 71

database design 71 75

design for change 108

skills 75

diagram editor

adding query results 398

canvas 394

components 393

consistency with explorer 397

menus 475

preferences 394

starting 393

toolbar 394

diagram elements

adding 396

deleting 397

selecting 397

diagrams 393

export 398

import 398

printing 398

saving as a GIF file 398

display

refreshing 160

display height 198

display in place editing 196

display name queries 351

creating 351

in Sentences 352

display options 123

display order of instances 159

display width 198

DisplayStatus parameter 247 250 253

divider bar 123

in query editor 134

document conventions 19

documentation directory 27

drill down 118

DTD 377

create a DTD from a query 370

parameter 384

servlet access 381

DTD reference 369

duplicate instances are not allowed 172 187

E

edit profile dialog 142

editions 21

EditOption parameter 246


creating 227

element identifiers 368

element IDs parameter 385

elements

in XML 378

ellipsis button 130

EnablePickers parameter 247

enterprise edition 21

entities 164

creating 165

introduction to 71

size of 165

entities and associations 71

entities and values 73

entity types 164

creating 164

naming rules 165

properties 185

renaming 176

equivalence 206 218

defining 201 206

error messages 54

client must be loaded from same host as

its HTML page 57

database not available 55 56

Error 1222 54

Error 1265 54

Error 1266 55

Error 1267 55

Error 1268 56

Error 1272 56

Error 1403 57

errors reported at the Sentences client 54

server connection expired 54

example custom datatype

use of 451

example trigger classes 434

disabling 449

examples

chapter directory 27

client API example 455

CSV Import example 417


directory 27

integration with MS Office applications

458

trigger examples 434

worked examples 416

exists() conditional function 311

example 311

expand and collapse node buttons 118

expand view 295

explorer 114

data pane 121

deleting 174

display options 123

divider bar 123

drill down 118

menu bar 114

shortcut keys 123

shortcut menu 127

status bar 122

tabs 118

toolbar 115

tooltips 116

export

and triggers 409

databases 152

diagrams 398

options 153

single chapter 158 484 485

troubleshooting 157

export and import


ExportChapter command 159

expression editor 336

expression syntax

for queries 305

expressions



concatenation operators 306

creating 338

datatype methods 313

deleting 340

editor 336

exists() function 311

group functions 312

in queries 304

logical connectives 309

nested 341

results 315

syntax 305

type constructors 315

wildcards 308

Extensible Stylesheet Language (XSL) 378

external formats 255

F

feedback 20

file URL prefix 191

filter tool 181

pattern matching 181

finding data 116 120 178

ForegroundColour parameter 248 250

format

display height 198

display width 198

format options 198

picker 196

presentation 194

read only on dataform 198

style 196

table column width 198

XML query output options 368 379

function editor 336

function keys

Dataform 472

Diagram Editor 476

Explorer 472

Query Editor 474

functions

deleting 341

editing 336 339

nested 341

unwrapping 340

wrapping 340

G


group functions 312

example 313

grouping results 349

H

hidden in Dataform tables 198

hidden on Dataform 198

hide

hide nodes in queries 318

how to use this guide 19

http URL prefix 191

Human Resources example application 416

employee entity type 416

group company entity type 417

project entity type 417

hyperlink datatype 190 191

I

icons 116

in query editor 132

identifiers

in query expressions 315

image datatype 190

ImageURLBase parameter 36 247 250



import

and triggers 409

database 152

diagrams 398

from earlier versions 156

options 155


XML data 381

ImportChapter command 159

installation 17

installation directories 25

instance equivalence 218

instance options 172 187

instance specific association types 109 219

instances

creating in the Dataform 239

deleting 174

display order of 159

introduction to 73

names created by trigger 188

operations on 217

visibility 168

instances are values 189

instances may not be created 172 187

instances may not be deleted 172 187

instances may not be renamed 187


creating mail merge emails 460

creating mail merge letters 458

creating Outlook contacts 462

creating Sentences data from an Outlook

contacts folder 465 467

internal identifiers

Chapter UID 146

displaying 123

renaming 176





delayed display 159

inverse verb 170

iterative design 108

J

J2SE JRE 53

Java 53

J2SE JRE 53

Java console tool 54

on Solaris and Linux systems 53 54

on Windows systems 54

Java runtime environment 53

Sentences and Java 263

Java plug in security warning 54

Java server pages 110

JSPs 110

K

key features 17

keys

not used in Sentences 74

L


layout

XSL layout options 357

LazyId parameter 247

LazyID parameter 251

LazyInstance parameter 251


LazyQuery parameter 253

LazyType parameter 246 250

licenses directory 28

licensing 22

list presentation option 195

localisation 414

application text 415

example messages file 415

messages file location 415

messages file name 415

messages property file 414

system text 414

locating data 178

positioner and filter tools 179

log files 52


behaviour with missing values 309

example 309

M

mailto URL prefix 191

mapping XML data 386

memory usage summary 483

menu bar

explorer 114

query editor 132

menus

diagram editor 475

explorer menus summary 469

query menus summary 473

shortcut menus 127

message log 134

message statistics 478

messages 134

messagesproperties 414

metaschemechap 26

metatypes 174 238

mixedcurrency datatype 192

modelling 107

common behaviours 109

one to many association types 108

morehellip prompt 178

multi-line edit presentation option 195

multi-line label on Dataform 199

multiple instances

sequencing 185

multiple line presentation option 195

multiple profiles 275 277 283

multi-user environments

XML import 385

N

naming

parameters 323

new chapter 145

new features 18

new profile

creating 138

new profile wizard 138

node names for XML output 370

nodes 116

and icons 116

binding 296

none datatype 190

none datatype 167

number datatype 191

O

online backup 49

preparation 49

restoring data 50

online backup using the command 50

open profile dialog 138

operations on instances 217

operator request nodes 297

options dialog 123

order entry example

picker applet 432

outlook URL prefix 191

Output Format parameter 384

overview 17

P

page nodes 354

added automatically 354

adding 354

Dataform display nodes 354

in derivation example 429

using 354

parameters

BackgroundColour 247 250

Border 247 250 253


CreateButton 251

creating 323

Dataform 247 250

defining 324

defining type 324

defining value 324

DeleteButton 251

DisplayStatus 247 250 253

EditOption 246 250

EnablePickers 247 250

ForegroundColour 248 250

ImageURLBase 247 250

LazyID 247 251

LazyInstance 246 251

LazyQuery 253

LazyType 246 250

mandatory 324

maximum number in Windows batch files

156

naming 323

Picker 251

Picker Applet Parameters 250

Profile 246 250 253 325

Query applet parameters 253

query parameters 323

RequestSize 247

SaveButtonText 247 251

ServletContext 245 250 253

ServletPort 43 245 250 253

ShowTitle 251

Target 253

use in query expressions 311

viewing in Explorer 325

parent and child dataforms 237

parent dataforms 265

password

changing your password 148

for chapter files 57

percentage datatype 192

personal edition 21

Picker applet 248

code example 249

parameters 250

using colours 253

Picker applet example

use of 432

picker lists 130 240

displaying in the Dataform 237

picker type selection 196

Picker parameter 251


using togethert 182

positioner tool 180

preferences

diagram editor 394

presentation 194

presentation methods for datatypes 195

presentation options

checkbox 195

combo 195


list 195

multiple line 195

radio button 195

single line 195

table for associations 196

table for targets 196

tree 195

printing

diagrams 398

printing page breaks

XSL printing page breaks option 360

Profile parameter 250 253

profiles 135

commands 137

creating 138

deleting 144


editing 142

editing profile dialog 142

export command switches 153

export command troubleshooting 157

import command switches 155

opening 138

renaming 143

saving 144

the profiles profile 136

using multiple profiles 137

visibility of imported profiles 155

profiles and chapters

constraints 137

profiles database 136

export using XML 156

import using XML 156

transferring 156

profileschap 26

properties 185



Custom Dataform 208 209 210 211 212

datatype properties 189

default target 215

description 207

equivalence 206

general 186

query properties

Dataform properties 360

derivation properties 303


general properties 290

query node properties 355

XML properties 367

XSL stylesheet properties 357


subets 202

subsets 200 201 202

target parameters 214

transitive closure node properties 362


association type page 213

datatype properties page 189

description properties page 207

equivalence properties page 206

format properties page 194

general properties page 186

subset properties page 200 201 202

supertypes properties page 205

target parameters properties page 214

triggers properties page 206

prototyping 108

Q

queries 287

creating 288

creating a new query 288

derived type nodes 299

description 290

display name 351

displaying 294

editing 289

executing queries with parameters 324

execution process 325

expression syntax 305

hidden nodes 318

navigation 212 361

no results 295


output format 368

parameters 323

recursive closure 319

renaming nodes 317

request tree 290

required nodes 316

result trees 294

saving 289

selection nodes 298

sort nodes 299

transitive closure 319

update 343

XML properties 367

Query applet 42 251

code example 252

colours 253

parameters 253

query changes chapter 143

Query Editor

and Dataforms 353

and XML 362 367

availability 288

divider bar 134

drag and drop cut copy paste 293

icons 132

introduction 287

menu bar 132

menus 473

query pane 133

quick tour 131

results pane 133

schema pane 133

starting 288

status bar 133

stop button 295

toolbar 132

use with XML 381

user interface 289

window 289

XML options 392

query expression examples




conditional operators 310

datatype methods

currency and mixed currency 314

date and time 313

text string methods 314

exists conditional function 311

group functions 312



user defined parameters 312

void 310

wildcards 308

query expressions



default value 311

identifiers 315

missing values 316

syntax 305

using conditionals to check for parameter

values 312

using parameters 311

using void 310

zero token given as result 316

query node dataform properties


dataform is read only 212 361

interaction between properties 212 361

query node properties dialog

format page 356

query nodes

adding 292

query pane 133

query results

adding to diagram editor 398

displaying 294

displaying in Explorer 295

export as CSV data 374

export as XML 371

view as XML 372

query shortcut menu

add options 292

R

radio button presentation option 195


recalculation

rules for derivations 302

recursive closure 319 321

referential integrity 175

refresh button

on custom dataforms 243

refreshing the display 160

relational and associative model comparison

74

relational databases

access with LazyView 76

relational model

in comparison with associative model 74

rename

rename a chapter 145

renaming

nodes 317

renaming 176

renaming a profile 143

request tree

in queries 290

RequestSize parameter 247

required nodes 316

resources directory 28

restarting the Sentences server 47

restore


restore default settings 199

restoring data 49

result trees 294

results

grouping 349

results pane 133

retrieval options 213 216

right align in dataform fields 199

right align in dataform tables 199

running CSV import 257

S

Salary Update example

use of 455

sandbox modes 161

access 161

changing 161

SAP Crystal Reports 350

SaveButtonText parameter 251


saving

saving a profile 144

schema

export to XML 379

schema changes 135

schema changes chapter 143

schema diagram

a simple association 71

an associative schema 74

more complex association 72

target parameters schema 270

schema pane

description 119

features 117

icons 117

in the query editor 133

schema pane 133

schema visibility 152

scroll bars 122

searching for data 178

security 57 148


checking HTML page host 57

user security 148

using database views 57

selection nodes 298

and expressions 304

Sentences

and Java 263

and XML 377

configuration 22


database design 107

diagrams 393

licensing 22

log files 52

queries 288

security 57

transactions 264

uninstall 69

user interface design options 109

user interface options 109

XML conventions 389

Sentences API 401


parameters 42

Sentences client 21 52

starting 52

Sentences editions 21

Sentences Explorer 159

drill-down 118

quick tour 114

tabs 118

tooltips 116

updates 264

use of 110

Sentences IDs parameter 385

Sentences server 21

shutting down and restarting 47

stopping data retrieval 183

sentences_chapters 26

sentences_home 27

sentences_images 26 27

sequencing 184


multiple instances 185

server

statistics 477

server activity

monitoring 47

Server API 402

server request statistics

statistics

server requests 484 485

server side triggers 258 260 261 404

servlet access to Sentences 67

ServletContext parameter 245 250 253

ServletPort parameter 43 245 250 253

servlets

access to Sentences features using 67

available in Sentences 67

enabling and disabling 69

for access to XML 382

use to a DTD 381

use with XML 381

set queries 287

visiblity 152

shortcut keys 123

shortcut menus 127

Dataform 130

show grid

XSL show grid option 360

show separator

XSL show separator option 360

ShowTitle parameter 251

single line presentation option 195

singular inverse 171

size of entity and value instances 165

sort nodes 299

sorting 184

source 170

spatial view 481

statistics

chapter statistics 480

memory usage 483


open profile statistics 478

open profiles 478

summary page 481

viewing 477

status bar 122

Query Editor 133

stop button 183

in Query Editor 295


in Query Editor 295

string datatype 190

strings 314

style 196

stylesheet parameter 383

stylesheet processing 385

stylesheets directory 28

subset queries

attaching to subsets 325

subsets 109 200 201 202

and Dataform 265

create 203

ordering 265

properties 202

properties dialog page 200 201 202

properties page 202

subset queries 325

used as targets 239

viewing subset instances 204

subsets and supertypes

comparison 203

dataform behaviour 204

ordering 265

using to design Dataform 265

supersedes 218

supertype

defining 205

supertypes 109

and Dataform 266

properties dialog page 205

properties page 205

using with association types 206

support information 125

symmetric 172

system chapters 26 136

T

tabbed pages

on dataform 129




target 170

Target parameter 253


allowed products example 274

conference room example 271

limitations 275 277 278 283 284

properties page 214

targets

and subsets 240

with duplicate names 240

technical support

contacting 56

text datatype 190

time formats

presentation 199

tomcat

diagram editor 393

explorer 115

home directory 28

sentences directory 29

web applications directory 28

toolbar

query editor 132

tooltips 116

trace files 51

trace level settings 51

transaction processing 264

transaction visibility 162

transactions

browing 162

browsing 163

transactions

Explorer based updates 264

transactions

in Sentences 264

transactions




tree displays 116

tree displays in Sentences 113

tree presentation option 195

trigger examples

auto-number example 442

email address example 439

refuse update 436

triggers 206 404

actions 408

and the Sentences API 405


attaching 405

calling 408

creating instance names 188

customised validation 408

examples 405

installing 405

invocation 408

loading example triggers 434


rules 408

threading 408

trigger actions 409

using with import 255

using with import and export 409

viewing enabled triggers 435

XML import 386

triggers directory 29

triple counts 483


example 315

type properties 185

types

and instances 73

deleting 174

introduction to 73

typographical conventions 19

U

undefined datatype 190


uninstaller directory 29

uninstalling Sentences 69

update Dataform 235

update queries 343

updating changes 135

URL

using a URL with a hyperlink datatype

190 191

user

changing user 149

preferences 149


and the client API 47

and triggers 47

format 46

how to refer to 47

pre-defined names 47


user parameters 47

user interface

explorer 114

introduction 113

options 109

Query Editor 131

schema pane 119

the Dataform 128

user preferences 149

user security 148

V

valid XML 377

value types 166

and datatypes 166

behaviour 168

creating 166

values

behaviour 168

creating 169

introduction to 73

size of 165

visibility 168

verb 170

virtual directories 36

visibility

of instances 168

of schema and data 152

W

web security 57 68

whatrsquos new 18

wildcards 308

example 308

X

XML 378

action attributes 386

associations appear as child elements 389

attributes 378

combining simple elements 391

conventions 389

data input and output methods 380

derived element type names 390

DTD 377

DTD parameter 384

elementIDs parameter 385

elements 378

export Sentences schema 379

export using command line 387

import and derivations 386

import and triggers 386

import in multi user environments 386

import using a servlet 385

import using command line 388

import XML data 381

including sentences IDs 391

introduction to 377


mixed content is not allowed 390

online importing 388

output format parameter 384

output options 368

output options for schema export 379

380


query properties 367

SentencesID parameter 385

servlet access 382

servlet parameters 382

setting options in Query editor 392

split multiple lines 390



terminology 377

use content not attributes 389

using alternative parsers 389

using command line tools 387

using element IDs 391

using servlets 381

using the API 388

using the Query editor 381

valid XML 377

well formed 377

XML based user interface 111

XSL

background colour option 360

export stylesheet 371

generated stylesheet 369

layout options 357

no (none) stylesheet 369

printing page breaks option 360

show grid option 360

show separator option 360

stylesheet 357

stylesheet from server 369

stylesheet from URL 370

stylesheet options 368

stylesheet properties 357

tablexsl example 374

XSLT 378

Y

your comments 20

A publication of Lazysoft Ltd

Web wwwsentencescom

Email supportsentencescom

Copyright copy 2000-2014 Lazysoft Ltd All rights reserved

The information in this document is subject to change without notice and does not represent a

commitment on the part of Lazysoft Ltd No part of this document may be reproduced stored or

transmitted in any form or by any means electronic or mechanical for any purpose without the

express written permission of Lazysoft Ltd

The software described in this document is supplied subject to a License Agreement and all use

of the software is subject to the terms of the agreement Lazysoft Ltd accepts no liability for any

damages incurred directly or indirectly from any errors omissions or discrepancies between the

software and the information contained in this document

Sentences is a registered trademark of Lazysoft Ltd

LazyView is a trademark of Lazysoft Ltd

IBM AS400 DB2 DB2 Universal iSeries pSeries xSeries zSeries Lotus and WebSphere are

registered trademarks of International Business Machines IBM Corporation

Microsoft Windows Windows XP Windows Vista Windows 7 SQL Server Internet

Information Server (IIS) Internet Explorer Microsoft Office Microsoft Word Microsoft Excel

Microsoft Outlook Microsoft Sharepoint and Microsoft Access are trademarks or registered

trademarks of Microsoft Corporation

Oracle and Java are registered trademarks of Oracle Corporation andor its affiliates

Adobe the Adobe logo PostScript and the PostScript logo are either registered trademarks or

trademarks of Adobe Systems Incorporated in the United States andor other countries

The Tomcat Web server redistributed with Sentences and the Xalan XSLT Stylesheet Processor

and the Xerces XML Parser incorporated in Sentences were developed by the Apache Software

Foundation (httpwwwapacheorg) Copyright copy 1999-2000 The Apache Software Foundation

All rights reserved Please see the accompanying text files in the Licenses subdirectory for full

details of the copyright and warranty limitations for Apache Software Foundation products

InstallAnywhere is a registered trademark of Flexera Software Ltd

Linux is a registered trademark of Linus Torvalds

SAP Crystal Reports is a registered trademark of SAP AG in Germany and other countries

All other product names used may be trademarks or registered trademarks of their respective

owners

Document Information

Last Updated September 2014 ndash Build 191

Table of Contents

Overview 17

Introducing Sentences 17 Key features 17 Whats new in Sentences Version 40 18 How to use this guide 19

Document conventions 19 Your comments 20

Chapter 1 21

Configuring Sentences 21

Sentences editions and components 21 Additional components 21

Sentences licensing 22

Configuration files 22 Personal Edition environments 22 Enterprise Edition evaluation and testing environments 22

Security 24 Enterprise Edition production environments 24 Web servers not using Java Enterprise standards 25 Sentences installation directories 25 Server properties 29 Virtual directories 36 About the ImageURLBase parameter 36 Support for configuring other environments 37 Configuring server utilities 37

The lazystart script file 37 Using the classpath argument 38 Sentences client configuration 39

Java Runtime Environment 39 Java browser plugins 39 Javascript helper library lazyDeployJavajs 40 Applet configuration 40 Sentences applet parameters 42 Additional optional parameters 43 Web Start Configuration 44

User-defined parameters 46 Format of user-defined parameters 46 Pre-defined names 47 User Parameters 47 Referring to user-defined parameters 47 User-defined parameters in the Client API 47 User-defined parameters in triggers 47 User-defined parameters in query expressions 47

Monitoring server activity 47 Shutting down and restarting the Sentences server 47 Backing up and restoring your data 49

Online backup 49 Preparing to run online backup 49 Using the online backup command 50 Restoring your data from an online backup 50 Exporting the database for backup 51 Copying chapters for backup 51

Using trace files 51 Sentences log files 52

Running the Sentences client 52 Starting the Sentences client 52 Java Runtime Environment Plug-in 53 Security and certificate acceptance 53 Using the Java Console tool 54

Activating the Java Console on Windows systems 54 Activating the Java Console on Unix Linux systems 54

Errors reported at the Sentences client 54 Contacting Technical Support 56

Security considerations 57 Automatic check of HTML page host 57 Using database views for enhanced security 57

Sentences user security reference 57 Users and roles 57

Anonymous access to Sentences 59 Creating a new role 59 Creating a new user 62 Resetting a locked user 63

System Administrator Lockout 63 Privileges 64

Combining chapters example 65 The current user 65 Combining chapters example continued 66

User security parameters 66 The Serverproperties file 66 Client properties 66

Servlet access to Sentences 67 URL patterns and Servlets available in Sentences 67 Sentences servlets and web server security 68 Enabling and disabling servlet access 69

Uninstalling Sentences 69

Chapter 2 71

Introducing the associative model 71

Entities and associations 71 Entities and values 73

Types and instances 73 Comparing the relational model and the associative model 74

Structural comparisons 75

LazyView - Using Sentences to view relational databases 76 LazyView chapters 76 Relational schema and Sentences schema 76 Representing relational structures in Sentences 76

Relational tables and columns 76 Views 77 Tables and views with no primary key 77 Tables with a foreign key 78 Defining your own foreign keys 79 Tables with composite keys 80 Tables with self-referencing columns 80 Tables representing subtypes 80 Tables representing additional information 80

LazyView chapter setup 81 Installing a JDBC driver 81 Indexing the relational database 81 Java memory and stack requirements 81 Adding a LazyView chapter to a profile 81

Dynamic and static LazyView chapters 82 Optional connection properties 83 Using an existing LazyView chapter 83 Copying an existing LazyView chapter 83

Creating a mapping definition 84 Select tables and columns 85 SubsetSubtype choices 87 New and existing Sentences schema conflicts 87 Filtering mappings 89 Resolving conflicts 89 Summary of schema to generate 91 Processinghellip 92

Creating and Editing Translation Lists 93 Creating a new Translation List 93 Editing a Translation List 94

Importing or updating static data 95 Recorded updates 97 Selecting date columns to limit incremental data updates 98 Creating and assigning limiting queries for a data import 98 Memory requirements and timeouts 100

Combining databases 100 Making entity types equivalent 100 Display name queries 100

Viewing existing definitions 101 Checking for schema changes 101

Using LazyView to view data 101 Performance 101 Large database fields 102

LazyView Query Optimisation 102 Optimisation Queries 102

LazyView reference 104 LazyView parameters in the Serverproperties file 104

Chapter 3 107

Sentences database design 107

Database modelling in Sentences 107 Database design skills 107 Choosing entity association or value types 107 Creating verbs for association types 108 Modelling one-to-many association types 108 Iterative design and prototyping 108 Designing for change 108 Modelling behaviour common to multiple types 109 Using instance-specific association types 109 Using chapters and profiles 109

Sentences user interface design options 109 Using the Sentences Explorer and Dataform interface 110 Using custom Dataforms 110 Using applets in HTML pages and using JSPs 110 Using an XML-based user interface 111 Using the Sentences client API 111 Using the Sentences HTML5 Interface 111

Chapter 4 113

The Sentences Quick Tour 113

About tree displays in Sentences 113

The Sentences Explorer quick tour 114 The Explorer Menu bar 114

The Explorer Toolbar 115 Copying and Pasting 115 Finding data 116 Sentences Explorer tooltips 116 Tree displays in the Sentences Explorer 116 Nodes and icons 116 Schema and data pane features 117 Schema and data pane icons 117 Expand node and collapse node buttons 118 Sentences Explorer drill-down 118 Sentences Explorer tabs 118 The schema pane 119 Finding schema 120 The Core types folder 120 The Core queries folder 121 The All types folder 121 The All queries folder 121 The data and properties pane 121 The Status bar 122 Divider bar 123 Shortcut keys 123 Display Session Options 123 Support information 125 Explorer shortcut menus 127

The Dataform quick tour 128 Different kinds of Dataform 128 Title bar 129 Dataform tabbed pages 129 Labels and fields 129 Ellipsis button and picker lists 130 Dataform shortcut menus 130

The Query Editor quick tour 131 Query Editor menu bar 132 Query Editor toolbar 132 Query Editor icons 132 Query pane 133 Schema pane 133 Results pane 133 Query Editor status bar 133 Query Editor divider bars 134

The Message Log 134

Chapter 5 135

Working with Sentences 135

Profiles and chapters 135 Data and schema updates 135 Chapter file locations 136 System chapters 136 The Profiles database and the Profiles profile 136 Using multiple profiles 137 Profile and chapter commands 137 Profile and chapter constraints 137 The Open Profile dialog 138 Creating a new profile 138 Creating a new profile with the profile wizard 138 The Edit Profile dialog 142 Using the Edit Profile dialog 142

Chapters 143 Changes chapters 143 Generate Core types automatically 143 Determine if child associations are present 143 Saving a profile 144 Deleting a profile 144 Working with chapters 144 Add chapter 144 New chapter 145 Naming chapter files 145 Rename 145 Properties 146 Checking chapters used for changes 146 Deleting a chapter 146 Password-protected chapter files 146 To set a password 146 To change a password 147 To delete a password 147 To enter a password 147 Password-protected files and the Personal Edition 148

Sentences user security 148 Logging into Sentences 148 Changing your password 148 Changing to a different user 149 User Preferences 149

Available User Preferences 149

Deploying profiles and chapters 151 Schema and data visibility 152 Exporting and importing databases 152 Benefits of exporting a database 152 Database export and internal identifiers 152 Default export behaviour 153 To export a database 153 Export command option switch 153 To import a set of chapters 154 Import command option switches 155 Visibility of imported profiles 155 Visibility of imported profiles using the -renumber option 156 Limitation on parameters with Import command on Windows 156 Importing a database export file from a previous version 156 Transferring the profiles database 156 Export command troubleshooting 157 Copying chapter files 158 Restrictions on copying chapter files 158 Chapter format 158 Changing chapter file block size (single chapter export and import) 158 ExportChapter command 159 ImportChapter command 159

Using the Sentences Explorer 159 Delayed display of inverse associations 159 Display order of instances 159 Refreshing the display 160 Determining if child associations are present 160 Hiding the data pane 160 Sandbox Modes 161 Transaction Visibility 162 Browsing transactions 163

Database components 164 Entity types and entities 164 Creating entity types 164 Creating entities 165 Size of entity and value instances 165 Value types and datatypes 166 Defining value types with datatypes 167 Impact of changing a datatype 167 Visibility of value instances 168 Behaviour of value types and values 168 Creating value instances 169 Association types and associations 169 Creating association types 169 Schema and data change visibility 169 Source verb and target 170 Source 170 Verb 170 Target 170 Inverse verb 170 Page 171 Cardinality 171 Cardinality rules and data display 171 Singular inverse 171 Symmetric 172 Display ordering 172 Instance options 172 Schema Pages 172 Metatypes 174 Using metatypes 174 Creating associations 174 Deleting types and instances 174 Impact of deleting dialog 174 Implicit deletion 175 Renaming types and instances 176 Inactive Instances 176

Locating data in the Sentences Explorer 178 Demand loading of data 178 The More prompt 178 The Positioner and Filter tools 179 The Positioner tool 180 The Filter tool 181 Pattern matching with the Filter tool 181 Using Filtering and Positioning tools together 182 Reloading data 183 Stopping data retrieval 183 The Stop button 183 Sorting and sequencing 184 Sequencing association types 184 Sequencing multiple instances 185

Properties 185 General properties page 186

Display in Core types folder 187 Instance options 187 Instance name creation options 187

Datatype properties page 189 Instances are values 189 Assigning datatypes 190

String datatypes 190 Numeric datatypes 191 International considerations for the currency datatype 192 Date and time datatypes 192 International considerations for date and time datatypes 193

Format properties page 194 Presentation 194 Picker 196 Style 196 Display width 198 Table column width 198 Display height 198 Format options 198 Presentation of date formats 199 Presentation of time formats 199 Restore Default settings button 199

Presentation properties page 200 Display Name Query properties page 201 Subsets properties page 202

Comparison of subsets and supertypes 203 Dataform behaviour with subsets and supertypes 204 Subsets of association types 204 Viewing subset type instances 204

Supertypes properties page 205 Using supertypes with association types 206

Equivalence properties page 206 Triggers properties page 206 Description properties page 207 Custom Dataform properties page 208 State Domains properties page 209 Business Rules properties page 209 Diagram Images properties page 210 Default Sorting properties page 211 Dataform (Navigation) properties page 212 Dataform Filter properties page 213 Retrieval Methods properties page 213 Association Type properties page 213 Target Parameters properties page 214 Derived target properties page 215 Retrieval Methods properties page 216 Operations on instances 217

Supersedes 218 Instance equivalence 218 Instance-specific association types 219

Business rules 220 Introduction 220 Domains and states 221 Effector queries 226 Effector query parameters 226 Effector triggers 227 Business rules 227 Business rules reference 230 Browsing state domains 231 Browsing business rules 231

The Sentences Dataform 232 Dataform Layout Systems 232 Dataform Page Layout System 232

Dataform Section Layout System 233 Dataform Field Formatting 234 The base Dataform and the default Dataform 235 Create and update Dataforms 235 The create Dataform 235 The update Dataform 236 Parent Dataforms and child Dataforms 237 Creating an association in the Dataform 237 Association type targets and metatype targets 238 Dataform shortcut menu 238 Selecting targets in the Dataform 239 Creating an entity instance in the Dataform 239 Targets with duplicate names 240 Targets that are subsets 240 Changing the target in a Dataform 240 Instance specific Dataforms 240 Picker list initial selection 240 Business rules and states 241 Display names 241 Table and list buttons 241 Creating a custom Dataform 241 Refresh button on custom Dataforms 243 Custom Dataform restrictions 243 Selecting a custom Dataform 243 Custom Dataforms with subsets and supertypes 244

The Dataform applet 244 Dataform applet code example 245 Applet parameters for the Dataform applet 245

The Picker applet 248 Picker applet code example 249 Applet parameters for the Picker applet 250

The Query applet 251 Query applet code example 252 Applet parameters for the Query applet 253

Using colours in Sentences applets 253 Sentences and external formats 255

Using triggers when you import data 255 CSV Import 255 CSV Import and supertypes and subsets 256 Structure of CSV files 256 CSV Import rules 256 Cardinality rules and triggers with CSV import 257 Running CSV Import 257 To import a CSV file on Windows platforms 257 To import a CSV file on Unix Linux platforms 257 CSV Export 258

Server Process Scheduler 258 Access to the Scheduler 258

Scheduled Process Lists 258 Server Processes 258

Execute Query Process 259 Set Entity Type Name Creation Seed Process 259 Update Static LazyView Data Process 259 Replace Data Chapter Process 260 Backup Database Process 260

Schedule Plans 260

Managing Scheduled Process Lists 261 Manually running a Scheduled Process List 261 Viewing Scheduled Process List Progress 261

Chapter 6 263

Advanced techniques 263

Sentences and Java technology 263 Transaction processing in Sentences 264

Sentences Explorer based updates 264 Dataform based updates 265 Updates in parent and child Dataforms 265

Dataform tabbed pages with subsets and supertypes 265 Dataform appearance with Supertypes 266 Dataform example with Subsets 269

Target parameters 270 Conference room example 271 Allowed products example 274 Limitations of the Target Parameters mechanism 275

Creating database views using profiles and chapters 275 Database views example 275

Creating Candidate Lists 277 Item Candidates 277 Value Candidates 278

Filtering Dataform Tables 283 Limitations 283

Server Text Documents 283 Configuration 284

Chapter 7 287

Sentences queries 287

Introducing the Query Editor 287 New in version 4 287 Starting the Query Editor 288 The Query Editor window 289 General query properties dialog 290 Database queries 290 Building the request tree 290 Binding Nodes 296 Selection Sort and Derived type nodes 297 Derived types and derivations 299 Specific derived type targets 304 Using expressions in queries 304 Required nodes 316 Renaming request nodes 317 Hidden Nodes 318 Transitive closure and recursive closure 319 Query Parameters 323 Attaching Subset Queries 325 Using parameters in subset queries 325 Sentences query execution process 325 Additional expression capabilities 325 The expression and function editors 336 Update Queries 343

Creating and deleting instances 343 Firing triggers 345 Requesting a state change 346 Adding a message action 346

Adding an email action 347 Grouping instances 348 Sandbox mode 348

Grouping results 349 Reporting using SAP Crystal Reports 350

Display name queries 351 Creating a display name query 351 Display names in Sentences 352

Custom Dataforms 353 Page Nodes 354 Query node Properties dialog 355

Statistics and Graphical Output 362 Adding statistics to your query 362 Making your query into an X-Y chart 363 Making your query into a pie chart 364 Making your query into a distribution chart 365

The Query Editor and XML 367 XML properties dialog 367 Node name considerations for XML output 370 Create an XML DTD from a query 370 Export query results as XML 371 Export XSL stylesheet 371 View query results as XML 372 Example stylesheets 372

Exporting query results as CSV data 374 Running CSV Export 374

Chapter 8 377

Sentences and XML 377

Introducing XML 377 XML Terminology 377

XML Support in Sentences 378 Export Sentences schema to XML 379 XML data input and output methods 380

Using the Query Editor 381 Using Servlets 381 Using command line tools 387 Using the Sentences API 388

Sentences XML conventions 389 Use content not attributes 389 Associations appear as child elements 389 Mixed content is not allowed 390 Derived element type names 390 Split multiple lines 390 Allow the action attribute 391 Include Sentences IDs 391 Combining simple elements 391 Using Element IDs 391

Setting XML options in the Query Editor 392

Chapter 9 393

Sentences diagrams 393

The Diagram Editor 393 Diagram Editor components 393 Diagram Editor preferences 394 Diagram elements 396 Diagram element types 396

Adding diagram elements 396 Deleting diagram elements 397 Moving diagram elements 397 Consistency with Sentences Explorer 397 Adding Query Results 398

Exporting and importing diagrams 398 Printing 398

Chapter 10 401

Customising Sentences 401

Sentences API overview 401 Sentences API 401 Comparing the Sentences Client API and Server API 402 Example code and online documentation 402 Program build and execution 402 API packages 403 Class hierarchy 403

Triggers 404 Server-side triggers 404 Triggers and the Sentences API 405 Installing a trigger 405 Attaching a trigger 405 Trigger threading issues 408 Trigger invocation 408 Trigger actions 408 Customised validation (rules) 408 Customised actions 409 Using triggers with import and export 409

Custom datatypes API 409 Custom datatypes API 410 Installing a custom datatype 410 Custom datatypes and import and export 411 Removing custom datatypes 411

Adding custom Help topic pages 411 Help button display 411 Creating Help topic pages 412 Creating a Help topic mapping file 412

Localisation notes 414 Localising Sentences system text 414 Translating Sentences application text 415

Chapter 11 416

Worked examples 416

The Human resources example application 416 The Employee entity type 416 The Group company entity type 417 The Project entity type 417

CSV Import example 417 Preparing a profile for the example CSV Import 418 Importing the example CSV files 419 Viewing the imported data 419 Adding image data 420 Viewing additional data 421 Restoring the original Human Resources profile 422 Repeating the CSV Import example 422

Derivations example 422 Setting up the Order Entry example application 423

Starting the Order Entry example application 423 Order Entry base Dataform and custom Dataform 424 The Order Entry query 428 The Picker applet for the Order Entry example 432 Using the Picker applet to enter and update orders 432 Design assumptions used in the Order Entry example application 433 Restoring the original Human Resources profile 434

Trigger examples 434 Example trigger classes 434 Loading the example triggers 434 Viewing enabled triggers 435 Attaching triggers and editing trigger assignments 435 Refuse Update trigger example 436 Email Address trigger example 439 Auto Number trigger example 442 Disabling the example triggers 449

Custom datatype example 450 About datatype classes 450 Loading the custom datatype example 450 Custom datatype example TelecomsNumber 451 Using the example custom datatype 451

Client API example 455 Preparing to run the demonstration 455 Using the Salary Update example 455 Enabling Sentences Client API connections 456 Setting up the demonstration profile 456 Creating a command file 456 Demonstrating the Salary Update example 457 Restoring the original Human Resources example application 458

Integration with Microsoft Office applications 458 Creating Mail merge letters from Sentences data 458 Creating Mail merge emails from Sentences data 460 Creating Microsoft Outlook Contacts from Sentences data 462 Creating Sentences data from an Outlook Contacts folder 465 Copying Excel Data to and from Sentences 467

Integration with Crystal Reports 467

Appendix A 469

Menus and Commands summary 469

Sentences Explorer menus 469 Sentences Explorer function keys 472

Dataform function keys 472

Query Editor menus 473 Query Editor function keys 474 Diagram Editor menus 475

Diagram Editor function keys 476

Appendix B 477

Statistics and analysis 477

Viewing Sentences statistics 477 Message statistics 478 User statistics 478 Open profile statistics 478 Chapters statistics 480 Detailed chapter statistics 480 Memory usage summary 483 Scheduled process status 484

Chapter file analysis 484 Server request statistics 485

Glossary 487

17


Overview

Overview

Welcome to the Sentences Users Guide This Overview chapter describes

bull the key features of Sentences

bull new features introduced in this version

bull how to use the rest of this guide

Unless otherwise noted in the text this Users Guide describes the Sentences

Enterprise Edition If you are using the Sentences Personal Edition please refer to the

Personal Edition Supplement which describes the differences between the Personal

and Enterprise editions of Sentences You can find a copy of the Personal Edition

Supplement in the DocUserDocuments folder of your Sentences installation


Sentencesreg produced by Lazysoft is a database management system offering rapid web-

based business solutions Sentences is based on the associative model of data developed

in Java and is optimised for intranet and internet use Sentences is available in the

following editions

bull Sentences Enterprise Edition a commercial multi-user edition

bull Sentences Personal Edition a non-commercial single-user edition for evaluation

purposes only

Sentences offers unparalleled ease of development and speed of deployment for Web

based business solutions The Sentences Enterprise Edition runs on a Web server as a

Java servlet with client access through a conventional Web browser running a Java applet

Alternative client access is possible using XML for example from HTML forms The

Sentences Personal Edition runs as a stand-alone Java application that does not require a

separate server process

Key features

The main features of Sentences include

bull the associative database engine which provides a multi-user transactional capability for

the Sentences database (see Chapter 2 Introducing the associative model and Chapter

6 Advanced techniques)

bull configurable chapters and profiles allowing the flexible configuration of schema and

data (see Chapter 5 Working with Sentences)

bull support for XML as a means of exchanging data with other systems (see Chapter 8

Sentences and XML)

bull the Sentences Explorer for the creation and maintenance of associative schemas and for

browsing searching and selecting data (see Chapter 5 Working with Sentences)

bull the Sentences Dataform user interface for the entry and maintenance of data (see

Chapter 5 Working with Sentences)

bull a powerful associative query capability (see Chapter 7 Sentences queries)

bull Java APIs for the creation of custom-code Java applications (see Chapter 10

Customising Sentences)

18


Overview


Version 40 of Sentences includes new functionality and enhances some of the previously

existing features

bull LazyView

LazyView allows Sentences to query browse and import data from any data source that

has a JDBC driver This includes all modern relational databases Mapping the data

sourcersquos meta-data into an associative schema is automated but allows fine-grain tuning

of how the mapping is performed Both data and schema may be periodically refreshed

Corresponding data types in different databases may be made equivalent in Sentences and

their instances aggregated This functionality allows seemingly disparate data sources

including relational databases to be combined and viewed or queried as a whole

bull User Security

Sentences now has a User Security Model for managing users and their privileges

bull Business Rules Engine

Sentences now includes a rule-driven engine for describing and enforcing an applications

behaviour

Schema in the database can be given one or more domain to describe its states Rules can

be created to either prevent certain state changes or act upon a change from one state to

another

Effector Queries can be triggered by a state change or rule These specialised queries

allow the user to add update and delete data send messages or emails and fire Triggers

bull Queries

The existing Query Engine has been enhanced and extended to provide update

functionality to support Business Rules and additional functions for data manipulation

and cleansing

A new tool for composing expressions within the query editor has been developed to

make authoring easier and more productive

In addition a query can be attached to a type that defines a friendlier name to display in

place of uninformative data such as a name in place of a unique ID These are called

Display Name Queries bull Sandbox Mode

Sentences now includes Sandbox functionality to enable the user to make data and

schema changes and then discard those changes when they have finished experimenting

bull Transaction Visibility Mode

Sentences now includes the ability to set a Visibility Timestamp which sets a point in

time in the past to view the state of the current profile This has no impact on

performance

bull Server Process Scheduler

Sentences now includes a process scheduler This provides the ability to create lists of

tasks to be executed at regular intervals including updates to static LazyView data

execution of queries (with the ability to save the output) and starting an online backup

bull Automatic entity name generation

Sentences now includes the ability to generate entity names from the current timestamp

an incrementing ID or a Globally Unique Identifier as well as the existing generation

through the Sentences trigger functionality

19


Overview

bull Inactive instances

Sentences allows you to conveniently hide obsolete or inactive data during data entry

whilst retaining the data for historical records and reporting purposes The inactive status

can be set or cleared individually or en masse using an update query


For a rapid introduction to Sentences see the Sentences Tutorial which is available as a

printed book a PDF file and directly from the Help menu

If you are responsible for installing Sentences please see the Sentences Installation Guide

If you are responsible for configuring and deploying Sentences read Chapter 1


If you are new to Sentences and the associative model of data you should start by reading

Chapter 2 Introducing the associative model If you have worked with other database

products you should find the first part of Chapter 3 Database modelling in Sentences

useful as well Continue with Chapter 4 The Sentences Quick Tour and Chapter 5

Working with Sentences Refer to other chapters as necessary

If you have used earlier versions of Sentences you should first look at the section Whats

new in Sentences Version 40 in this chapter If you have not used Sentences Version

30 or later you should also read Chapter 5 Working with Sentences Chapter 7

Sentences queries and Chapter 8 Sentences and XML Chapter 9 Sentences

diagrams

If you are an experienced application developer read the second part of Chapter 3

Sentences user interface design options You should then look at Chapter 6 Advanced

techniques Chapter 10 Customising Sentences and Chapter 11 Worked examples

You may also want to consult the Doc and Examples directories of your Sentences

installation for additional online information for developers

At the end of this guide there is an Appendices section which contains lists of menus and

commands information on server statistics and a Sentences glossary A copy of this

Users Guide and of the Sentences Tutorial are available as Adobe Acrobat PDF files in the

DocUser Documents directory of your Sentences installation An online Help system

and an online copy of the Tutorial are accessible from the Sentences Help menu

Document conventions

Sentencesrsquo product documentation uses the following phrases

bull Type in means to enter data with your keyboard

bull Press means press a key on your keyboard

bull Click means move your mouse pointer over a button or other item on the screen and

press once on the primary button on your mouse (usually the left button if you are right-

handed)

bull Double-click means move your mouse pointer over a button or other item on the screen

and press twice rapidly on the primary button on your mouse (usually the left button if

you are right-handed)

bull Right-click means move your mouse pointer over a button or other item on the screen and

press once on the secondary button on your mouse (usually the right button if you are

right-handed)

bull Shortcut menu means the pop-up context menu displayed when you right-click (click

with the secondary button) on an object

This document uses the following typographical conventions

20

Your comments

Overview

bull Names of menus commands dialogs and fixed elements in Sentences are shown in

boldface font For example

the All Types folder

the Expand node command on the View menu

the Properties toolbar button

bull Names of actual files and directories are shown in monospaced font For example

the Human resources datachap file

The monospaced font is also used for examples of batch file HTML XML javascript

and Java code and for commands to be entered at a command prompt

bull When a command line or a line of code in a batch file HTML file or Java file cannot be

displayed on one line in this book the symbol sect is used to indicate that the line has been

split for display in this book only You should type in the lines of code in this book as one

line in the file or command

bull All user-created schema and data elements in examples of the Sentences database

(association types entity types associations and entities) are shown in a sans serif font

The verb of an association type or association is shown in sans serif italics Nested

associations are enclosed in parentheses for greater clarity

For example

Person

Project

Person assigned to project

(Louise East assigned to Pisces) starting date 25th March 2000

The sans serif font is used for the data and schema items you create in examples of the

Sentences database and for error messages that are displayed in the Message Log

Your comments

We welcome your comments on this Users Guide Please let us know how it has helped

your work with Sentences or how you would like to see it improved in the future

Please email your comments to supportsentencescom

21



Chapter 1


This chapter explains how to set-up and configure a Sentences installation It is

designed primarily for system administrators The topics covered in this chapter

include

bull licensing

bull configuring Sentences

bull shutting down and restarting the Sentences server

bull backing up and restoring your data

bull security considerations

bull servlet access to Sentences

bull uninstalling Sentences

For information on system requirements and installation procedures please see the

Sentences Installation Guide


Sentences is available in an Enterprise Edition and in a Personal Edition The Enterprise

Edition has two software components a server and a client The server component (the

Sentences server) runs as a Java servlet under a Web Application Server The Web

Application Server must be running a compatible servlet container (previously known as a

servlet engine) in order to run the Sentences server You need to have the appropriate

level of authorisation for your system in order to install Sentences

The client component (the Sentences client or Sentences applet) runs as a Java applet

in a Web browser or as a Java Web Start application and communicates with the server

using HTTP over TCP IP It is also possible to configure Sentences to use the secure

HTTPS protocol

More information is available from supportsentencescom

You must install an appropriate version of the Java runtime Plug-in for your browser

either before running the Sentences client or when it is first run on each machine but

apart from this there is no installation on the client

You can run the Enterprise Edition in Web mode with the server and client on different

machines or in local mode with the server and client on the same physical machine (see

Running the Enterprise Edition on a single computer)

The Personal Edition is a stand-alone Java application that does not require a separate

server process The Personal Edition cannot communicate with other clients or servers

and is designed for evaluation use on one computer only It is not licensed for commercial

use of any kind

The Personal Edition can be downloaded from wwwsentencescom If you are using the

Personal Edition please make sure you read the Personal Edition Supplement which can be

found in the DocUserDocuments folder of your Sentences installation

Additional components

There are two additional optional components to the Sentences Server

22

Sentences licensing


For information about the requirements and installation of each of these additional

components please see the Sentences Installation Guide For information about using each

of these components please see the separate guides provided in the

ltSentences_homegtDocUserDocuments directory

LazyView

The Sentences LazyView tool enables you to view external data alongside data from

Sentences chapters in one integrated view External data can include one or more

relational databases and MS-Excel spreadsheets

To enable the LazyView component you must have a suitable Sentences License

Application Suite

The Sentences Application Suite is a set of modular applications that introduce Sentences

features and showcase its potential The applications within the suite centre on core

business functions and use both the native Sentences Explorer interface and additional

custom HTML and applet interfaces

The Application Suite component is not installed by default It can be included during

installation by selecting the Custom install option

Sentences licensing

Sentences Enterprise Edition is supplied in accordance with a license agreement which

governs your use of the product Please see your license agreement for further details

The Sentences license file now is version-specific Only a Version 40 license will

activate Sentences Version 40 The license file contains the encrypted Initial System

Administrator password See System Administrator passwords for details

Sentences Personal Edition is distributed free of charge for evaluation purposes only The

Personal Edition is not licensed for any commercial use whatsoever You must have a

License file to run Sentences For more details see the Sentences Installation Guide

Personal Edition users should refer to the Personal Edition Supplement

Please see wwwsentencescom for more details about obtaining the Sentences Personal

Edition

Configuration files

Personal Edition environments

The Sentences Personal Edition runs as a Java application and does not require a separate

Web server The start-up properties for the Personal Edition are set in the

Serverproperties and Applicationproperties files For further information please

see the Personal Edition Supplement

The available memory default locale and locations of supporting libraries (for example

Java Database Connectivity libraries used in LazyView) are configured in the lazystartbat

or lazystartsh script See the section on Configuring server utilities for details as the same

file is used for starting the Personal Edition and running personal edition utilities such as

database backup data import and data export

Enterprise Edition evaluation and testing environments

The Sentences Version 40 installer installs the Tomcat Web server to host Sentences as a

Web application according to the guidelines of the Java Enterprise Edition specification

This is intended as a lightweight minimalist test server for evaluation and testing

To facilitate this Sentences 40 introduces a small desktop application ldquoSentences

Launcherrdquo This is intended for use as a Test environment rather than Production It

23

Configuration files


allows you to start and stop the Tomcat Web Application Server and launch the Sentences

Explorer Client locally using Java Web Start or open the welcome html web page

It is also possible to run the Tomcat Web Server as a service on Windows or other

platforms More information is available from supportsentencescom

Tomcat memory configuration

By default the Tomcat Test server is set up to use a default of 512MB system memory

The amount of memory (Java Heap) can be changed in the Server properties dialog or by

editing the catalinabat catalinash file directly in the tomcat installation The file

is located under the Sentences installation directory

ltinstallation dirgtTomcat4bincatalinabat (or catalinash)

To modify the maximum memory allocated edit the file and alter the line


The example shows 512 MB allocated to increase the available memory to 2GB you

would alter the line to read


Tomcat locale configuration

By default the Tomcat Test server is set up to use the default locale of the machine it is

installed on To change the default locale that Tomcat (and Sentences) will use you can

add the following parameters







-Duserlanguage=en -Dusertimezone= AmericaChicago

Tomcat port configuration

The Sentences tomcat server is configured to listen for server requests (from the

Sentences applet to the Sentences servlet) on a specific port number and to listen for

shutdown requests on a different specific port number By default these port numbers

are 8090 and 8095 respectively During installation users who select the Custom

installation option can specify alternative port numbers to be used by the Sentences

server

If you need to change the port numbers used by the Sentences test server you must edit

the references to port numbers in specific files listed below If you have installed the

Applications Suite there are additional references that must be edited You must always

shut down the Sentences server before making any changes to the port numbers and

restart it afterwards for the changes to have effect

bull References to the shut-down port for all installations

References to the shut-down port number are in


bull References to the request listener port for all installations

References to the request listener port number are in


24

Configuration files


bull Additional references to the request listener port for installations with the

Application Suite

Additional references to the request listener port number are in

ltSentences_homegtresourcescreateAppSuiteChaptersxml

ltSentences_homegtresourcescreateAppSuitexml

ltSentences_homegtTomcat4webappsIdeasWEB-INFwebxml

ltSentences_homegtTomcat4webappsCASWEB-INFwebxml

Security

When you first run the Sentences Launcher application you may be asked to confirm

some security checks depending upon your Operating System and system configuration

On Windows executing the Sentences Launcher application may invoke the User

Account Control mechanism that will prompt you to confirm running the application

On Windows executing the Sentences Launcher application may also invoke a dialog

from the Firewall program asking to grant access to the Java Runtime Environment

Enterprise Edition production environments

When installing Sentences into a production Web Application Server you will use the

Java Enterprise Edition standard Web Archive (WAR file) for the Sentences application

The Java Enterprise Edition standard enables convenient deployment of Web

Applications that are packaged into a single WAR file A default Sentenceswar file is

included in the Sentences installation

25

Configuration files


A single environment entry included in the Sentences web application webxml file needs

to be configured to tell Sentences where to locate the Sentences Serverproperties file

For detailed information please see the Sentences Installation Guide All server

configuration is stored in the Serverproperties file See below for details This

environment entry can either be specified in the webxml file or set in your Web

Application Server Management Application

Other customisations of the WAR file may include

the addition of Java Database Connectivity libraries (JDBC jar files) for use with

LazyView

the addition of static or dynamic web application pages for a customised web

application that includes embedded Sentences applets

Web servers not using Java Enterprise standards

If you wish to install Sentences into a Web server that does not use the Java Enterprise

Edition standards you will need to create a directory structure that includes a

WebApplication directory and a Server directory under your ltSentences_homegt

location The web server needs to define a virtual directory that is set to this

WebApplication directory We recommend using the mapping name Sentences

The WebApplication directory needs to contain all the files that are accessed by the

Sentences client including those listed above under the webappsSentences directory

The Server directory needs to contain all the files that are accessed by the Sentences

server including those listed above under the webappsSentencesWEB-INF directory

It will need to be able to read the ldquoenvironment entryrdquo that specifies the location of the

Sentences Serverproperties file

Sentences installation directories

There are two separate locations for files in a Sentences installation program files and

data files You are prompted for these tow locations during installation

Prior to Sentences Version 40 Sentences Trace files were kept with the program files

These are now located by default along side the chapter data directory The Java process

running the Sentences server must have permission to create read and write files in both

the Chapters directory and the Trace directory

If the Trace directory does not exist the Java process running the Sentences server must

have permission to create it

The following list shows the directories created by the installation procedure for the

Sentences Enterprise Edition with descriptions of the directories and files which are

important for Sentences users The initial installation of Sentences includes all the

directories and files required for Tomcat 41 a J2EE compliant Web server An

exhaustive description of the directories and files required by Tomcat is beyond the scope

of this Users Guide

In this guide the term ltSentences_homegt refers to the main Sentences server program

installation directory This is the directory selected during installation and specified in the

InstallPath parameter in the Serverproperties file The default location for the

Sentences server installation directory on Windows platforms is CProgram FilesLazySentences40

The default location for the Sentences server installation directory on Unix or Linux

systems is usrlocalLazySentences40

26

Configuration files


All the data files required by a default installation of Sentences including the files

required by optional components are in the ltSentences_datagt directory and its

subdirectories This directory is also specified during installation The default location for

ltSentences_datagt on Windows platforms is CSentencesData40

The default location for ltSentences_datagt on Unix Linux systems is usrlocalLazySentencesData40

The default locations for Sentences chapters (referred to in this guide as

ltSentences_chaptersgt) for Sentences images (referred to in this guide as

ltSentences_imagesgt) and for Sentences trace files (referred to in this guide as

ltSentences_tracegt) are subdirectories of ltSentences_datagt

The ltSentences_chaptersgt location is the first directory listed in the ChapterPathList


bull ltSentences_chaptersgt

The default location for the Sentences chapters directory on Windows platforms is

CSentencesData40Chapters

The default location for the Sentences chapters directory on Unix Linux platforms is

usrlocalLazySentencesData40Chapters

During the installation procedure you can choose a different location for the chapters

parent directory You can specify additional directories for chapters in the

ChapterPathList and choose different directories for the SystemChapterPath and

TempChapterPath properties in the Serverproperties file (see The Serverproperties

file ) This directory is used by the Sentences server and is not accessed directly by Web

users Make sure that the file system security permissions for this directory are set so that

the Java process running the Sentences server is able to create read and write files within

the Chapters directory

By default the chapters directory contains the system chapters Metaschemachap

Schedulerchap and Profileschap which are used internally by Sentences and which

must not be changed The system chapter Profileschap has a special status in all

Sentences sessions as it is used to store profiles and other configuration data It must not

be used as a changes chapter for user updates

The Examples subdirectory of the chapters directory contains the chapter files for the

Human resources example application and further subdirectories containing chapter

files for the Application Suite examples if these are installed

bull ltSentences_tracegt

The default location for the Sentences trace file directory on Windows is CSentencesData40Trace

The default location for the Sentences images directory on Unix Linux platforms is usrlocalLazySentencesData40Trace

This is the physical location in which the server trace files are stored When diagnosing

any problems the trace files are useful in providing information on the server activity

The location is also used to store the outcome of LazyView activity when creating a

LazyView Mapping or updating the static data for a LazyView

This directory is the default location for any Sentences server trace files It is referenced

by the TracePath property in the Serverproperties file The file system security

permissions for this directory must allow the servlet container process create read and

write access to files within the directory If the trace directory does not exist the

Sentences servlet attempts to create it You must either create the directory manually or

27

Configuration files


set the file system security permissions for the directory containing the trace directory to

allow the servlet process to create it

A trace file is created each time the Sentences server starts You can delete these files

manually when they are no longer required

bull ltSentences_imagesgt

The default location for the Sentences images directory on Windows is CSentencesData40Images

The default location for the Sentences images directory on Unix Linux platforms is

usrlocalLazySentencesData40Images

This is the physical location in which any images referenced in your Sentences database

can be stored This directory is used by the Web server to deliver images to clients and for

this reason it has a virtual directory mapping in Tomcat (ImagesforSentences)

bull ltSentences_homegt

This is the main Sentences program installation directory This directory contains server

administration scripts and batch files the Serverproperties file the Sentences license

file (SentencesLicensetxt) and the small application to facilitate the Tomcat Test

server

Server administration scripts include

Database backup and restore scripts

Chapter and Profile import and export scripts

XML data import and export scripts

Other diagnostic scripts

bull ltSentences_homegtDatatypes

This directory is the default location for any custom datatypes It is referenced by the

DatatypePath property in the Serverproperties file Any custom datatypes that are

compiled into Java archive (JAR) files which are placed in this directory are

automatically available to Sentences

bull ltSentences_homegtDoc

This directory contains extensive Sentences documentation for application developers and

users You can access detailed information on the Sentences API and also access the

Sentences Tutorial and Sentences Users Guide by opening the file indexhtml in your

Web browser

bull ltSentences_homegtExamplesChapters

This directory contains backup copies of the system chapter Profileschap and the

chapter files for the Human resources example application

bull ltSentences_homegtExamplescom

bull ltSentences_homegtExamplesCSVImport

bull ltSentences_homegtExamplesDerivations

bull ltSentences_homegtExamplesExistingDatatypes

bull ltSentences_homegtExamplesHTML

bull ltSentences_homegtExamplesJars

This group of subdirectories contains various files that are referred to in Chapter 11

Worked examples

The ExamplesExistingDatatypes subdirectory contains the source code for the

datatypes included in Sentences

28

Configuration files


The ExamplesHTML directory contains examples of HTML pages for the Dataform applet

(see ldquoThe Dataform appletrdquo) the Picker applet (see ldquoThe Picker appletrdquo) and the Query

applet (see ldquoThe Query appletrdquo)

bull ltSentences_homegtLicences

This directory contains the text of the Sentences License Agreement

(SentencesLicenseAgreementtxt) and the text of the license agreements pertaining to

software produced by the Apache Software Foundation and included with Sentences The

Sentences License file that is needed to activate Sentences is not placed in this directory

but in ltSentences_homegt

bull ltSentences_homegtresources

This directory contains image resources javascript libraries and additional JAR files that

might be needed for a server process such as a JDBC library

This directory also contains the lazystartbat file and lazystartsh files These files

contain scripts for invoking the Sentences server-side utilities For more information see

The lazystart script filerdquo

This directory also contains script files that can be used to import the chapter and profile

definitions for the optional Sentences component Sentences Application Suite Usually

these chapter and profile definitions are created as part of the installation process

However if you install the Sentences server on the IBM i you need to run these scripts

You can also run these scripts if you have restored the default profiles database by

copying the Profileschap file from ltSentences_homegtExamplesChapters

bull ltSentences_homegtStylesheets

This directory contains sample XSL stylesheets used to transform XML data exported

from Sentences Additional XSL and XSLT files required for your Sentences applications

should be added to this location or to a sub-directory of it If you change the location of

the files in this directory you must update the StylesheetURLBase property in the

Serverproperties file For more information about XSL stylesheets in Sentences see

Chapter 8 Sentences and XML

If you have installed the Application Suite this directory also includes a subdirectory

named ApplicationSuite which contains the stylesheets used by the Application Suite

examples

bull ltSentences_homegtTomcat4

This directory contains all the files and directories required for the Tomcat Web server

which conforms to the Java Enterprise specifications Sentences and the Sentences

Application Suite examples are installed as web applications under this Tomcat server

bull ltSentences_homegtTomcat4webapps

This directory includes Web archive (WAR) files for Sentences and for the Application

Suite example programs If you wish to run Sentences with any other Java Enterprise

compliant Web server you can use the WAR files from this directory

The following paragraphs describe the sub-directory structure for Sentences The pattern

of sub-directories for each of the Application Suite examples are similar

bull ltSentences_homegtTomcat4webappsSentences

This is the top-level directory for Sentences It contains all the files that need to be

accessed by the Sentences client such as the Sentencesjar archive file and

launchhtml start page If you create any customised message files they must be put into

this directory as well as into the WEB-INFclasses subdirectory This directory contains

29

Configuration files


the example Swiss German messages file Messages_de_CHproperties (see

Localisation notes )

If you create any customised Help topic HTML pages you must place them along with

the Help topics mapping file in this directory (see Adding custom Help topic pages )

This is also the parent directory for Sentences online Help and online Tutorial

bull ltSentences_homegtTomcat4webappsSentencesWEB-INF

This is the directory for all the files that need to be accessed by the Sentences server This

directory has two sub-directories classes for individual Java files and lib for Java

archive files

bull ltSentences_homegtTomcat4webappsSentencesWEB-INFclasses

This directory contains individual Java code class files that need to be accessed by the

Sentences server

If you create any customised message files they must be put into this directory as well as

into the webappsSentences parent directory This directory contains the example Swiss

German messages file Messages_de_CHproperties (see Localisation notes )

bull ltSentences_homegtTomcat4webappsSentencesWEB-INFlib

This directory contains compiled Java code archive files (JAR files) that need to be

accessed by the Sentences server These include the SentencesServerjar file and any

JDBC jar files to support LazyView chapters Older versions of Java may require the

XML parser libraries such as xalanjar xercesjar and xml-apisjar Or you may

wish to use different XML parser libraries in which case you include them here

bull ltSentences_homegtTriggers

This directory is the default location for any triggers It is referenced by the TriggerPath

property in the Serverproperties file Any triggers that are compiled into Java archive

(JAR) files which are placed in this directory are automatically available to Sentences

bull ltSentences_homegtUninstaller

This directory contains files used for uninstalling Sentences

Server properties

Sentences Server has many configurable properties that govern the available functionality

and the way it behaves These properties are stored in a file called Serverproperties in

the installation directory

Sentences 40 introduces the ability for a System Administrator to be able to edit most of

these properties from a Sentences Client (The JDBC configuration is not included To

change these the user will still have to manually edit the Serverproperties text file and

restart the server) Where applicable these properties are changed with immediate effect

This allows an Administrator more flexibility and removes the need to restart the server

for many properties For example the Administrator can change the level of trace file

logging temporarily to debug a production issue

Some properties cannot be changed without restarting the server These are indicated

below

To change the Server Properties follow these steps

1 Log into Sentences as a System Administrator

2 Select the Server Propertieshellip item from the File menu in the Sentences

Explorer

3 Modify the properties you wish to change and select OK or cancel

30

Configuration files


Server Properties have been grouped into seven areas Installation Profile Security

Troubleshooting Email LazyView and Java Heap The last group concerns the amount

of memory allocated to Java Processes on the server

List entries should be separated by the path separator for this platform ie on

Windows or on Unix

Installation properties

All properties on the Installation tab are physical locations on the server and will not be

changed dynamically This is why a ldquolive valuerdquo is shown (if different from the currently

set value) The new value will only be used when the server is restarted

bull Chapter Path List

This property stores a list of locations for your Sentences chapters as fully-qualified

directory pathnames The entries in this list refer to the location you selected for

ltSentences_datagt during Sentences installation The default entries in this list are as

follows

ltSentences_datagtChapters (for user-created chapters)

ltSentences_datagtChaptersExamples (for the Human resources example chapters)

ltSentences_datagtChaptersExamplesApplicationSuite (for the Application Suite

example files - not listed if the Application Suite is not installed)

You can add additional locations for chapter files to this property setting by entering

fully-qualified pathnames Separate the entries with the appropriate delimiter character for

your system (a colon for UnixLinuxMac OS X and a semi-colon for Windows) If

you type in more than one location for this property then Sentences uses the first entry as

the default location

bull System Chapter Path

The location used to store the system chapters Metaschemachap Schedulerchap and

Profileschap If no location is given the first location in the Chapter Path List will be

used

bull Temporary Chapter Path

The location used to store temporary chapters such as query chapters If no location is

given the first location in the Chapter Path List will be used

bull Image Path

The location used to store relative images references for Image Datatypes This defaults to

a sibling folder next to the first chapter location

bull Backup Path

This property stores the location of the directory for any backup files created by the

Online Backup procedure (see Online backup )

bull Trace Path

The location used to store server trace files This defaults to a sibling folder next to the

first chapter location

bull Statistics Path

This property specifies the directory location in which statistics files are placed Statistics

files have the name format Statisticsxxxtxt (where xxx represents a timestamp)

31

Configuration files


There is no default setting for this property If this property is not set statistics files are

not created

bull Trigger Path

The location used to store Java Archive files containing User defined Server Triggers

bull Datatype Path

The location used to store Java Archive files containing User defined Datatypes

bull Default Image URL Base

The server will use this Image URL Base when no other has been specified from the

client The XML Export process uses this Image URL base when automatically

generating XSL Stylesheets

bull Stylesheet URL Base

The location used to store XSL Stylesheets

bull Text Document Path

This property stores the location of textual documents that can be imported into

Sentences For example txt or pdf files The TextDocumentPath property will

default to a subdirectory called Text next to your first Chapters directory and Trace

directory

bull Install Path

This property stores the location of your Sentences directory The InstallPath property

is set from your response to the installation prompts This location is known as

ltSentences_homegt This property can only be modified by editing the


Profile properties

bull Profile Timeout

The inactive timeout period in seconds for opened profiles

bull Pending Timeout

The inactive timeout period in seconds for pending data results

bull Chapter Timeout

The time period in seconds after which an update will time out waiting to lock a chapter

bull Backup Timeout

The time period in seconds after which a backup process will time out waiting to lock a

chapter

bull Cache Size

The maximum amount of memory in megabytes to use to cache data from all chapter

files combined

bull Visibility Cache Limit

The maximum size of the visibility caches This is the sum of the known visible objects

known hidden objects and known committed transactions

bull New Chapter Block Size

The default blocksize in kilobytes to use for a new chapter

bull New Temp Chapter Block Size

32

Configuration files


The default blocksize in kilobytes to use for a new temporary chapter

bull Minimum Transaction Memory

The amount of free memory in megabytes that a server update will insist on before

starting to carry out transaction updates

bull Statistics Poll Interval

This property specifies the time interval in seconds for which the number of server

requests is recorded The default setting for this property is 300

bull Hidden Request Buffer Size

The default buffer size used for hidden forwardinversedata request results when used in

derived type and derivation expressions This is used for very large databases

bull Maximum Effector Messages

The maximum number of messages generated by an Effector Query before we curtail

reporting to the client (to avoid overwhelming the client)

bull Maximum SMTP Emails

The maximum number of simple emails generated by an Effector Query

bull Preempt Interesting Associations For Large Databases

This property should be set to true for large databases where the process of determining

whether each instance has child associations is expensive Setting this property to true

will pre-emptively determine whether there are many triple pages to search (gt100) and if

so assume there are children Only when the user actually expands the instance do they

discover if it has child associations This property can only be modified by editing the


bull XML Parser Class

This property sets the class name of the XML parser used by Sentences when importing

XML documents whenever a parser other than the default is required The default parser

is orgapachexercesparserSAXParser

This property can only be modified by editing the Serverproperties file directly

Security properties

The Security properties do not include access flags for Servlets for the Personal Edition

bull Client Api Access

Grant access to user-written programs using the Sentences client API URL Pattern ApiServer

bull Statistics Access

Grant access to Sentences server statistics URL Pattern Statistics

bull Chapter Statistics Access

Grant access to Sentences chapter statistics URL Pattern Chapter

bull DTD Access

Grant access to Generation of XML DTDs URL Pattern DTD

bull XML Schema Access

Grant access to Generation of XML Schemas URL Pattern Schema

33

Configuration files


bull XML Access

Grant access to XML output from a saved query URL Pattern XML

bull Import XML Access

Grant access to XML import using a saved query URL Pattern ImportXML

bull Backup Access

Grant access to Online Backup URL Pattern Backup

bull Anonymous Login allowed

Allow end users to log on anonymously as Public

bull Maximum login attempts before lockout

The maximum number of failed attempts an end user is allowed before the account is

locked

bull Minimum length of a password

The minimum length of a new password

bull Default User Roles

A list of the Roles to assign any new Users separated by semicolons

Troubleshooting properties

bull Maximum log size

The maximum size in megabytes of a log file (used for robust journaling) before it is

closed and a new file opened

bull Business Rules Disabled

Disable all Business Rules functionality

bull Debug Business Rules

Log detailed troubleshooting information for Business Rules

bull Disable Scheduler

Disable the Server Process Scheduler This does not prevent a user manually triggering a

process list to be run The Scheduler is enabled by default

bull Check Value Visibility




enabled with this property This additional check is disabled by default

bull Trace Level

Trace Level is a set of bit flags that determine which server events are logged to the server

trace file Simply add together the numbers for the types of tracing that you want to

appear in the file

Value Meaning

0 Only major events are logged

34

Configuration files


Value Meaning

1 Profile operations are logged


4 Requests from clients to update data are logged without the prior




16 All server update actions are logged whether they came directly from a


being run




256 A one-line summary of Client Parameters are logged This is only

available if a one-line summary is requested (2)

Email properties

bull SMTP Host

The host name or address of the SMTP server

bull SMTP Username

The username for the SMTP account

bull SMTP Password

The password for the SMTP account

bull Notify end user of SMTP failures

Notify the end user if there is a failure to send email

bull Valid From List

A List of valid email addresses that the server can send SMTP email from separated by

semi-colons

LazyView properties

The LazyView Properties are only displayed if the License File includes LazyView

functionality

bull Log SQL

Output the SQL being generated for LazyView

bull Multiline Text Threshold

The minimum size of Relational Text Column for which a Sentences text field is set to be

multi-line

35

Configuration files


bull Cache Timeout

The time period in seconds after which a cached dynamic LazyView object will be

discarded and re-read A value of zero indicates cached objects will never timeout

bull Maximum result set cache size

The maximum number of open cursored results sets to hold against each RDBMS

bull Query Timeout


data dynamically or executing a query in a dynamic LazyView profile

bull Import Timeout


LazyView data import

bull Dynamic Snapshot Limit

The maximum number of results to obtain in any dynamic request to an RDBMS Zero

indicates no limit For very large databases this significantly improves performance by

avoiding creating a cursor over a large result set Note Caution should be used with this

feature as any queries will also have their input limited to this amount which will lead to

incorrect aggregate values

bull Disable In Clause Optimisation

This flag indicates whether to disable the optimisation of Select statements that use an IN

clause to improve dynamic Lazy View performance This property can only be modified

by editing the Serverproperties file directly

Java heap properties

The Java Heap properties will only change when the server is restarted These properties

are convenient when using the Personal Edition or the Tomcat Test environment

If you have deployed Sentences to a Web Application Server then the Java Heap available

will be dependent on the settings of your Server The Server Process Java Heap value is

relevant for any server utility programs that are run when the Sentences Server is stopped

bull Tomcat Java Heap

The size in megabytes of memory to use for the main Sentences Server process running in

Tomcat If you are using Tomcat you can set how much Heap is available to the server

here If you are not using Tomcat then you will need to configure the memory allocation

in your chosen Servlet Container The Tomcat Java Heap property is not applicable to the

Personal Edition

bull Server Processes Java Heap

The Server Processes Heap Size is used when running other exclusive server processes

such as exporting a database This is also the value used by the Personal Edition

Specialist properties

There are several properties that are not accessible from the User Interface because they

make fundamental changes to the way that the system works or are rarely used but

important They are set by editing the Serverproperties file in the installation directory

when the server has been stopped

bull DataformLayoutSystem=[Sections|Pages]

36

Configuration files


This property can be set to Sections or Pages and defaults to the former Page layout

was the original system by which fields were organised in Dataforms The more

sophisticated Sections Layout system replaces it If Pages have been used extensively in

an existing Sentences profile then this property allows the user to revert to that layout

system

bull ShowSetQueries=[true|false]

This property (which defaults to false) allows the Set Query functionality to be exposed

This would be useful when upgrading an existing profile that made use of Set queries

when converting them to request based queries

bull DisableDemandPagingQueryOptimisation=[true|false]

This property (which defaults to false) allows the system administrator to temporarily turn

off the demand paging optimisation for queries on large datasets

Virtual directories

When you install Sentences with the default Tomcat Web server Tomcat creates virtual

directories for two specific locations ltSentences_imagesgt (by default this is

SentencesData40Images) and for the Web application directory (by default this is

ltSentences_homegtTomcat4webappsSentences)

The jnlp files or javascript refer to the ltSentences_imagesgt location by using the

ImageURLBase parameter with the name the name ImagesForSentences (see About the

ImageURLBase parameter)

If you use Sentences with any Web server other than the default Tomcat Web server you

must create virtual directories on your Web server for these two locations Please refer to

the documentation for your Web server for instructions on how to do this

Note The documentation for some Web servers (for example the Apache HTTP server)

refer to virtual directories as aliases

If you want to allow users to access the Sentences Users Guide and Sentences Tutorial you

can also create a virtual directory for their location on the server which is

ltSentences_homegtDocUserDocuments

About the ImageURLBase parameter

The Sentences Enterprise Edition client is a Web-based application that does not use the

local file system This means that references to external files such as image files need to

be resolved to fully qualified (absolute) URLs

Image instances are defined in the Sentences database using a string representation of the

appropriate file name or URL Any full URL entered is referenced independently of the

ImageURLBase parameter Any non-URL file name entered is combined with the value of

ImageURLBase to create a full URL

As part of the Sentences initial installation the Images subdirectory created in the

ltSentences_datagt location you chose is automatically configured as a virtual directory

named ImagesForSentences The ImageURLBase parameter is set to refer to this virtual

directory

In general for the Enterprise Edition when the value of ImageURLBase starts with

images from the default location must be served by the same Web server which is serving

Sentences That Web server must serve the images in response to a request of the form

httplthostnameportnumbergtltImageURLBasegtltimage namegt where hostname and

portnumber are derived from the codebase from which the Sentences applet JAR file is

loaded

37

Configuration files


Where ImageURLBase does not start with the default image location can be served by

any URL In this case images must be readable on the client using a URL of the form

ImageURLBaseimage name For the Enterprise Edition this kind of configuration typically

uses a second web server as the default image source and ImageURLBase takes the form

httpimageWebHost imageVirtualDirectory where imageWebHost is the host with

optional port specifier and imageVirtualDirectory is a logical name mapped by the

web server to the images directory

Support for configuring other environments

Lazysoft Technical Support maintains the list of currently supported configurations for

Sentences and can advise you on setting up your environment

For further information please contact supportsentencescom

Configuring server utilities

Server utility programs including database backup restore import and export all use a

common script to start lazystartbat or lasystartsh This enables the memory

allocation locale and supporting java libraries to be configured in one file

The lazystart script file

The ltSentences_homegtresources directory contains the lazystart script file (named

lazystartbat on Windows systems and lazystartsh on UnixLinus systems) This

file contains a script used for starting various Sentences server-side utilities such as

Import and Export which require explicitly specified Java classpaths The lazystart

script file uses variables to simplify the specification and modification of Java classpaths

If you want to change any of these variables you may edit the lazystart script file

Always use a plain text editor to edit the file and always save the file as plain text

The commands and variables listed in the file are as follows

bull SENTENCES_HOME

This variable stores the location of your Sentences home directory The default value is

taken from the location you selected when you installed Sentences

bull LAZY_JAVA_HOME

This variable stores the location of the Java home directory used by Sentences

The default value is taken from the Java Virtual Machine location you selected when you

installed Sentences

bull Classpath elements

This section is used to set the classpath used in the Java execution command Please see

the section Using the classpath argument below for more detailed information

The classpath setting includes the JAR files used by Sentences Enterprise Edition which

in the default installation of Sentences are in the

ltSentences_homegtTomcat4webappsSentencesWEB-INFclasses directory and they

are

SentencesServerjar

xalanjar

xercesjar

xml-apisjar

The JAR files used by Sentences Personal Edition are all in the ltSentences_homegt

directory and they are

SentencesPEjar

xalanjar

38

Configuration files


xercesjar

xml-apisjar

If you move or delete any of these JAR files from the default installation of Sentences

with Tomcat you must edit this section of the lazystart script file to use the changed

paths

The script also includes several other mandatory jar files and then dynamically adds any

jar or zip file present in the resources directory This way you can include a java

library by simply placing it in the resources directory

bull JVM_OPTS

This property sets Java Virtual Machine options for server-side utilities such as the Java

memory parameters The memory parameters are in the format -Xmx512m ndashXms512m

where -Xmx specifies the maximum system memory that can eventually be used (shown

here with the example value 512m meaning 512MB) and -Xms specifies the initial amount

of memory to be allocated















-Duserlanguage=en sect

-Dusertimezone= AmericaChicago

The ndashshowversion parameter displays the version of java in the output

Using the classpath argument

The term classpath has two uses and this may cause some confusion CLASSPATH is an

operating system environment variable and -classpath (abbreviated -cp) is a command-

line argument for Java

bull -classpath (or -cp)

Whenever a Java program is run the Java Virtual Machine must find all the classes which

are required or the program fails Classes are found using the classpath which specifies a

list of JAR files and directories to be searched for class definitions

Oracle recommend setting a classpath on the Java command line using the -cp or -

classpath arguments and this recommendation is followed in the lazystart program

bull CLASSPATH

If a classpath is not supplied on the command line Java programs use the environment

variable CLASSPATH instead In some cases start programs for Java may include this

setting on the classpath used to run Sentences Loading some publicly available JAR files

can lead to the Sentences server failing to start depending on the installed JAR files and

on how the CLASSPATH for Sentences is determined (typically this is controlled by your

servlet container configuration) To avoid these problems Lazysoft recommends that the

39

Configuration files


you should not set the system wide variable CLASSPATH for users who run the Sentences

server

Sentences client configuration

There are several Clients to the Sentences Server The Server provides several Java

Servlets for different purposes For example there is an XML servlet and an XMLSchema

servlet that can be accessed to provide a CrystalReports ldquoclientrdquo with XML data to be

rendered into a Crystal Report The XML servlet can also be used to transform the

retrieved data into html utilising any javascript libraries to render graphs tag clouds etc



or used as stand-alone desktop applications using the Java Web Start technology



Java Runtime Environment

Java Applets require a Java Runtime Environment to be installed on the client machine

This is available for a large range of platforms The Java Runtime installation also

includes Browser plugins that enable the browser to display java applets embedded in

web pages We recommend the latest version of the Java Runtime Environment be

installed on client machines

You can manually install the Java Runtime Environment from the Oracle Web site

appropriate to your browser and platform

httpjavacomendownloadtestjavajsp

By default the Sentences web application contains a welcome page that detects the

browser and operating system of the client and any installed JRE If the JRE is not

installed or requires upgrading to the minimum required version then the page will either

redirect the user or show instructions on how to install the latest JRE

If a suitable version of the JRE is installed and the browser plugin is enabled then the

welcome page includes a link to launch the Sentences client as a desktop application

Upon first launch a desktop shortcut will be created that can be used without the need for

a browser next time

If you have developed your own application and embedded Sentences applets into it then

you will have created a ldquohomerdquo page which can use the same detection of browser

platform and JRE to assist new users of your application

See the launchhtml webpage for an example of how to use the javascript library to

detect the browser platform and JRE in your own web pages and launch Sentences as a

desktop application See the DataformApplethtml webpage in the ExamplesHTML

installation directory for an example of how to use the javascript library to detect the

browser platform and JRE in your own web pages and embed Sentences applets in the

HTML

Java browser plugins

Please note that if you intend to use both the 32-bit and 64-bit versions of a browser then

you will need to install both versions of the Java Runtime Environment The 32-bit

version of a browser can only detect and use the 32-bit version of Java Runtime

Environment Similarly the 64-bit version of a browser can only detect and use the 64-bit

version of Java Runtime Environment

It is possible to disable Java plugins in each of the browsers and in the Java Control Panel

Different versions of JRE have different options for enabling and disabling these plugins

Please consult the Oracle website for details

40

Configuration files


httpjavacomendownloadhelpenable_browserxml

Javascript helper library lazyDeployJavajs

Sentences includes a javascript library to assist in the detection of Java and both the

launching of a Java Web Start Sentences Application or the embedding of a Sentences

Applet in a web page

This javascript library has been adapted from the javaDeployjs library developed by

Sun Microsystems and Oracle

The javascript library can be used to detect whether a suitable version of Java is available

and if not then prompt the user to download and install one or if not possible then direct

them to the Oracle website The library means that you do not have to write separate code

for different Operating Systems 32-bit or 64-bit Operating systems or the many different

browser clients available All Enterprise environments can be dealt with A known

exception at the time of writing is Safari on Windows which cannot detect the Java

plugin

Applet configuration

When embedding a Sentences Applet into a web page the javascript library can be used

to write the appropriate html for the given browser

The javascript library must be referenced in the html usually in the ltheadgt section For

example






example of an embedded Sentences Dataform Applet

41

Configuration files



into The first parameter to the writeAppletHTML method ldquosentencesAppletrdquo is the id of

the element Below is part of the ltbodygt html that includes a div element with an id

sentencesApplet This can be any name you give but different applets on the same page

must have unique ids

The second parameter to the writeAppletHTML method is a list of general parameters to

define which of the Sentences Applets to render and what its size in the html it should be

The code property defines which Sentences Applet is displayed

bull Dataform applet

code lsquocomsentencesdataformDataformAppletclassrsquo

The Dataform applet displays a dataform for a single instance or a blank ldquocreaterdquo

dataform for the specified Entity Type in the specified Profile

bull Diagram applet

code lsquocomsentencesguidiagramDiagramAppletclassrsquo

The Diagram applet displays either a saved diagram the results of a query or a blank

diagram

bull Picker applet

code lsquocomsentencesguipickerPickerAppletclassrsquo

lth1gtEmployee Detailslth1gt

lth2gtBarney Norrislth2gt

ltdiv id=sentencesAppletgtltdivgt

ltpgt

The above is an example of a Dataform applet embedded within an HTML page



deployJavawriteAppletHTML(sentencesApplet

Applet Parameters

codecomsentencesdataformDataformAppletclass

archiveSentencesjar

width700

height500

Application Specific parameters


EditOptiondata

FixedProfileno

LazyTypeEmployee

LazyInstanceBarney Norris

EnablePickersyes

SaveButtonTextSubmit changes


Bordernone

ColourwindowFFFFEE

ColourmenuFFFFEE





ColourcontrolDDEEFF







)

)

ltscriptgt

42

Configuration files


The Picker applet displays a list of instances for the user to viewedit in a dataform They

may also be able to create new instances

bull Query applet

code lsquocomsentencesdataformQueryParameterAppletclassrsquo

The Query applet displays a form to enter the parameters for a given query and then

displays the query results

bull Sentences Explorer applet

code lsquocomsentencesmainSentencesclassrsquo

This is the main applet for the Sentences Explorer Client

The third parameter to the writeAppletHTML method is a list of parameters specific to

each of these applets For more information on each of these see The Dataform applet

The Picker applet - and The Query applet An example of the Diagram applet is

included in the examplesHTML directory of the installation

The Sentences Explorer applet uses the following common applet parameters

Sentences applet parameters

bull Profile

The Profile parameter defines the default profile opened when the Sentences applet is

started You can change the value of this parameter to the name of the default profile for

your installation The name of the profile must not contain any special characters that

need to be represented by escape sequences in HTML If the Profile parameter is not

specified then Sentences will offer the user a list of profiles that they are allowed to open

The user can also cancel from this list and create a new profile to work with if allowed

bull FixedProfile

The FixedProfile parameter can have the values yes or no When the FixedProfile

parameter is set to yes the Open Profile Delete Profile and Edit Profile options in the

Explorer File menu are not available This creates a profile with limited database access

for end-users

Note You can restrict a users ability to change parts of the database by using a

combination of the FixedProfile and EditOption parameters and by specifying

changes chapters in the Edit Profile dialog (see Using the Edit Profile dialog )




bull EditOption


The possible values are schema query data and none






43

Configuration files



parameter the default setting is none The setting in the jnlp file or javascript supplied

with Sentences is schema

If the EditOption parameter is set to data or none users can create edit and execute

queries but they cannot save any changes they make to queries




bull FontSize

The FontSize parameter specifies the font size to use in the Sentences Explorer (default

11 for Windows) This is intended for use on large monitors with large resolution where

the text size may be too small for adequate viewing during for example a presentation

Font sizes larger than 16 are not recommended

bull ImageURLBase





display images By default this is ImagesForSentences which is a relative URL

referring to the Images subdirectory you chose during installation For further details

about this parameter (see About the ImageURLBase parameter)

Note You can add further parameters at this point in the code (see Additional optional

parameters)

Additional optional parameters

You can add any of the following parameters to your HTML script

bull ServletPort

The Sentences applet attempts to connect to the Sentences servlet using the host name and






the ServletPort parameter See also Starting the Sentences client

bull ServletContext

The Sentences applet requires a servlet context to connect to the Sentences servlet The

servlet context is the part of the URL after the host name and port The default value is

Sentences If the Sentences servlet is configured on a different context this must be

specified using the ServletContext parameter for example

ltparam name=ServletContext value=servletgt

See also Starting the Sentences client

bull RequestSize

Sets the number of data items retrieved from the Sentences database for each request If

more items exist Sentences displays the More prompt in the data pane The default

value for RequestSize is 500

44

Configuration files


bull LookandFeel

Sets the appearance of the Sentences client applet The possible settings are Default

Windows Metal Nimbus and Motif Not all of these possible settings are supported on

all platforms The supported settings depend on those supported by the version of Java

installed

bull UserText

This parameter specifies an optional text string that is added to transactions as userText

This can be referred to by triggers

bull ProfilesProfileVisible

This parameter determines whether the system profile Profiles is visible to users in the

Open Profiles dialog The possible values are Yes and No The default setting is No (see

The Profiles database and the Profiles profile)

Web Start Configuration

The Java Web Start technology uses a Java Network Launching Protocol (JNLP) file to

define how the Sentences Client is to be configured in a similar way to the way a Java

Applet is configured

One advantage of the JNLP configuration over HTML applet configuration is that it is

browser-independent Whilst the Sentences Server can be run with any version of Java

above Version 16 the client Web Start must use Version 7 to benefit fully from the

advantages of Web Start

The lazyDeployJavajs javascript library can be used to render the appropriate html for

the given browser and provide either a link that will launch the Sentences Explorer Client

as a Java Web Start application or instructions on how to install a suitable Java Runtime if

required

The lazyDeployJavajs javascript library must be referenced in the html usually in the

ltheadgt section For example






example of creating a link (or Java installation instructions)


into The first parameter to the writeLaunchHTML method ldquolaunchInfordquo is the id of the

element Below is part of the ltbodygt html that includes a div element with an id of

launchInfo This can be any name you give but different elements linking to different

client configurations on the same page must have unique ids



deployJavawriteLaunchHTML(launchInfo)

)

ltscriptgt

45

Configuration files


ltjnlp href=sentjnlpgt

ltinformationgt

lttitlegtSentences Explorer 40lttitlegt

ltvendorgtLazysoft Ltdltvendorgt

lticon href=resourcessentencesgifgt

ltdescriptiongtSentences Enterprise Edition V40150EEltdescriptiongt

ltshortcut online=falsegt

ltdesktopgt

ltshortcutgt

ltinformationgt

ltupdate check=backgroundgt

ltresourcesgt

ltjava version=170+ href=httpjavasuncomproductsautodlj2se

java-vm-args=-Xss1mgt

ltjar href=Sentencesjar main=true download=eagergt

ltresourcesgt

ltapplet-desc

name=Sentences Explorer V40150EE

main-class=comsentencesmainSentencesgt

ltparam name=ServletProtocol value=httpgt

ltparam name=ServletPort value=8090gt

ltparam name=FixedProfile value=nogt

ltparam name=EditOption value=Schemagt

ltparam name=ImageURLBase value=ImagesForSentencesgt

ltapplet-descgt

ltsecuritygt

ltall-permissionsgt

ltsecuritygt

ltjnlpgt

If a suitable version of the Java Runtime Environment is available then the generated

URL link will use the broswer plugin to launch a Java Web Start application according to

the JNLP file ltsentences_homegtTomcat4webappsSentencessentjnlp

The jnlp file contains parameters to customise and configure the particular client

behaviour and defaults (see below) If you wish to set up several different jnlp files then

alternatives to the default can be passed in as a second parameter to the writeLaunchHTML

method

The following JNLP configuration file is the example that is installed to launch Sentences

with the default settings It is the file located at ltsentences_homegtTomcat4webappsSentencessentjnlp

The JNLP file has an XML format The items in bold will differ depending upon the

installation Here are details of its contents

The name of the file must be included in the root jnlp element as a href attribute

bull information

The information element is used to describe the Web Start Application These can be

customised for specific application requirements The icon and title are used when a

desktop shortcut is created



deployJavawriteLaunchHTML(launchInfo myJNLPjnlp)

)

ltscriptgt

ltdiv class=headinggtSentences Explorer Clientltdivgt

ltdiv id=launchInfogt

ltpgt

46



bull update

The update element is used to indicate the preferences for how application updates should

be handled by the JNLP Client The default is to check for a new version in the

background

bull resources

The resources element is used to indicate which version of the java runtime environment

is required and which Java archive files are needed to run the client For the Sentences

Client only the Sentencesjar file is required

The java-vm-args attribute is used to specify aguments for the client to use If more

memory or stack is required or a different locale it can be added here The default value

is -Xss1m

The memory parameters are in the format -Xmx512m ndashXms512m where -Xmx specifies the

maximum system memory that can eventually be used (shown here with the example

value 512m meaning 512MB) and -Xms specifies the initial amount of memory to be

allocated









-Dusercountry=ltcountry codegt

-Duserlanguage=ltlanguage codegt

-Dusertimezone=lttimezone codegt

For example a user in Chicago might use

-Dusercountry=US -Duserlanguage=en -Dusertimezone= AmericaChicago

bull applet-desc

The ltapplet-descgt xml element is used to describe the Sentences client defaults and

configuration These are the same as the applet parameters described in the ldquoSentences

applet parametersrdquo and ldquoAdditional optional parametersrdquo With the exception that the

main-class=rdquocomsentencesmainSentencesrdquo parameter is used in place of the code

lsquocomsentencesmainSentencesrsquo parameter



for servlet access These parameters can be referred to using the Client API triggers and

query expressions

These parameters can also be added to the Applicationproperties file for use with


Format of user-defined parameters

The name and value of a user-defined parameter are specified in the same way as other

parameters in the JNLP file or javascript

When using a jnlp file the a user-defined parameter is defined as follows

ltparam name=ClientParameter1 value=UserParamName=UserParamValuegt

47



When using the javascript library a user-defined parameter is defined as follows

ClientParameter1rsquoUserParamName=UserParamValuersquo

The list of parameters are separated by commas

In the Sentences Personal Edition user-defined parameter is defined in the

Applicationproperties file on a single line as follows

ClientParameter1=UserParamName=UserParamValue

Pre-defined names

User-defined parameters use pre-defined names which must be in the form

ClientParameter1 ClientParameter2 and so on These names are not case-sensitive

and there is no practical limit to the number of parameters that can be added The pre-

defined parameter names must be used in sequence with no omissions For example if you

used the sequence of names ClientParameter1 ClientParameter2 ClientParameter4

only the first two entries would be recognised as ClientParameter3 is missing from this

sequence

User Parameters

The name part of the user parameter (UserParamName in the example above) is not case

sensitive Any characters except the equals sign (=) and the double quote () may be used

in parameter names

Sentences ignores any leading or trailing spaces in parameter names If any duplicate

parameter names are used Sentences processes the first one and ignores all the others

Missing values in user parameters are treated as null values

Referring to user-defined parameters

You can refer to user-defined parameters using the Sentences Client API triggers or

query expressions

User-defined parameters in the Client API

The Sentences Client API includes getClientParameter and setClientParameter

methods For more information on using the Sentences API see Sentences API overview



ltSentences_homegtDocapihtml The Javadoc files for the Sentences API can be found

in ltSentences_homegtDocjavadoc

User-defined parameters in triggers

A getClientParameter method is available to Sentences triggers For more information

on triggers see Triggers

User-defined parameters in query expressions

You can use the GetClientParameter method in query expressions For more details see

ldquoUsing user-defined parametersrdquo


You can use the Sentences statistics servlet to monitor server activity For more

information see Appendix B ldquoStatistics and analysisrdquo

Shutting down and restarting the Sentences server

Sentences operates in three modes Sentences Personal Edition is a single-user desktop

application that you run and exit as any other desktop application

48


Certain processes require exclusive access to the Sentences database You must shut

down the Sentences server before performing any of the following actions and restart the

server when the action is complete Certain processes require exclusive access to the

Sentences database You must shut down the Sentences server before performing any of

the following actions and restart the server when the action is complete

import a CSV file

export a profile

import a set of chapters

install a trigger or custom datatype

make changes to the Serverproperties file or Applicationproperties file

install a new SentencesLicensetxt license file

The steps required for shutting down and restarting the Sentences server vary with the

Sentences edition you are using as described in the table below

When you are usinghellip restart the server as followshellip

Sentences Personal Edition Shut down and restart the Sentences PersonalEdition

Sentences Enterprise Edition local

mode

Stop and restart the Sentences Web Application in

your Web Application Server If you are using Tomcat

you can use the Sentences Launcher application to

stop Tomcat You do not need to close the Sentences

client but if you do not you must refresh the profile

after you restart the server

Sentences Enterprise Edition Web

mode

make sure no users are connected to the Webserver

and then restart the Sentences web Application

Users should either close and restart the Sentences

client or refresh the profile

49




It is always good practice to keep a backup copy of all your data The data in your

Sentences database is stored in chapter files which can be backed up in a number of

ways You should also back up the system chapter Profileschap which records

information about the profiles in your database and the Schedulerchap which contains

any scheduled server processes It is good practice to keep an independent record of the

profiles in your database and of the chapters used in each profile

Sentences offers you a number of ways to back up your Sentences database which are

explained in the following sections

Online backup

Online backup is not available in the Sentences Personal Edition

Online backup is a command line procedure that creates a backup file from all your

chapter files and profiles and uses journalling to maintain data integrity during the backup

procedure You can run online backup without the need to shut down the Sentences

server Online backup may be initiated by automated procedures

Online backup preserves the complete record of all the updates made to your chapters

When you restore your data from an online backup the resulting chapters are exact

duplicates of the original chapters

You can run online backup from any system that can communicate with your Sentences

server using HTTP If you wish to limit access to running the backup program you must

use the security mechanisms of your Web server to do so

The backup client communicates with a Backup servlet on the server With the default

installation of Sentences using Tomcat this servlet has the servlet name Backup and is

accessed locally using the URL httplocalhost8090SentencesBackup (see

Servlet access to Sentences ) When using any other Web server installation the

administrator must configure the Backup servlet in the same way as all other sentences

servlets The classname of the backup servlet is comsentencesbackupBackupServlet

The backup command script file (Backupbat on Windows or Backupsh on Linux

Unix) in the Sentences installation directory assumes that the command is being executed

on the same machine as the server and that the default Sentences configuration is being

used and uses the URL httplocalhost8090SentencesBackup to connect to the

servlet

Note If you chose Custom installation when you installed Sentences and specified a

different port number for Tomcat HTTP access then that port number is used rather than

8090

If you have installed Sentences into another Web server you need to edit the Backupbat

or Backup shell script to set the -url parameter to the appropriate value

Preparing to run online backup

Before you can run online backup you must verify or edit two settings in the


You must define the destination for the backup files in the BackupPath

parameter This path cannot be changed when the procedure is run By default

this parameter is not set

You must ensure that access has been granted to the Backup servlet in the

servlets section the appropriate entry must read BackupAccess=true

50



This is the default setting

For more details see The Serverproperties file

Using the online backup command

The Sentences server must be running when you run the online backup command

To perform an online backup open a command prompt navigate to the Sentences


named Backupbat and on Unix Linux systems the file is named Backupsh

You may specify a name for the backup by entering it after the command as follows Backup [-name backupname]

where backupname is an optional name used for the two files created by the backup

operation the backup file (with the extension bkp) and the journal file (with the extension

jnl)

For example if you specify the name mybackup the files created are named

mybackupbkp and mybackupjnl

If you do not specify a name the backup files are identified by a name indicating the date

and time of the backup For example if you started a back up on 15th March 2002 at

113023 the files created are named 20020315113023bkp and 20020315113023jnl

The backup operation copies all the Sentences chapter files including the system files

Profileschap and Schedulerchap The backup process copies each file in turn to the

backup file and records any changes to files that take place during the backup process to

the journal file This ensures that the combination of the backup file and the journal file

represent an accurate record of your database at the end of the backup process

Restoring your data from an online backup

You need to have exclusive access to the Sentences server when you restore from an

online backup

To restore from an online backup open a command prompt navigate to the Sentences


named Restorebat and on Unix Linux systems the file is named Restoresh

The following commands are available

bull Restore -display

This produces a summary of the backup file sets that are available

bull Restore -display [backupname]

This displays the details of the backup file set with the name you specify including the

name of the server the date when the backup was made and a list of chapters and their

locations

bull Restore [-overwrite] backupname

This starts the restore process with the given backup name If the restore involves

overwriting any existing chapters (other than the profile chapter) then the procedure

displays a list of the affected files and does not perform the restore You must use the -

overwrite switch to force the procedure to overwrite files

If your installation uses multiple locations for chapter files all the locations must be

available when you run the restore process If the original locations for some files are not

available during restore copies of these files are created in available locations The

resulting files are exact duplicates of existing chapter files When all your locations later

51

Using trace files


become available Sentences is unable to start because of these duplicate chapter files (see

Error 1267 The Sentences database is not available )

Exporting the database for backup

You can back up your data by exporting the database An exported database can later be

imported into Sentences For further details and restrictions on using export for backup

see the section Exporting and importing databases The Sentences server must be shut

down before you can export the database

Copying chapters for backup

You can back up your data by copying chapter files If you want to use a copied chapter

file in a different Sentences installation you need to create or edit a profile to use the

chapter Chapter files should not be copied while the Sentences server is running If the

server is not shut down the integrity of the copied files is not guaranteed For further

details and restrictions on copying chapters for backup see the section Deploying profiles

and chapters

Using trace files

Sentences trace files store server activity information They often contain valuable

diagnostic information that can be used to establish where an error occurred particularly

where a problem exists in client-server communication (see Errors reported at the

Sentences client )

The TraceLevel variable in the Serverproperties file determines which activities

generate messages to the trace file The basic settings are shown below

Value Meaning

0 Only major events are traced

1 Profile operations are traced


4 Requests from clients to update data are logged withoutthe prior




16

All server update actions are logged whether they came directly from a


being run




256

A one-line summary of Client Parameters is logged This is only

available if a one-line summary of every request is logged (trace level

2)

The trace levels can be used independently or in combination simply by adding together

their numeric values for use as the server trace level

The default setting for TraceLevel is 0 (zero) which is appropriate for general use An

effective setting for monitoring server activity in more detail is 23

When TraceLevel is set above zero the size of the trace files can grow rapidly so you

must ensure that there is always enough disk space for trace file usage

Every time you start the server a new trace file is created Trace files are named

trace_nnnnntxt where nnnnn is a positive integer 12 or 13 digits in length for

example

52



trace_938079391280txt

The integer value used is the elapsed time in milliseconds since the Java system epoch

(midnight GMT 1st January 1970)

Sentences log files

Sentences creates a log file for every open chapter in the same directory as the chapter

file Sentences writes information about changes in a chapter file to the log file before

data changes are made to the chapter file This allows Sentences to maintain the integrity

of the chapter file You must not delete Sentences log files

Every time that a sequence of chapter actions that makes up a transaction iscompleted

Sentences ensures that the chapter file is written to disk which enables the size of the log

file to be reduced If the size of the log file reaches the limit set by the optional

MaxLogSize property in the Serverproperties file the chapter file is immediately

written to disk and the log file is truncated This means that very long transactions such as

those created by the CSV Import program can be handled without requiring excessive

amounts of disk space for the log file

When the chapter file is closed normally the log file is removed If Sentences terminates

unexpectedly then the next time that Sentences is started the log file is used to ensure the

integrity of the chapter file contents If Sentences terminated unexpectedly because of a

lack of disk space you must make more disk space available so that the chapter file can

be recovered correctly

The log file name is generated by removing the chap suffix from the chapter file name

and adding a log suffix instead Log files are binary files and cannot be read directly The

Sentences administrator must make sure that there is enough disk space available for

these files


There are several possible Clients for the Sentences Server The Server provides several

Java Servlets for different purposes For example there is an XML servlet and an

XMLSchema servlet that can be accessed to provide a CrystalReports ldquoclientrdquo with XML

data to be rendered into a Crystal Report The XML servlet can also be used to transform

the retrieved data into html utilising any javascript libraries to render graphs tag clouds

etc



or used as stand-alone desktop applications using the Java Web Start technology If a Java

Web Start application is used then a desktop shortcut can be created for subsequent

launching of Sentences client independently from a browser



No installation is required on a client computer other than the Java Runtime Environment

This includes the Java Plug-ins that browsers use to display the applet embedded in an

html page

Starting the Sentences client

The default Tomcat test server installation of Sentences and the default Web Archive file

for deployment to a Web Application Server are both configured with a ldquowelcomerdquo html

page launchhtml

To open this page start your Web browser and navigate to the root context of the

Sentences web application The address of your server depends on your configuration

53



If you are running Sentences Enterprise Edition in local mode (with the client and server

running on the same computer) the default address is

httplocalhost8090Sentences

This will be automatically redirected to the welcome page at

httplocalhost8090Sentenceslaunchhtml

If you are running the Sentences Enterprise Edition in Web mode (with the client and

server running on different computers) the default address depends on your system

configuration You need to know the following details of how your systems Web server

has been configured

The hostname (or IP address or networked server name) of the Web server

The port your Web server is listening on for Sentences HTTP connections

The servlet context for Sentences on your Web server

For example the Tomcat Web server as configured by the Sentences installer uses the

name Sentences as the servlet context and is configured to listen for Sentences requests

on port 8090

If you wish to identify the Sentences server by its IP address you would specify the

address in the URL For example if the IP address is 123123123123 the URL for

accessing Sentences would be

http1231231231238090Sentences

If the Sentences server you wish to specify is a computer named myserver on a local

network the URL for accessing Sentences would be

httpmyserver8090Sentences

If the Sentences server you wish to specify is a computer named servermyispcom on a

distant network the URL for accessing Sentences would be

httpservermyispcom8090Sentences

All of the above assumes that the Web server for Sentences is listening on port 8090

which is the default port with which Tomcat is installed If the default HTTP port of 80 is

used the port number (8090 in the examples above) does not need to be specified See

ldquoAdditional optional parametersrdquo for details of how to configure the ServletPort and

ServletContext parameters for the Sentences client

Java Runtime Environment Plug-in

Before you can run the Sentences client you must have the Java Standard Edition

Runtime Environment (JRE) installed and enabled

The launchhtml page uses a javascript library to detect whether the client machine has a

suitable JRE installed It will be able to automatically install or upgrade the JRE version

or give the user instructions on how to do this

If the client machine has a suitable JRE then a link will be provided to launch the

Sentences client using Java Web Start technology This will install a shortcut to the

desktop for future use without a browser This does not prevent the user from using the

link each time if they wish

Security and certificate acceptance

Application digital certificates

The Sentences Personal Edition and the Sentences Test Server application are both

digitally signed to authenticate that the software is genuinely from Lazysoft Ltd

54



On Windows the User Account Control mechanism may prompt you to confirm running

the application You may also be asked to confirm access through the firewall to the Java

Runtime Environment

Java Applet Security

The first time you access a Sentences client either as an applet or an application you must

accept the digital certificate for Sentences The Java Runtime Environment (JRE) displays

a warning dialog You will be asked to confirm that you wish to run the application

Depending upon the Operating System you may be offered the ability to ldquoAlways trust

content from this publisherrdquo which we recommend so that you are not asked to confirm

each time you run the application

Using the Java Console tool

Useful debugging information is displayed in the Java console tool

Activating the Java Console on Windows systems

To display the Java console tool each time you start Sentences start the Java Control

Panel from the Windows Control Panel The Advanced tab expand the Java Console

item and select Show console Click OK or Apply The next time you start Sentences in a

browser the separate Java Console messages window is displayed

Activating the Java Console on Unix Linux systems

You can display the Java Console on Unix Linux systems by entering a command at a

shell prompt or by entering a URL in a Web browser

Using a shell prompt type in the following command

usrjavabinControlPanel


With a web browser use the following URL

fileusrjavaControlPanelhtml


Errors reported at the Sentences client

If the connection between the Sentences server and the Sentences client is temporarily

interrupted or if the Sentences server is not readily available the client cannot

communicate properly with the server and Sentences displays an error message in the

client Message Log The most common messages are described below

Error 1222 Your server connection has expired

This error message continues Please select the Refresh command from the File menu to

continue

Sentences displays this message when the ProfileTimeout or PendingTimeout limit

configured in the Serverproperties file has been passed or when the Sentences server

has been stopped and restarted while a Dataform remained open on a client and an

attempt to save the data on an open Dataform fails

After you select the Refresh command you must re-enter any data that was on an open

Dataform





55



This message is displayed when the Sentences server cannot be found It usually means

that the server has been shutdown

If this message is displayed you must restart the Sentences server and select the Refresh

before continuing to work with Sentences (see ldquo Shutting down and restarting the

Sentences serverrdquo)





This message is displayed when the Sentences Servlet has not been configured correctly

for example an entry for MainServer does not exist in the webxml file

If this message is displayed you must check your servlet configuration settings (see

ldquoSentences servlets and web server securityrdquo) and then restart the Sentences server (see

ldquoShutting down and restarting the Sentences serverrdquo)





This message is displayed when the Sentences servlet cannot start correctly The most

common causes of this error are that the Sentences servlet has stopped without shutting

down correctly or that the Sentences server has detected two or more chapter files with

the same internal identifier In both of these cases you cannot start Sentences and you

must check the trace file for more details

Sentences not shut down correctly

When a user opens a profile that uses one or more chapters on a particular file server

Sentences creates a databaselock file in each Chapters directory This file is deleted

automatically only when the Sentences server that created it is shut down If the server is

not shut down correctly the databaselock file remains and you cannot start the server

If the Sentences server has detected a databaselock file the trace file displays information

similar to the following


comsentencesapiexceptionsLazyServerConflictException 10016 A lock file

(databaselock) already exists in the Chapters directory CSentencesData40

Another Sentences server process or stand-alone process may be using this

database Check for other running processes If there are none remove the lock

file from your Chapters directory and re-start

If you see this trace file message you should shut down the Sentences server and then

check the chapters directory to see if a file named databaselock is present If you have

specified more than one location for your chapter files you must make sure that you

search all of the possible locations

Note A file named databaselock is always present while the Sentences server is

running

The Sentences backup command may also report the error 10016 shown above This

means that the backup process has found a databaselock file in the chapters directory

specified in the error message This error may occur even if the databaselock file is in a

chapters directory not used for the applications you are backing up

If you find one or more databaselock files present when the Sentences server is not

running you should delete them and then restart the Sentences servlet (see ldquoShutting

56



down and restarting the Sentences serverrdquo) You may also need to consult the

documentation for your Web server and your servlet container You must not delete a

databaselock file while the Sentences server is running

You can determine the validity of a databaselock file by checking the timestamp

indicating when the file was created If the files timestamp shows that it was created

before the last time you re-started Sentences then it can safely be deleted

Duplicate chapter files

This error is also displayed when the Sentences server detects duplicate chapter files

Duplicate files usually have different system names but are recognised as duplicates

because they have the same internal identifier

If the Sentences server has detected two or more chapter files with the same internal

identifier these files are listed in the trace file The trace file displays information similar

to the following


comsentencesapiexceptionsLazyDBException 10189 The chapters

CSentencesData40Human resources datachap and CSentencesData40Human

resources databchap are duplicates



message you should contact the person in your organisation who is responsible for

running the Sentences server and report this error

This message is displayed when there has been an attempt to access functionality that has

been disabled in the Serverproperties file For example if you have disabled access to

XML output by setting XMLAccess=false in the Serverproperties file this message is

returned if you attempt XML access In addition the trace file contains a message such as

Access to XML is forbidden

Error 1272 A connection error has occurred

This error message continues Please contact your administrator quoting the code

[codenumber] If you receive this message at a Sentences client you should contact the

person in your organisation who is responsible for running the Sentences server and

report this error quoting the code number displayed

This message is displayed when a client-server connection problem other than those

specified by errors 1265 1266 1267 or 1268 occurs The code quoted is a HTTP

response code that describes the error that has occurred HTTP error codes are widely

documented including on a number of Web sites and administrators should check this

documentation for help in identifying the cause of the problem

This error is also displayed at the client if the SentencesLicensetxt file is missing or

corrupted

Contacting Technical Support

If the recovery information given for the error messages listed above does not resolve

your problem or if you receive a different error message you should contact

supportsentencescom

Before contacting Technical Support please review the configuration information in this

chapter and make sure you have access to the following files

Serverproperties launchhtml

senthtml

and that you also have access to any trace files

57




You should be aware of the security implications of running applications over the Web or

over internal systems using Web communications protocols There are a number of ways

in which Sentences helps you to minimise any security risks These include an automatic

check of the HTML page host using different profiles for different users and limiting

access to Sentences servlets Security considerations for servlets are discussed in

ldquoSentences servlets and web server securityrdquo You can also set passwords to protect

chapter files (see ldquo Password-protected chapter filesrdquo)

Automatic check of HTML page host

To enhance the security of Web-based access to the Sentences server Sentences

automatically checks that the web page has been loaded from the same server as the

Sentences applet used by the client

Error 1403 The Sentences client must be loaded from the same host

as its HTML page

This error message is displayed if Sentences finds that the web page has not been loaded

from the server on which the Sentences servlet is running

Using database views for enhanced security

An additional level of security is afforded by changing the combination of chapters in

different profiles as described in Creating database views using profiles and chaptersrdquo

You can create different html start pages for different users or groups of users to open

different profiles and each would have the FixedProfile parameter set to True This

would prevent users from accessing a profile they were not entitled to use

In addition you can use the security features of your operating system or web server (or

both) to limit user access to each of these html files by granting or denying

permissions or by requiring a password


This section gives reference information that may be useful for system designers system

administrators and user administrators

Version 40 of Sentences introduces a User Security Model Whilst those familiar with

User Security will be familiar with the terminology used there are several subtle

differences between User Security partially defined by SQL standards and those in

Sentences

Sentences uses a Role based system where Users are granted abilities through Built-in and

Custom Roles Privileges are granted to Roles not Users Users are given Roles This

abstraction makes the maintenance of Users easier and more efficient

Users and roles

There is only one built-in User in the system System Administrator is the only user who

has the ability to perform any function There is only one System Administrator and

System Administrator privileges cannot be granted to any other user

User Entities have the names used to authenticate with The also have the following

associations

bull (User display name Text)

This is the name displayed in the client rather than the username used to log in with

58



bull (User password Password)

bull (User locked Yes)

Whether the user has been locked out This can be either because of too many incorrect

login attempts or set manually by a User Administrator

bull (User last profile Profile)

The last profile used by the user is stored for use next time they use Sentences If the

client does not specify a default profile then the last profile used by the user is loaded

bull (User force password change Yes)

When creating a new User or resetting the User they are automatically forced to change

their newly assigned password The User Administrator can manually set or unset this

association

Associations inherited from Role

bull (Role role Role)

Any number of Roles can be assigned to the User As Roles can be assigned to other

Roles hierarchies of Roles can be created

bull (Role description Role)

Each Role can be given a description Users inherit this association which can then be

used if the User represents an Application rather than an individual

bull (Role fixed profile Profile)

Each Role can specify a profile which is the only profile that is available to the users with

that Role They will not be prompted to choose a profile and their Sentences Explorer will

not include menu items to change edit create or delete profiles

bull (Role edit option Edit Option)

Each Role can be given an Edit Option

The edit option specifies what parts of the database can be edited by users The possible

values are Schema Query Data and None


parameter the default setting is Schema

If the edit option is set to Data or None users can create edit and execute queries but

they cannot save any changes they make to queries

The built-in Roles are

bull Profile Editor

A Profile Editor can view create drop and alter any Profile

bull Chapter Editor

A Chapter Editor can view create and alter any Chapter

Edit Option Editing actions allowed





59



bull Schema Editor

A Schema Editor can create drop and alter any Type or Query

bull Data Editor

A Data Editor can insert delete and update any Instances

bull Sandbox User

A Sandbox User can use the Sentences Sandbox functionality for testing purposes

bull Scheduler

A Scheduler User can manage server processes to be run at scheduled times and dates

bull Transaction Visibility User

A Transaction Visibility User can set a Timestamp that determines the visibility of

committed transactions

bull User Administrator

The User Administrator Role allows access to Manage Users and Roles

When new Users are created they are assigned a default set of Roles These defaults can

be customised See the User Security Reference section for details

Only the System Administrator or User Administrators (Users with the User

Administrator Role) can Administer Users This is done either by opening the Profiles

Profile or from the File menu by selecting Administer Usershellip

bull Public

The Public Role allows anonymous access to Sentences

Anonymous access to Sentences

By default Sentences requires users to authenticate themselves with a user name and

password in order to use the system There is however a mechanism available to allow

anonymous login This has to be enabled on the server before any requests by a client will

be granted See the User Security Reference section for details of how to enable

anonymous login on the server

Each client needs to specify the anonymous login as a parameter See the Client

properties section for details

If a client has requested anonymous login and the server is set to allow it then the user

will automatically be logged in with the role of Public The privileges assigned to Public

can be changed in the same way as any other Role

Creating a new role

It is likely that you will wish to create several roles for groups of Users to give them

access to one or more Sentences Profile The access may be read-only or grant them the

ability to make data or schema updates

Roles can be organised into a hierarchy so that basic abilities can be layered and built up

To create a new Role follow these steps




are administered



60



2 Once the Profiles Profile has open select the Role Entity Type in the schema


3 You must enter a Name for the Role

4 You may optionally add any other Roles that you wish this Role to inherit from

5 You may optionally enter a description for this Role

6 You may optionally enter preferences for this Role

7 You may optionally select an Edit Option and Fixed Profile for this Role

8 Select the Privileges tab

9 You may add individual profiles or select All Profiles to the View profile list

10 You may select whether or not users with this role can create or drop (delete)

profiles

11 You may add individual profiles or select All Profiles to the Alter profile list

12 You may select whether or not users with this role can create chapters

13 You may add individual chapters or select All Chapters to the Alter Chapter list

14 You may select whether or not users with this role can use the Transaction

Visibility functionality

15 You may select whether or not users with this role can use the Sandbox

functionality

16 To set schema and data privileges on one of the Profiles from the View profile

list (including the All Profiles item) select it and either double click it to open its

child dataform

61



17 The first page of the child dataform is for Schema Privileges You may select

whether the user can create and drop types

18 You can add individual types to the list of types that can be altered This includes

two built-in items for All Entity Types and All Association Types

19 You may select whether the user can create and drop queries

20 You can add individual queries to the list of queries that can be altered This

includes the built-in item for All Queries

62



21 The second page of the child dataform is for Instance Privileges

22 There are three lists for granting permission to Insert Delete and Update

individual instances or you can select the built-in item All Instances

23 Apply and close the child dataform and save the New Role Dataform

Creating a new user

To create a new User follow these steps




are administered





3 You must enter the identifier that the user will use to log in into the User field

Note that this is different to the name displayed in Sentences

4 The default Roles assigned to new users will be displayed You can add or

remove any roles for this user

5 If this user represents an application you may enter a description

6 The privileges tab is the same as for Roles It is possible to define specific

privileges here but usually privileges are assigned via the role(s) that are

assigned to the user See the previous section for how to assign individual

privileges

7 Select the User tab

8 You must enter a display name for the user

9 All other properties can be left with their default values

10 Select save to save the new user

11 Once you save the user a dialog will open for you to enter the initial password

for that user This will be a one-time password and the user will be forced to

change it when they first log in

63



12 You may choose to generate a random password by selecting the Generate

Random button

13 Ensure that you make a note of the password as it will not be visible in the

system afterwards

Resetting a locked user

If a user fails to log in more than the allowed number of times (See the User Security

Reference section for details) they will be locked out

A User Administrator can unlock a user This clears the locked flag and allows you to

specify a new one-time password and force the user to change password when they next

log in

To reset a User follow these steps




are administered




pane and then locate the user in the data pane and select them

3 Open the context menu for the user and select Reset User The Reset user dialog

will be opened

4 Enter a new one-time password or generate a random password by selecting the

Generate Random button Ensure that you make a note of the password as it will

not be visible in the system afterwards

5 Select Reset

6 The user will be unlocked given the new password and have the force password

change property set to yes

System Administrator Lockout

If any Sentences User forgets their password and locks themselves out the System

Administrator can reset their password If the System Administrator forgets their

password the following mechanism allows them to reset without having to re-create the

entire Profiles database

The mechanism allows the System Administrator to enter the original password that is

encrypted into the Licence file and force a new password to be set This is only possible

with physical control over the installation The trigger for this reset action is to place an

64



empty text file in the system chapter directory (or the first chapter location if one is not

specified) with the name resetadminpassword

The procedure is to

1 Shut down the server

2 Create the empty text file named resetadminpassword and place it in the

system chapter directory

3 Start the server again

4 Log in as System Administrator with the password encrypted in the license file

5 Enter a new password when prompted

6 The resetadminpassword file will be removed automatically

Privileges

Relational Database Standards for Security use a set of privileges to grant access to view

update and delete schema and data Sentences follows this standard where appropriate but

includes some additional functions specific to the Sentences database architecture

Privileges exist to

View individual Profiles

View all Profiles

Create Profiles

Drop Profiles

Alter individual Profiles

Alter all Profiles

Create Chapters

Alter individual Chapters

Alter all Chapters

Allow transaction visibility

Allow sandbox mode

For each individual Profile granted View privileges (or all Profiles) there are Further

Schema and Data Privileges

Schema Privileges exist to

Create Types

Drop Types

Alter individual types

Alter all Entity Types

Alter all Association Types

Create Queries

Drop Queries

Alter individual Queries

65



Alter all Queries

Data Privileges exist to

Insert individual Instances

Insert all Entities

Insert all Associations

Delete individual Instances

Delete all Entities

Delete all Associations

Update individual Instances

Update all Entities

Update all Associations

See the section on creating a new Role for details of how to set these privileges

A userrsquos view of an associative database is defined by the profile that they are using A

profile defines a set of chapters and the sum of their contents is the userrsquos view A user



design

An existing mechanism for defining visibility of and access to schema and data is to

combine chapters into different profiles for different sets of users

Combining chapters example

Let us imagine you have a human resources database You wish to provide an application

for general Human Resources personnel to view employee information You also wish to

provide an application for managers to maintain employee appraisal information

You could design your database with one chapter to hold the core schema for your human

resources and another to extend that schema for sensitive appraisal information

With this modular approach you can then create two profiles The first only includes the

core schema and does not have any target chapters for changes and is thus read-only The

second profile would include both schema chapters and a data chapter as the target for

appraisal data

It is possible to use privileges to limit visibility and access of schema to achieve the same

result and you must assess which is the more appropriate for your situation A modular

design of combining chapters is easier to maintain whilst User roles and privileges allow

greater flexibility

The current user

The currently logged in user is shown in the title bar of the Sentences Explorer

Sentences Queries and the Sentences API have been extended to include functions to

retrieve the current user and evaluate whether they have been granted particular roles

This allows the database designer to adapt the behaviour to different users or roles

bull GetCurrentUserID()

This function returns the username of the currently logged in user the identifier they use

to log in with

66



bull GetCurrentUserName()

This function returns the display name of the currently logged in user

bull CurrentUserHasRole(ltrole namegt)

This function returns whether or not the currently logged in user has been granted the role

specified by the passed parameter

Combining chapters example continued

In the human resources example from above we would only wish team managers to have

access to appraisal information for their team The visible appraisal information could

either be filtered by manager id name or role

In this situation it is more likely that you would use Sentences Business Rules to describe

and enforce the desired behaviour See the section on Business Rules

User security parameters

The Serverproperties file

The following parameters in the Serverproperties file are used by the User Security

System

bull AnonymousLoginAllowed

You may use this truefalse property to specify whether the Server will allow requests to

log into Sentences anonymously Even if the client requests an anonymous login unless

this property is set to true anonymous logins will not be granted

bull MaxLoginAttempts

You may use this property to set the number of attempts that will be allowed before the

user is locked out The default is 3

bull MinPasswordLength

You may use this property to set the minimum number of characters to be entered as a

password The default is 9

bull DefaultRoles

You may use this property to set the Roles that a User is given when created The default

installation of Sentences has default roles Profile EditorChapter EditorSchema

EditorData Editor

If Custom Roles are created these can also be used in this list of default Roles

Client properties

The following parameters are used in the Applicationproperties file for the Personal

Edition and in the client HTML applet or JNLP configuration file for Enterprise Edition

Clients

bull AnonymousLogin

You may use this truefalse property to specify whether the Client should connect to the

server as the Public User without asking for login credentials from the user This will only

be honoured if the server has been configured to allow this


You may use this property to specify a background colour to be used for the Login Screen

if you are customising it for your application or set of applications For example a value

of ldquoFFFF40rdquo would make the background a Yellow background

bull LogoImage

67



You may use this property to specify a Logo to be used for the Login Screen if you are

customising it for your application or set of applications For example a value of

ldquologogifrdquo would use that GIF image

bull LogonTitle

You may use this property to specify a Title to be used for the Login Screen if you are

customising it for your application or set of applications For example a value of ldquoACME

Applicationrdquo would use that as the title


In many situations the best way for users to access the Sentences server is by running the

Sentences client applet in a Web browser

It is also possible to access the Sentences server directly using a servlet A number of

different servlets are supplied with Sentences which are listed below Because of security

considerations some of these servlets are disabled when you install Sentences Security

considerations are discussed in Sentences servlets and web server security

URL patterns and Servlets available in Sentences

The following table lists of the URL patterns that correspond to various Sentences

features and shows the status of each servlet on installation The URL patterns marked as

always enabled are essential to Sentences and cannot be changed All the other URL

patterns are listed in the Serverproperties file and you can change their status by

changing the corresponding access parameter from false to true or from true to false

You should always check the Serverproperties file for an up-to-date list of theURL

patterns and servlets currently available

68



URL pattern Servlet name Enabled by default Sentences feature

MainServer Main Always Access to Sentences from


SavedXML

XmlSavedRespon

se

Always XML export requested by


ApiServer Main Yes Access to Sentences from

user-written programs using

the Sentences client API

Statistics Stats Yes Sentences server statistics

Chapter ChapterStats No Sentences chapter

statistics

Spatial Spatial Yes Data for the spatial view of

a Sentences chapter

DTD XmlDtd Yes

Export of XML DTDs


Schema XmlSchema Yes Export of XML Schema


XML XmlOutput Yes Export of XML documents


ImportXML XmlInput Yes Import of XML documents

Backup Backup Yes Enables online backup

Sentences servlets and web server security

The Sentences client applet is loaded from an HTML page which means that the

administrator of a Sentences Web site can apply security constraints to the relevant

HTML page to make sure that only authorized users can access Sentences data and that

each user is restricted to appropriate profiles

Users who access Sentences data using the Sentences API or the XML import and export

features do so directly by communicating with a servlet and so any security controls

applied to an HTML access page does not apply to them

Sentences addresses these security problems by introducing distinct URLs for different

kinds of database access The effects of this approach are

Individual features can be enabled or disabled by setting the corresponding access


Web site administrators can use the security features of their web servers to place security

constraints independently on each feature in some cases down to the level of a profile or

even an individual query within a profile

Web site administrators can use web server security features to control access to the URL

patterns used by the servlets listed above In some cases such as XML export the full

URL includes a profile name and a query name which allows the administrator even

more detailed control by restricting access to specific URLs

69



For information on how to restrict access to a specific URL on your web server using

security constraints please consult your web servers documentation

Enabling and disabling servlet access

A full list of servlet access features showing which ones are enabled and which ones are

disabled on installation is given above (see URL patterns and Servlets available in

Sentences )

To enable or disable servlet access for a particular feature you must edit the


For each servlet that you want to enable you must change the corresponding access

parameter from false to true For each servlet that you want to disable you must

change the corresponding access parameter from true to false


To uninstall Sentences on Windows platforms and the Tomcat Web server installed with

it use the AddRemove Programs option in the Windows Control Panel

After running the uninstall procedure you must make sure that you delete the

ltSentences_homegt directory using the Windows Explorer

You can uninstall Sentences on Unix Linux platforms by running the UninstallSentences

script which can be found in ltSentences_homegtUninstaller or by deleting the


71



Chapter 2


This chapter is an introduction to the associative model for database designers who

want to work with Sentences More detailed information is available in the book The

Associative Model of Data by Simon Williams available from wwwsentencescom

Sentences is the first database product to implement the associative model of data

which is radically different from the relational model of data which currently

dominates the database market This chapter looks at some of the basic concepts of

the associative model including

bull entities and associations

bull values

bull types and instances

bull contrasts with the relational model


The associative model of data allows you to record information about independent things

in the real world (entities) and about their interactions (associations) An entity represents

a thing in the real world that has a discrete independent existence In contrast an

association represents a link or interaction between two other things each of which may

be an entity or an association An association represents a thing in the real world which

does not have an independent existence but is always dependent on other things

Some examples of entities and associations may help you understand the differences

between them Houses people bicycles and buildings are all examples of entities

Customers husbands and headquarters are all examples of associations A person may

fulfil the role of being a customer or of being a husband but even if that role comes to an

end the person remains a person

Take an imaginary company called Medway Furniture that has its main offices in

Riverbank House Riverbank House could be designated as the headquarters of Medway

Furniture But should Medway Furniture move away or go out of business Riverbank

House would not necessarily cease to exist It would merely cease to be the headquarters

of Medway Furniture The associative model sees Riverbank

House as a building entity and Medway Furniture as a company entity but it sees

Medway Furnitures use of Riverbank House as its headquarters as an association It

would be incorrect in the associative model to represent headquarters as an entity

because it does not have the necessary quality of independent existence

Any thing in the real world that can be described in terms of a link between two other

things can be represented in the associative model as an association The sentence John

Smith is a customer of Medway Furniture describes the interaction between a person

entity called John Smith and a company entity called Medway Furniture The phrase

is a customer of describes the nature of the interaction and in the terms of the

associative model defines an association

72



Figure 2-1 A simple association

In Figure 2-1 entities are shown as ellipses and associations as arrows The diagram

illustrates that in the associative model an association has three parts The first part is

referred to as its source here John Smith and the third part is referred to as its target

here Medway Furniture The middle part of the association here is a customer of is

referred to as the verb of an association Every association in the associative model must

have this source verb target structure It is the similarity between this structure and the

subject verb object structure of a common English sentence that gives the product

Sentences its name

Similarly when John Smith orders a table from Medway Furniture this too can be

described in an association

Figure 2-2 A more complex association

The diagram in Figure 2-2 shows a more complex association and illustrates one of the

strongest features of the associative model Associations are not only links between

objects in the associative database they are objects in their own right The is a customer

of association had an entity as its source and an entity as its target while the orders

association has another association as its source In the associative model an association

may be used as the source or the target of an association as easily as an entity

Since the source or target of an association may be an association the associative model

can have many associations nested within each other to whatever depth is necessary We

can write out a list of associations of increasing complexity to illustrate this For greater

clarity subordinate associations in nested groups are enclosed in parentheses there are

commas separating the source from the verb and the verb from the target and each verb is

in italics for example (source verb target)

bull John Smith is a customer of Medway Furniture

bull (John Smith is a customer of Medway Furniture) orders 6ft mahogany dining

table



John Smith

Is a customer of

Medway Furniture

John Smith

Medway

Furniture

6 foot

mahogany

dining table

Is a customer of

Orders

73

Entities and values




Sources and targets in the associative model are reusable This means that one association

or entity can be the source of many associations or can be the target of many

associations

Entities and values

Entities and associations are the two kinds of real world things that we want to record

information about in a database There are other things in the real world that we do not

need to record additional information about

Data items of this kind are known as values Numbers dates and times in the real world

do not have any qualifying attributes of their own and so in the associative model they

are treated as values

Look again at the last two examples of nested associations given above





The date 14th June 1999 and the price pound350 are examples of things that you do not

need to record any data about apart from the fact that they exist and so may be treated as

values

Since values by definition do not need to be defined or described by associations values

can only be used as the targets of associations and never as their sources Apart from this

restriction the behaviour of values is very much the same as the behaviour of entities

The distinction between entities and values is implemented in Sentences using the

datatypes mechanism Defining a group of data items as values in Sentences has far-

reaching consequences and in many cases the majority of data items in a database are not

values

Types and instances

So far this chapter has looked at examples of individual entities values and associations

The associative model generalises entities values and associations to entity types value

types and association types

Entity value and association types are used to develop the schema for an associative

database They are the main building blocks of associative database schema design

Any individual entity value or association is an instance of its respective type If you

create an entity type that is the source of a number of association types then any entity

that is an instance of that entity type may be the source of one or more associations that

are instances of the corresponding association types An individual entity does not need to

have all or any of the associations implied by the association types but if they do exist

they conform to the association types characteristics

The following diagram shows an example of an associative schema design

74



Figure 2-3 An associative schema

This diagram shows a schema design made up of entity types value types and association

types Using the same (source verb target) notation as before this schema could be

written out as follows

Person is a customer of Company

(Person is a customer of Company) orders Product

((Person is a customer of Company) orders Product) on date Date

((Person is a customer of Company) orders Product) at price Amount

Company has headquarters at Building

(Company has headquarters at Building) pays monthly rent Amount

This schema conforms to the principles of the associative model It has six association

types two value types (Date and Amount) and four entity types Some association types

in this schema have an entity type for their source and others that have an association type

for their source The Amount value type is the target of more than one association and the

Company entity type is the source of one association type and the target of another

Comparing the relational model and the associative

model

The associative model offers a different set of building blocks for schema design from

that offered by the relational model The principal building blocks of the relational model

are relations and domains while the building blocks of the associative model are entities

types value types and association types

Relations (also referred to as tables) are sets of rows that behave in accordance with the

rules of the database model For example each row in a relation must be unique and every

column must have a distinct name Domains are sets of values from which the values in a

column may be drawn An example of a domain is days of the week

In a relational database every table must ave a defined primary key and may include

foreign keys A primary key is one or more columns whose values are such that each row

can be uniquely identified A foreign key is one or more columns that serve as a primary

key in another table Foreign keys are used as a method of linking rows together to

implement many-to-one associations If you want to model many- to-many and one-to-

Is a customer of

On date

Person

Date

Amount

Product

Company

Building

Has

headquarters at

At price

Pays monthly rent

Orders

75



many associations in the relational model you must provide additional linking tables as

these types of association cannot be modelled directly

The associative model does not use keys In the associative database every entity or

association has a hidden surrogate that is assigned when it is created This is a unique

internal identifier which is never changed You can even change an entitys visible name

without affecting its underlying hidden surrogate

Because the use of surrogates has done away with the need for keys it is easy to

implement many-to-many and one-to-many associations as well as many-to-one

associations in the associative model narrowing the gap between the business model and

its implementation

Structural comparisons

The following statements are an attempt at a simple mapping of relational building blocks

to their associative counterparts These statements are generally true but there may be

exceptions in certain cases

bull A relational table that has no foreign keys among its primary keys can be modelled in an

associative database as an entity type that is the source of one or more association types

In other words an entity type that is the source of one or more association types is

equivalent to a table that has no foreign keys as primary keys It is likely that some parts

of the relations that would have appeared in columns in that table can be modelled as

association types having this entity type as their source

bull A relational table that has one or more foreign keys among its primary keys can be

modelled in an associative database as an association type

In other words an association type is equivalent to a table that has one or more foreign

keys as primary keys In a relational database data about customers would be recorded in

a Customer Table and data about shops in a Shop Table To combine data about shops

and customers in one table in the relational model you need to construct a ShopCustomer

Link Table This link table would use two foreign keys the primary keys from each of the

source tables as its own primary keys In an associative database an association type

with the (source verb target) of (Person is a customer of Shop) achieves the same

result

bull A domain in a relational database can be modelled in an associative database as a value

type which by definition has no association types Alternatively an entity type that is the

source of no association types is also equivalent to a domain

An associative database can use the same value type in many situations where a

relational database would require separate columns in different tables The simplest

example of this would be the use of dates One single Date value type can be used as the

target for associations indicating start date end date invoice date or date of birth which

would all require separate representations in the relational model Furthermore a single

instance of a date value such as 25th January 2001 would only be recorded once as

associations based on different association types could all make use of the same data

bull A column heading in a relational table can be modelled as the verb of an association

type

In other words the verb of an association type is equivalent to a column heading in a

relational table This restates what we have seen about the use of dates Column headings

in relational tables do not necessarily define the domain of the permitted values in the

column but often do give an indication of what the domain is An associative database

could easily contain a series of association types with verbs such as Start Date and End

Date all pointing to the same Date value type as their target

76



bull Both the relational and associative models use datatypes as part of the definition of a

domain

Datatypes are used in relational databases to determine the kinds of entries permitted in a

domain The associative database uses a similar mechanism for similar purposes although

the internal implementation of datatypes in Sentences is very different

LazyView - Using Sentences to view relational

databases

The LazyView Tool has been re-written and whilst some of the content from the previous

LazyView Guide is relevant all necessary information is included in this guide

You can use the Sentences LazyView chapters to view data in one or more relational

database alongside data from Sentences chapters in one integrated profile

LazyView chapters

Data from a relational database is accessed using a special kind of Sentences chapter file

A LazyView chapter can be part of a profile in the same way as an ordinary chapter

although it cannot be defined as the target chapter for schema data or query changes

You can create a number of LazyView chapters that each represent a different relational

database or instance and include them all in the same Sentences profile Although you

can add data to the Sentences database which includes a LazyView chapter this data is

always written to a native Sentences chapter and never to the LazyView chapter itself

This means that any data you add is only available when viewed through the Sentences

interface It is currently never written back to the relational database and is not available

when viewing data using the relational databasersquos native interface

Relational schema and Sentences schema

Before you can model a relational database in Sentences you must have a thorough

understanding of both Sentences and the associative model and of the relational database

you are working with

Relational databases are based on tables keys columns and rows while the Sentences

associative database is based on entity and association types and instances Despite these

fundamental differences the inbuilt flexibility of the associative model means that it is

relatively straightforward to create an associative schema in Sentences that can be used to

model the schema of a relational database

This modelling is achieved by mapping entity and association types in Sentences to

columns in the relational database Much of the mapping process has been automated but

to use LazyView successfully you must have a thorough understanding of the table

structure of the relational databases you wish to use and in particular of the ways in

which tables are linked to one another by the use of foreign keys

In general the preferred way of working with LazyView is to construct a new Sentences

schema to represent the schema of an existing relational database

Representing relational structures in Sentences

The following sections suggest how to map relations in relational databases to entity types

and association types in Sentences

Relational tables and columns

In relational databases objects are typically represented by primary key columns of tables

and the attributes of objects are typically represented by the non-key columns in a table

77



In Sentences an object is represented by an entity type and its attributes are represented

by association types As association types in Sentences have three elements in them the

correspondence between an association type and a non-key column is not exact

For example consider a relational table listing employees which has a primary key

column named Employee and has Department and Telephone number as non-key

columns In Sentences Employee Department and Telephone number would all be entity

types The relationships between these entity types would be represented by association

types which have the entity type representing the tablersquos primary key Employee as their

source and an entity type representing a non-key column as their target These

association types could be Employee works in department Department and Employee

has telephone number Telephone number

A Sentences association type specifies not only a source and a target but also the nature

of the association which is referred to as the association verb When mapping data from

relational tables to Sentences types it is therefore necessary to map the association verb as

well as the source and target In the case of an association which has a primary key as its

source and a non-key column as its target the association verb is mapped to the same

non-key column as the target This apparent duplication is necessary to prevent any

ambiguity

Views

Views are utilised in two main ways in a Relational Database They can be used as a read-

only subset or aggregation of data for the production of reports or analysis and they can

be used to control access and visibility of data

Views created for the purpose of inserting and updating data will generally be of no

interest to you when using LazyView to interrogate information If you do not have

access to the base table but only through a view then you may need to map that view to

obtain the data but views do not usually define a primary key or foreign keys and you

may have to specify them manually

Tables and views with no primary key

LazyView has the capacity to modify primary and foreign key definitions because this

information is not available directly available with some database connections

Note that the previous documentation on the LazyView tool stated that primary key

definitions were not available with a JDBC connection to a Microsoft Access database

Since then some JDBC Drivers do support this ability

Many relational databases allow you to construct read-only views (as simplified

selections of columns from one or more tables) which are treated as tables Unlike tables

views do not generally have primary or foreign keys defined for them and you should

create alternative key column definitions for columns in views so that they may be

mapped to types used as sources for associations

Any changes you make to these definitions in LazyView only effect the way in which

LazyView interprets the data in relational tables None of these changes is written back to

the original relational database files and the existing database definitions are not altered in

any way

It is very important that you understand the structure of the relational database and in

particular the way in which tables are related to each other before you make any changes

to the primary and foreign key definitions If you make any changes to key definitions

that contradict the logic of the relational database then the data you access with

LazyView may be meaningless

78



Tables with a foreign key

In relational databases connections between tables are often represented by using the

primary key column of one table as a column in another table This is known as a foreign

key In Sentences relational columns are represented by entity types A primary key

column that is used as a foreign key in another table is mapped to one Sentences entity

type That entity type (like all entity types in Sentences) can be used as the source of

association types whose targets represent non-key columns in the table for which it is the

primary key The same entity type can be also be used as the target for an association type

when performing its function as a foreign key with the second tablersquos primary key as the

source of the association

The important difference is in the way that the association verb is mapped In cases where

the target of an association is a non-key column the association verb is mapped to the

same column as the target In cases where the target of an association is the primary key

from another table the association verb is mapped to the foreign key column in the same

table as the association source is taken from For example a relational database may have

two tables named Employees and Departments

The columns of the Departments table include

bull Department_ID (the primary key)


bull Location

The columns of the Employees table include

bull Employee_ID (the primary key)

bull Employee_name

bull Department_ID_fk (a foreign key which represents the primary key in

the Departments table)

In Sentences these six columns could be represented by five entity types

bull Department_ID


bull Location

bull Employee_ID

bull Employee_name

There is no need to represent the foreign key Department_ID_fk as an entity type in

Sentences

The relations in the two tables could be represented by a series of association types

including Department_ID located at Location and Employee_ID works in

Department_ID

Both of these association types use the same Sentences entity type for

Department_ID even though in one case this entity type is the source and in the other

case the target of an association

The association verb located at which links the primary key to a non-key column in the

same Departments table would be mapped to the same Location column as the Location

entity type

The association verb works in which links the primary key to a foreign key column would

be mapped to the Department_ID_fk column in the Employees table and not to the same

column as the target type (which is mapped to the Department_ID column in the

Departments column)

79



There is a restriction on the use of foreign key columns You cannot create an association

in Sentences in which the source maps to a foreign key column and the target maps to a

primary key column You may only create association in which the source maps to a

primary key column and the target maps to foreign key column or to a non-key column

Defining your own foreign keys

Some relational databases may have connections between tables but they are not defined

in the Metaschema Other external data sources like an Excel Workbook may also not

contain Foreign Key Reference information In these cases it is possible to add missing to

Foreign Key references These are termed User Defined Foreign Keys Whilst you can

add edit amend and delete User Defined Foreign Keys you cannot do this with the

Foreign Keys defined in the External Data Source Metaschema

The wizard page for refining table and column choices includes a section that displays the

available Foreign Keys and allows you to create user-defined Foreign Keys

Figure 2-4 Foreign key definitions in the Mapping Wizard

Foreign Keys defined in the External Data Source Metaschema are marked with a lock

icon to indicate that they cannot be altered

To create a User Defined Foreign Key follow these steps

1 In the LazyView wizard select the Createhellip button

2 The Create Foreign Key Reference Dialog will open

3 Select the table you wish to reference The primary key of that table will be

shown

4 Select the column(s) to match the primary key from this table If the primary key

of the referenced table is compound then you must select the matching columns

in the correct order

Figure 2-5 Creating a foreign key definition

80



There is a facility for the dialog to attempt to automatically match columns based on their

column and table names If the schema is named such that incorrect selections are being

made then you may uncheck the option

There are several limitations imposed when creating User Defined Foreign Keys

bull You cannot create duplicate Foreign Key References

bull You cannot create a Foreign Key Reference if one exists in the opposite direction

bull The datatypes of columns must match their relevant primary key column datatypes

bull Whilst a self-referencing foreign key can be created for a table it cannot reference itself

with any of its primary key columns

Tables with composite keys

Some relational tables use a composite primary key (a key that uses more than one

column) An example of this would be an Employees table that used the two columns

Employee_ID and Department_ID as a composite key Each of these columns would be

represented in Sentences by an entity type and the composite key itself would be

represented by an association type in the format Employee_ID works in department

Department_ID Each of the non-key columns of the table would be represented by entity

types The status of each non-key column as an attribute of the composite key would be

represented by an association type which has the association type representing the

composite key as its source An example of this would be

( (Employee_ID works in department Department_ID) telephone number

Telephone number)

Tables with self-referencing columns

In some relational tables a column may represent the same data as is represented by the

primary key column For example an Employees table may contain an Employee_ID

column and a Manager_ID column to designate which manager each employee works for

The data in both of these columns is Employee_ID data as each manager is an employee

The Manager_ID column should be declared in the relational database as a foreign key

The relationship between these two columns could be represented in a Sentences schema

by defining two entity types Employee_ID and Manager_ID where Manager_ID is

defined as a subtype of Employee_ID

Tables representing subtypes

In some relational databases information about a subtype of a certain object is shown in a

separate table which has additional columns representing attributes of the subtype

In Sentences the entity type mapped to the primary key of the subtype table should be

defined as a subtype of the entity type mapped to the primary key of the original table

Tables representing additional information

In some relational databases attributes for a particular object are shown as columns in

two different tables which share the same primary key In Sentences there is no need to

define a separate entity type for the second tablersquos primary key as there is no practical

limit to the number of associations that may be created with the same source entity type

81



LazyView chapter setup

This section describes the practical procedures for using LazyView

Installing a JDBC driver

To use LazyView you must install the appropriate JDBC driver software for each

relational database you wish to access and make sure that the driver is available to your

Sentences server You must also know the details of how to connect to each relational

database Generally this includes

bull Server Hosting the RDBMS (and port if not the default)

bull Database instance (if applicable)

bull Database name

bull RDBMS User Name and Password

Certain RDBM Systems allow other options such as integrated security and secondary

servers for failover

The JDBC driver is often supplied as a Java archive (JAR) file and you should place this

file in a directory that is accessible to your Sentences serverrsquos classpath

When using the default installation of Sentences Version 40 with Tomcat 41 the

suggested location for the JAR file containing your JDBC driver is

ltSentences_homegtTomcat4webappsSentencesWEB-INFlib

When using the default installation of the Sentences Personal Edition the suggested

location for the JAR file containing your JDBC driver is

ltSentences_homegtresources

You must restart the Sentences server after making any changes to the JAR files available

to it

Indexing the relational database

When you retrieve data from relational database columns using LazyView mappings to

Sentences entity and association types indexed columns show better performance than

columns without indexes We therefore recommend that if you experience slow

performance you build or rebuild the indexes for the relational database columns that you

wish to connect to with LazyView

Java memory and stack requirements

If you wish to use LazyView to access large amounts of data from a relational database

you may need to make more memory resources available to the Java

Virtual Machine For details on how to do this please see the section on the lazystart

script file in the Sentences Userrsquos Guide

Mapping a large Relational Schema can also lead to a large number of Sentences Types

being generated In order to maintain a large Schema the Java stack size may need to be

increased The default stack is 1MB for Linux Unix systems and 512KB for Windows

A stack size of 1MB is sufficient for most large Schemas and this is set explicitly when

using the Tomcat test server To change the stack used see ldquoTomcat memory

configurationrdquo ldquoConfiguring server utilitiesrdquo and ldquoWeb Start configurationrdquo

Adding a LazyView chapter to a profile

The New Profile Wizard will allow you to create a Profile that includes a LazyView

Chapter to connect to a Relational Database For details see the section on Creating a

new LazyView profile using the wizard If you have more advanced requirements then

you can manually create or edit a profile containing LazyView Chapters

82



To create a LazyView chapter that represents a relational database follow these steps

1 In the Sentences Explorer select New profile or Edit profile from the File

menu

2 Start creating a chapter in the normal way by selecting New on the Edit Profile

dialog

3 Define a name and a location for the chapter and select the LazyView chapter

check box on the New file dialog and click OK

4 The Chapter will be added to the Profile and itrsquos Connection properties will be

opened in a dialog

Figure 2-6 Manually specifying LazyView chapter details

5 Select the Database Vendor and JDBC driver and then either select an existing

connection string or enter a new one Any connection strings previously used for

that Vendor in LazyView Chapters is included in the drop-down list

6 If necessary enter the user name and password that are required for

authentication with the RDBM System

7 Most of the time you will require a Dynamic Lazy View Chapter but if you

intend to import a snapshot of the data rather than connect dynamically then

select the Static mode

8 Define the chapter or chapters to be used as the target for schema data or query

changes This cannot be a LazyView chapter

9 Save the profile You may wish to give the profile a new name

The dialog will inform you if the particular JDBC Driver is not available This is usually

due to the relevant Java Archive file not being available to the server on the classpath

Once you save the profile Sentences will attempt to connect to the Relational Database

using the connection properties you have entered If there are any problems making this

connection the reason will be displayed in the Message Log For example

Error 1752 Opening connection Adventure Works rdbms

commicrosoftsqlserverjdbcSQLServerException The TCPIP connection to the

host has failed javanetConnectException Connection refused connect

Dynamic and static LazyView chapters

A Static LazyView Chapter is intended to be used for capturing a snapshot of Relational

Database data Any subsequent changes to the Relational data will not be visible so the

83



data can be updated or re-imported later but the intention is that the data is mainly

referential and does not change often or for performance reasons the reference data can be

held in a local Sentences database

Most of the time you will want to use a Dynamic LazyView Chapter that connects in

real-time to a Relational Database Note that there is a cache of data in Sentences to

improve performance which can be adjusted to balance performance with timeliness

In both cases the Relational Schema will be mapped to Sentences Schema but with a

Static LazyView the data (or a subset of the data) will be imported into a standard

Sentences Chapter file the target chapter for data changes This means that if you

subsequently change the Mode of the LazyView Chapter you must be aware of the

consequences

If the LazyView Chapter was Static and you had previously imported a snapshot of the

data then changing the Mode to Dynamic will have the effect of displaying duplicates of

everything (assuming nothing has changed since the snapshot was taken) You can then

remove the data chapter and see just the dynamic data

If the LazyView Chapter was Dynamic then changing the Mode to Static will mean that

no data will be present You will then have the option to import a snapshot of the data into

a standard Sentences Chapter

Optional connection properties

Some relational databases require that additional properties such as the name of a

database are specified when connections are made to them using a JDBC driver

You can specify these properties in a LazyView connection by appending them to the

connection string The syntax for these depends upon the Database Vendor and the

specification followed by the JDBC Driver manufacturer so consult their documentation

for details

For example to append additional connection string properties for an Oracle My SQL

connection you append

property_name1=value1ampproperty_name2=value2hellip

but for a Microsoft SQL Server connection it would be

property_name1=value1property_name2=value2hellip

Using an existing LazyView chapter

After you have created a LazyView chapter and defined the connection settings for it in

one Sentences profile you can use the chapter in another profile

You can do this by editing the profile that includes the LazyView chapter and saving it as

a new profile or by creating a new profile and selecting the LazyView chapter from the

Add chapter dialog list

The Connection properties dialog for the LazyView chapter is only available after you

save the profile to which you have added it

Copying an existing LazyView chapter

To copy an existing Lazy View Chapter follow these steps


menu

2 If there are more than one LazyView Chapters included in the profile then select

the one you wish to copy

3 Click on the Copy LazyView Chapterhellip button

84



4 A Copy LazyView Chapter dialog opens and you can amend any of the

properties including a new name for the copied chapter

5 Click OK to make a copy and refresh the profile

Creating a mapping definition

Once you have a Profile containing a LazyView Chapter you are able to start the

Mapping Wizard to create a mapping definition This definition will be saved with the

LazyView Chapter It will include

o Your selection of which Catalogs Schema Tables and Columns you wish to

map

o Any alternative naming or alternative datatypes for generated Sentences Schema

to remove unwanted duplication and facilitate reuse of the same Sentences

Schema where appropriate

o Choices where the primary key of a table is the entire foreign key to another

table (The choices are whether to represent this as a subset or a subtype)

Your profile will need a target for schema changes to be able to create a Mapping and

generate the resulting Sentences Schema

If the LazyView Chapter is operating in Static Mode then you will be able to specify a

limit to the number of rows to import on any one table Your profile will need a target for

data changes to be able to import a snapshot of the data

Depending upon the size of the Relational Database Schema it may take a while to make

your selections and choices You can save the definition at any point in the Wizard and

return to it later

To create a new Mapping Definition follow these steps


menu



changes


the profile


you would like to create a Mapping Definition for Otherwise just that LazyView


5 If there is no existing Mapping Definition for that LazyView Chapter then select

Create Mapping Definition to open the Wizard

6 If there is an existing Mapping Definition then select Re-create Mapping

Definition You will be asked if you wish to use the existing definition as a

starting point or create a completely new one from scratch

7 The Introduction Page of the wizard outlines the steps to be taken Select Next

and wait for the available Relational schema to be read

8 The first page shows three lists Catalogs Schema and TablesViews From here

you can select the items you wish to map If you are unsure you can proceed to

the next step to see more details and remove items later

9 Select Next The second page shows the selected Tables and Views on the left

hand side and when you select each one the column and foreign key details are

shown on the right hand side See the screenshot below

85



Select tables and columns

10 The list of tables and views on the left allows you to

Look at View definitions

See whether a table or view has a defined Primary Key

See whether any of the columns or keys are invalid

Select or deselect individual tables and views

Select All None or Only Tables

Figure 2-7 The LazyView Mapping Wizard ndash Selecting tables and columns

11 The Selected TableView columns on the right allows you to

Alter the primary key sequence or assign one if there is none defined (only

mandatory fields can be assigned an alternative primary key sequence) See the

section ldquoTables and views with no primary keyrdquo for more details

Change the Sentences Datatype that this column data will be converted to For

example the database may define the table as a Timestamp but if you know that

it only contains Dates you can change the datatype to Date

Select and deselect individual columns

Select All or None of the columns in one go

The button on the end of each row and the View Sample Data button below the

table will open a dialog that shows you a preview of the data in the relational

database

86



Figure 2-8 Previewing sample data from the RDBMS

You may alter the number of individual values that are returned Note that some kinds of

Relational Column Datatypes do not allow use of the Min and Max functions

12 Also shown on the right is a summary of any Foreign Key references This will display

whether the Foreign Key is available to map to an Association Type or not For

example if it links to a table that you have chosen not to map then the Foreign Key

cannot be used other than importing the raw data as a normal column (or columns)

If Foreign Keys are missing you can create and edit User-Defined Foreign Keys here to

link your tables and views See the section on defining your own foreign keys for details

13 At the bottom of this page are several options that you can choose

Use fully qualified names for Entities and Foreign Key Association Verbs

This means that the schema generated will include the Catalog and Schema

names to ensure that every Column and Foreign Key Reference is mapped to a

unique Sentences Type This is unchecked by default as it more common that

columns in different tables with the same name hold the same kind of data and

can be represented by a single Sentences Type

Convert Names to Proper Case This allows the automatic conversion to

proper case names with spaces between words from databases where the schema

names are all uppercase or Camel Case

Substitute spaces for underscores and full stops When generating Schema

names this replaces any full stops or underscores with spaces

Re-use existing Entity Types If possible reuse the same Entity Types

otherwise append a incrementing number to the name For example Date01

Date02 Date03hellip

Use NOT NULL Constraints This honours the constraint by making the

resulting Sentences Schema mandatory

Group Entity Names for Datatypes This allows two columns to be mapped to

the same Entity Type despite them not having exactly the same datatype For

example two text columns called Description but of different lengths can be

mapped to the same Entity type With this option unchecked the wizard would

insist that the columns are mapped to different Entity Types Similarly two

decimal columns with different precision can be mapped to the same Entity

Type

87



List of Name Translations This allows you to select a named list of

Translations to apply to column and table names For example you might wish to

replace all occurrences of ldquoInfordquo with ldquoInformationrdquo

You can create new Translation Lists and Edit existing ones If you use a

Translation List for a mapping then the name of the list used is saved with the

mapping definition and re-used if you re-run the mapping wizard

See the section Creating and Editing Translation Lists for details of how to create and edit

Translation Lists

14 Select Next to move onto the next page If there are any invalid columns or

tables or none selected you will not be able to move to the next page

SubsetSubtype choices

15 If there are no choices to be made then the page will not be displayed and you

will be taken directly to the next page

16 This page allows you to make choices as to how the schema is mapped for two

specific scenarios Tables where the primary key is the foreign key to another

table and Columns that you may or may not wish to represent with the same

Entity Type

Figure 2-9 Choosing subsets and subtypes

17 The list shows tables where the entire primary key is a foreign key to another

table You need to use your knowledge of the data and schema to determine

which of the two kinds of relationship the tables should have because the

Relational Schema cannot record this The screenshot above shows an example

where we know that a Sales Person does not exist in its own right as a particular

type of Employee It will not necessarily remain a Sales Person throughout its

life So in this case Sales Person is a subset of Employee rather than a subtype

18 Select Next to move onto the next page

New and existing Sentences schema conflicts

19 The next page lists all the columns that you have chosen to map and informs you

of any conflicts that must be resolved before you can continue It also allows you

to perform actions on more than one Entity Type to be generated at once such as

changing all Timestamp datatypes to Date datatypes

88



If we did not previously select the ldquoGroup Entity Names for Datatypesrdquo

option then we may end up with some Columns mapping to the same Entity

Type that have different Relational Datatypes In many situations we will be able

to map the different relational columns to the same Sentences Entity Type

despite having different precision and length because Sentences can

accommodate such variation

By default we map simple column data to Value Types where possible If part of

a Primary Key then the Entity Type cannot be a Value Type because it will need

to be the source of Associations So another reason an Entity Type might be in

conflict is when some columns are part of a Primary Key and others are not This

is resolved by setting all columns to generate Non-Value Types

If you are re-creating the mapping or are adding a new LazyView Chapter to an

existing Profile then there may be existing Schema with the same names as

Schema that is to be automatically generated by this wizard

There are thus two main kinds of conflict that may prevent you from continuing

Columns from different tables may be mapped to the same Entity Type in

Sentences These must have compatible datatypes

Entity Types to be generated may already exist These must also have compatible

datatypes

In addition another conflict that may prevent you from continuing is where there

are more than one mapping LazyView chapter in the profile and the target Entity

Type is already mapped in another LazyView definition


from multiple Relational Columns that have the same names but different

datatypes (or the same datatypes but different value type flags) You can filter

the list to just show these mappings by clicking the button underneath the

message


that already exist but have incompatible datatypes You can filter the list to just

show these mappings by clicking the button underneath the message

22 The filter section of the page will also show if there are Entity Types to be

generated that already exist and have mapping(s) in other LazyView definitions

It would be unsafe to delete and re-create these Entity Types as the other

mapping(s) would be broken You can filter the list to just show these mappings

by clicking the button underneath the message

89



Figure 2-10 The LazyView Mapping Wizard ndash resolving mapping conflicts

Filtering mappings

There are several ways to filter the mapping columns The three kinds of conflict

mentioned above can display only the affected columns by selecting the relevant ldquoShow

the affected column(s)rdquo button

In addition you may enter a name or an SQL datatype to filter the displayed mappings If

you enter several words in the Name filter then they must all appear in either the Type to

be Generated column or the Existing Type column If you enter several words in the

SQL Datatype field then rows with the SQL Datatype containing any of them will be

selected

Finally you can select the Show All Columns button to restore the full list

Resolving conflicts

There are several ways to resolve these conflicts You need to use your knowledge of the

data and schema to determine which method(s) to use

23 It may be that two or more columns are mapped to the same Entity Type but one

will be the source of associations and others are not In this case you may set all

column mappings to generate non-value Entity Types


checkboxes next to the icon on each mapping) and select the Set As Non-Value

Types button


require different Datatypes You may look at a sample of the data by selecting

the button that opens the sample data dialog From this or other knowledge of the

data and schema you may be able to change one or more of the generated

datatypes to match thus allowing the same Entity Type to represent all columns

90




checkboxes next to the icon on each mapping) select the desired Datatype from the

drop-down list and select the Set Datatype button

It may be that the datatype you have selected is incompatible If so then you will receive

a warning dialog such as below

Figure 2-11 Resolving mapping conflicts

In a few cases it may be that you need to override the datatype like this For

example if you are certain that a textual field only contains numeric data


should be distinct Entity Types In this case you may rename the Type to be

generated to have unique names You may either double click in the cell for the

Type to be generated or select it and press F2 Edit the name and press Enter

To facilitate making the Entity Type names unique this page also provides the ability to

o Prepend the selected Types with their Table names

o Add a Prefix

o Add a Suffix

o Reset the names to those originally generated

When changing the names of several columns at a time you have the option of also

renaming the Association Type verbs that are targeted on each Type at the same time

Select the Checkbox next to these options to enable this feature

26 It may be that a Type to be generated already exists but that the datatypes are not

compatible (or one is a value type and the other is not) In this case you may either

delete the pre-existing Entity Type or modify the one to be generated to match

To delete the pre-existing Entity Type(s) select all the mapped columns you wish to

delete the existing type for (by selecting the checkboxes next to the icon on each

mapping) and select the Delete Existing Schema button

Note that it is unsafe to delete pre-existing schema that was generated from a different

mapping definition to a different database because those mappings will be lost You will

be warned if such a situation exists and given the option to cancel the action

In addition to necessary conflict resolution you may also wish to modify several

column mappings at a time This page also provides the ability to

o Include or exclude several column mappings at once

o Delete all pre-existing schema that is safe to delete

91



o Filter the columns shown by name

o Modify datatypes for several column mappings at once

If a relational schema designer has chosen to store a number in a character

column you may specify a Number Datatype Sentences will attempt to convert

the characters into numbers for you

If a relational schema designer has chosen to store a date or time in a character

column you may specify a Date Time or Timestamp Datatype If the date or

time format is not one of the standard ones built into Sentences then you can

define additional formats that will be used to convert a textual representation into

a date or time These additional formats are added to the Serverproperties file by

the System Administrator Here is an example set of etries

DateFormat1= ddMMyyyy

DateFormat2= dd-MM-yy

DateTimeFormat1= yyyy-MM-dd HHmmssSSSZ

DateTimeFormat2= yyyy-MM-dd HHmmssSSS

TimeFormat1=HH~mm~ss

TimeFormat2=HHmm

27 Once all conflicts have been resolved select Next to move to the next page

Summary of schema to generate

28 This page shows a tree of the Schema that is about to be generated when you

select Finish It is still possible to rename individual items in the tree by

selecting them and pressing F2

29 If you are importing a snapshot of static data then you can choose to enter a

value for the maximum number of rows to import This will limit the amount of

data and is useful if you wish to obtain a sample of the data to investigate offline

92



Figure 2-12 The LazyView Mapping Wizard ndash summary page

30 Once you have reviewed the summary select Finish to generate the mapping

definition and schema and import the data if appropriate

Processinghellip

31 As the wizard generates the mapping schema and data it shows you itrsquos progress

Figure 2-13 The LazyView Mapping Wizard ndash processing page

93



If data is being imported then there are additional steps in the process

32 Once complete the Results are displayed Select Close to close the wizard

Figure 2-14 The LazyView Mapping Wizard ndash results page

When types are generated the description field is populated with the catalog schema


The output from a mapping are also saved to a file in the Trace directory with the name

LazyViewMapping_ltmilliseconds timestampgttxt

Creating and Editing Translation Lists

When performing the mapping from an external data source to Sentences you may wish

to automate some of the re-naming of schema For example some of the abbreviations

used in the external data source can be expanded to more meaningful names in the

Sentences Schema

To facilitate this the mapping refinement page of the LazyView wizard allows you to

specify a Translation List to use when generating the mapping You can edit these lists

and if you use a list the mapping definition remembers this if you choose to re-run the

mapping

If two translations match a particular column name then the longer more specific

translation will be used For example with ADDR_=ADDRESS_ and

DESPADDR_=DESPATCH_ADDRESS_ the latter will be used

Creating a new Translation List


1 Select the New Listhellip button The New Translation List dialog will open

2 Enter a name for the list

94



3 You may enter as many translations as you wish You can specify whether each

translation is case-sensitive or not This applies to the From word or phrase not

the To word or phrase

4 You may optionally add one or more exclusions

An example would be where you may enter a translation for Id =gt Identifier

This would replace ProductId with Product Identifier and Holiday with Ho

Identifier day By making it case-sensitive Holiday would not be erroneously

replaced

This does not stop NewIdea being replaced with New Identifierea so an

exclusion for Idea could be added

5 Select Save to save the list If the name you have specified is already in use you

will be prompted to change it to a unique name Once saved that list will be set

as the Translation list to use when generating the Mapping Definition

Editing a Translation List


1 Select the Translation List you wish to edit from the drop-down list

2 Select the Edit Listhellip button The Edit Translation List dialog will open

3 You may add or delete any translations or exclusions

4 Select Save to save the changes to that Translation List or Cancel to cancel the

changes

Figure 2-15 LazyView Mapping Translation List

95



Importing or updating static data

When using a Profile containing a Static LazyView Chapter you can choose to initially

import no data to simply view the schema generated If you are happy with the mapping

then you may wish to subsequently import all or part of the data If the LazyView Chapter

was originally operating in Dynamic mode and you have changed to Static mode then you

will also wish to perform an initial Import

There are several strategies when taking a static snapshot of RDBMS data You may

import the data once and never need to update it again You may wish to import a sample

of the data for experimentation You may know that only new data is added and choose to

periodically update the data or you may know that data is added changed and deleted and

need to keep a record of when those changes happened Finally you may wish to treat the

data as transient and periodically discard the previous snapshot and replace it with an

entirely new one

To accommodate these different strategies there are four types of data update that can be

performed on a Static LazyView chapter

You may already have a complete snapshot of data that you wish to update with the latest

RDBMS data This is a Standard Update in which a note is made of when there is a) no

change b) an addition or c) a target changes Any data no longer in the RDBMS data is

also deleted

You can choose to incrementally update the data without noting these changes and

without deleting any old data This is the second kind of update called an Incremental

Update In addition to this simpler and faster behaviour you can also choose to only add

data since the last update date You can specify date fields to use in each table such that

only rows with dates after the last update date are added For example a Date Created

column Each time a data update is performed the last update date is recorded

The third Replace Data update replaces all data To do this Sentences deletes the old data

chapter and creates a new blank one This update method assumes that the data is

transient This method is faster than the Standard Update method You can optionally

choose to limit the number of rows that are imported as a simple way to test the mapping

with a sample of the data For details of how to choose date columns see Selecting date

columns to limit incremental data updates

The final method Replace Limited Data is intended to import a subset of the data as

defined by a set of Sentences Queries Each set of related tables can have a Sentences

Query assigned to it which is used to limit the rows imported For details of how to create

and assign limiting queries see Creating and assigning limiting queries for a data import

96



Figure 2-16 LazyView Data Update Wizard

To Import or Update the Static Data follow these steps


menu



changes


the profile


you would like to import or update data for Otherwise just that LazyView


5 There is only a single page when importing or updating Static data

6 Select which option for updating you require

7 If you choose to completely replace the existing data then you can additionally

specify a maximum number of rows to import on any one table Again this is

intended to allow you to sample the database

8 Select Finish to start the import Progress is shown similar to that when

originally creating the mapping

Steps when updating the data

Steps when replacing the data

97



9 Once imported the results are displayed Select Close to close the wizard

The output from an Update are also saved to a file in the Trace directory with the name

LazyViewUpdate_ltmilliseconds timestampgttxt

Recorded updates

For each Table we record



For each Association mapped from a simple column or a Foreign Key reference we record



the instances where the target was changed

We do not record when the previous target is orphaned

Any remaining instances that were not annotated as such are deleted These would be

found by using the time slider mechanism

Each time an update is performed a new Rdb Update Timestamp instance is created It

is the target of each of the three kinds of association to record these changes The Options

dialog (Select Options from the View Menu) includes a checkbox to determine whether

or not to show the Lazy View Update instances

Selecting this option will display the System Entity Type called Rdb Update

Timestamp and display the individual updates in the data pane

98



Selecting date columns to limit incremental data updates

When choosing to update Static LazyView data incrementally you can choose to specify

date fields to specifically limit the new rows imported to those since the last update date

The last update date is recorded after each importupdate

To choose the date columns follow these steps


menu


the profile




4 Select Choose Date Columns for Updateshellip and a Dialog will open showing a

list of tables Each table will display the alternative date columns that you may

choose to limit data updates

5 You can click the Select Defaults button to automatically select columns that

have ldquomodifiedrdquo ldquoupdaterdquo or ldquocreaterdquo in their name (selected in that order)

6 You can click the Clear choices button to deselect all columns

7 You can scroll down the list of tables and manually select or deselect date

columns

8 Once you have made your choices click OK to save your choices


Creating and assigning limiting queries for a data import

The Replace Limited Data data update choice allows you to replace the current data with

a new data chapter and import a limited ldquosubsetrdquo of the RDBMS data The data are

limited by the use of Sentences Queries for each table or set of tables

99



The External Data Sources dialog provides the abililty to create and assign these

queries To view the mapped tables and their limiting queries follow these steps


menu


the profile




4 Select Import Limited Datahellip and the dialog in Figure 2-18 will open showing

the Database Tables and their limiting queries The button will only be enabled

for Static LazyView chapters

The dialog shows each table (and their parent tables) together with the common

type that they are rooted on their row count their limiting queries and the count

of rows that would be imported using the limiting query Both counts can be

refreshed with the Refresh row countshellip button These counts will be saved

with your choices


5 You can edit an existing limiting query by clicking on the Edit Queryhellip button

6 You can create a new query by clicking on the Create Queryhellip button A new

query with the name ldquoltEntity Typegt SQL Limiterrdquo and if one already exists

that one will be edited instead so you canrsquot accidentally create duplicates

Creating limiting queries

Figure 2-19 Limiting query example

100



A Sentences query can be created to limit the rows imported by translating the query

constraints into an SQL statement If a forward request is made mandatory this will

translate to an IS NOT NULL constraint If we add a Selection node then this will be

translated to a WHERE clause For example in Figure 2-19 we limit the countries

imported by saying the country code must be 6009 (United Kingdom) The Selection can

include all operators and functions used in Optimisation Queries If a forward or inverse

request is used that represents a foreign key then an SQL JOIN will be performed

Unlike Optimisation Queries we cannot bind to instances because there are none Instead

using a dynamic profile we need to make a note of all pertinent codes such as 6009 =

ldquoUnited Kingdomrdquo for Country Code and 0 = ldquoMalerdquo 1 = ldquoFemalerdquo for Gender Code

All tables related by foreign keys that are part of their primary key must be linked For

example CUST_CUSTOMER CUST_CRDT_CHECK and CUST_INTEREST are

related through the primary key CUST_CODE of CUST_CUSTOMER If we were to

create a limiting query for CUST_CUSTOMER so that only say Men in the UK were

sampled then we would wish to limit the other two tables at the same time in the same

way Otherwise unneeded data would be imported from the other two tables that could

never link to the CUST_CUSTOMER table

Memory requirements and timeouts

Importing or updating static LazyView data can require a large amount of memory The

performance when importing or updating data is significantly improved by ensuring

Sentences has enough available memory

For relational database tables with large amounts of data LazyView will request the data

in smaller amounts rather than all at once For such large tables this may still take a long

time depending upon the database vendor and communication speeds between the

Sentences server and the Database server

You can adjust the Import Timeout value and memory allocation See ldquoServer propertiesrdquo

for details

Combining databases

A Profile can be used to combine two or more seemingly disparate databases by including

a LazyView Chapter for each database They can be on RDBM Systems from different

Vendors on different Servers All that is needed are the privileges to read the Relational

Schema and Data

Making entity types equivalent

Sentences has the ability to mark two Entity Types as equivalent For details see the User

Guide This mechanism is of particular use when combining databases if you suspect that

two tables hold the same data It will allow you to view the data in an integral way and

identify duplicates or produce aggregate statistics and information


A feature introduced in V40 is the Display Name Query For Details see the section on

Display Name Queries

For data viewed through a LazyView Chapter Display Name Queries are particularly

useful when the main Entity Types such as Employee are represented by a unique

identifier rather than useful information like names If the Employees tables from two

different databases store the names in two separate ways Display Name Queries and

Entity Type equivalence can be used to form a unified list of recognisable entities rather

than identifier data

101



Viewing existing definitions

The current Mapping Definition is saved with each LazyView Chapter and can be viewed

in detail from the External Data Sources Dialog

To view a Mapping Definition follow these steps


menu


the profile




10 Select View Mapping Definitionhellip and a Dialog will open showing the

Database Details and how the available schema has been mapped

11 The first dialog shows the Database details User Details and a table of Catalogs

You can drill-down into more details for Schema Tables and Views and

individual Columns and their properties

Checking for schema changes

The checkbox Check schema before actions on the External Data Sources Dialog will

examine both the Relational and Sentences Schema to see if there have been any changes

since the Definition was created

This includes useful information such as the creation of new Relational Tables and

changes in datatypes

The process of checking can take a long time so by default the schema is not checked

every time

Using LazyView to view data

For Static LazyView Chapters once the data is imported there is no difference in

behaviour between the snapshot data and data entered into Sentences in the usual way and

stored in Sentences Chapters The Static LazyView mechanism is another way to populate

a Sentences Database

Once set up data obtained dynamically will appear and interact with other Sentences data

as if it were stored in Sentences Chapters There are a few special situations that you need

to be aware of when using dynamic LazyView Chapters Firstly the speed of connection

and the particular RDBM System may impact the perceived performance of Sentences

and secondly some limitations that do not normally apply to Sentences will be present due

to the RDBM Systems limitations

Performance



the tree node can be expanded Because of the differences between how Sentences and an

RDBMS retrieve data it can be quite expensive to calculate whether or not to show a plus

sign when the data is from a dynamic LazyView Chapter

See Determining if child associations are present for details of how to change whether a

Profile attempts to determine if child associations are present

See also the section on LazyView Query Optimisation below

102



Large database fields

Associations in Sentences are always two-way If you can navigate from source to target

then you can navigate from target to source All Sentences datatypes can be searched and

sorted

Relational Databases have self-imposed limitations on these kinds of operation For

example you cannot perform a ldquoLikerdquo function on database columns with large datatypes

like XML You cannot even test for equality if you have an instance of XML that you

wish to find the ldquoparentrdquo of

This limitation hinders Sentences ability to show inverse associations dynamically for

such datatypes

CLOB and NCLOB (Character Large Objects)

NVARCHAR LONGVARCHAR LONGNVARCHAR

SQLXML

BLOB (Binary Large Objects)

LONGVARBINARY BINARY

LazyView Query Optimisation

Sentences queries work very efficiently with Sentences data in the chapter structures that

have been developed in tandem With a dynamic LazyView chapter the translation to the

relational schema can lead to inefficiencies simply due to the differences in data

structures

Static LazyView profiles do not have the same problem as the data is all stored in native

Sentences chapters

With a dynamic LazyView profiles a Sentences query based on an entity type will select

each instance of that Type in turn and apply selection criteria to see whether it should be

included in the results When this translates to a Relational SQL statement all instances

are returned which can take a long time In the relational world joins to other tables and

WHERE clauses limit the initial number of items returned For this reason there is a query

optimisation mechanism built into LazyView that allows an optimised Relqtional SQL

statement to be constructed for each LazyView chapter

The mechanism for this is to create a Subset of an entity type that is mapped to Relational

Schema and tell the subset that it is not a standard subset but an optimisation for a

LazyView chapter This is done by selecting the LazyView chapter that it should be used

in The Sentences query that is defined for the subset is then used to construct an SQL

statement that is used to optimise the instances returned When the subset is included in a

Query (either a normal Query or an Update Query) then the optimised SQL is passed to

the LazyView chapter to be used instead of the plain dynamically constructed SQL This

can have significant improvements on the performance

The best improvement will be seen on the data request node but this functionality is not

limited to that node

Optimisation Queries

The query used to construct SQL will be transformed by taking each request node and

applying a table join andor a predicate where clause if appropriate

Forward and Inverse Requests will lead to joins to other tables if they are the result of a

Foreign Key Mapping

Nodes set as required will translate to IS NOT NULL predicates

Nodes bound to instances will translate to equality predicates

103



Nodes bound to other nodes will translate to predicates linking columns in different

tables

Selection expressions will be parsed into equivalent where clauses Only functions that

translate to an equivalent SQL function can be supported Supported functionality

Sentences Supported SQL Equivalient

AND Yes

CASE No

COALESCE Yes

CONCAT (||) Yes

CurrentUserHasRole No

DEFAULT Yes COALESCE

EXISTS Yes IS NOT NULL

Datatype Constructors No

Entity Type Constructors No

Datatype Functions No

Average Yes AVG

Count Yes

CountDistinct Yes COUNT( DISTINCT ltcolumngt)

FIRST No

LAST No

MAX MIN Yes

Median No

StdDev No

StdDevSample No

Sum Yes

GetClientParameter No

GetCurrentUserID No

GetCurrentUserName No

GetParameter No

GetState No

HasState No

IF THEN ELSE Yes CASE WHEN THEN ELSE END

LIKE Yes

NOT Yes

OR Yes

PriorResult No

VOID Yes NULL

XOR Yes (c1 AND NOT c2) OR (c2 AND NOT c1)

== Yes =

= Yes ltgt

lt gt gt= lt= Yes

- + Yes (divide multiply subtract add)

Derived Types attached to the query node that are independent from the main data request

tree will be available as references to be used in such Selection nodes

Functions that do not have an SQL equivalent such as GetCurrentUserID() will be

evaluated and used in expressions for these independent derived types If a Selection

references any other derived type then that selection will not be able to be used to form a

predicate where clause

The property dialog of a Subset used for LazyView Optimisation allows you to select the

LazyView chapter that it should be used to optimise for because there could be a choice

104



It also allows you to request the actual SQL that will be executed which is useful when

developing the optimisation

LazyView reference


administrators

LazyView parameters in the Serverproperties file

The following parameters in the Serverproperties file are used by LazyView

bull LazyViewCacheTime

You may use this property to specify a default cache timeout for all LazyView

connections The time is defined in seconds and the default value is 10 LazyView always

checks for data in the cache before retrieving information from the database If this

parameter is set to 10 then if a requested data item is in the cache and is less than 10

seconds old the cached data is used and new data for this item is not retrieved

bull LazyViewShowSQL

You may use this property to specify whether or not the SQL statements being submitted

to the RDBMS should be output to the console This would allow for investigation of

lower level behaviour if assessing performance for example

bull LazyViewMultiLineTextThreshold

You may use this property to specify the limit at which textual columns are given a Multi

Line format in Sentences The number of characters has a default of 75 Any textual

columns less than this value will have a Single Line format

bull LazyViewResultSetCacheSize

You may use this property to specify the number of concurrent result set caches to hold

There will be an RDBMS limit to the number of open result sets allowed due to memory

constraints The default size is 1000

bull JdbcQueryTimeout


data dynamically or executing a query in a dynamic LazyView profile The default value

is 5 seconds Setting a value of zero will disable the timeout altogether

bull JdbcImportTimeout


LazyView data import The default value is zero Setting a value of zero will disable the

timeout altogether

bull JDBC Connection Specifications

For each Database Management System Product a specification is required to form the

vendor-specific JDBC Connection Strings There are eight possible values required

1 Jdbc1=The vendor and product name

2 Jdbc1Drivers=A list of drivers (the first will be the default to use)

3 Jdbc1Protocol=the protocol up to the server or service specification

4 Jdbc1Database=the string that is immediately after the server specification

and before the database name followed by a | followed (optionally) by a string

that might mark the end of the database name If no second string is specified

then the rest of the connection string is regarded as the database name

5 Jdbc1Port=the default port number if applicable

105



6 Jdbc1Service=true - if there is no serverport section and the database

name is a service system name file etc

7 Jdbc1Security=the string that is immediately before the integratedSecurity

property followed by a | followed by a string that might mark the end of the

integratedSecurity property This is only applicable to MS SQL Server

8 Jdbc1Instance=the string that is immediately before the instance name

followed by a | followed by a string that might mark the end of the instance

name If no second string is specified then the rest of the connection string is

regarded as the instance name This is only applicable to MS SQL Server

These values need to be repeated for each Database Product you wish to connect to The

second set of properties will be Jdbc2 Jdbc2Drivers Jdbc2Protocol

Jdbc2Database Jdbc2Port Jdbc2Service Jdbc2Security and Jdbc2Instance The

third set will be Jdbc3 and so on

Here are examples of two kinds of Oracle Specifications

Jdbc4=Oracle Thin


Jdbc4Protocol=jdbcoraclethin

Jdbc4Database=|

Jdbc4Port=1521

Jdbc5=Oracle OCI 8i


Jdbc5Protocol=jdbcoracleoci8

Jdbc5Database=|

Jdbc5Port=1521

Jdbc5Service=true

107



Chapter 3


This chapter looks at database design on a more practical level and shows some of

the ways in which Sentences implements the concepts of the associative model It

follows on from Chapter 2 Introducing the associative model which described the

concepts of the associative model of data and listed some points of comparison

between the relational model and the associative model

This chapter also introduces the range of user interface design possibilities that are

available in Sentences


In the schema design stage a database designer must decide which of the database

building blocks should be used to represent each element in the real-world system If you

have experience of relational database design and you are now approaching database

design in Sentences for the first time the theoretical points for comparison given in

Chapter 2 Introducing the associative model should help you choose the most suitable

associative model building blocks

Database design skills

Database design involves two activities problem analysis and schema design In the

analysis phase the structure of data in the real-world system under review - the problem

domain - is studied and recorded The analyst discovers how different data elements

relate to each other and how they may be dependent on each other If the analysis stage is

carried out accurately and thoroughly the schema design stage is usually straightforward

A thorough understanding of the real-world system is as important in the associative

model as it is in the relational model Someone skilled in relational schema design should

find that their analytical skills are equally relevant to the associative model

Choosing entity association or value types

Something modelled as an entity type must have an existence independent of other types

in the problem domain In contrast elements modelled as association types are dependent

on their sources and targets As you cannot create association types until you have first

created a number of entity types to be used as sources and targets there is a tendency to


As a practical test remember that every entity instance must have a name but an

association instance does not have a name If you cannot easily name instances of a given

type this suggests that this type should be modelled as an association Take care not to


If you are unsure about which entity type should be the source for a particular association

type it is useful to remember that associations are dependent on their source This means

that if the source entity type is deleted the association type is also deleted

Value types are a special kind of entity type Value types are used for numerical values

and similar data Any type that is configured as a value type cannot be the source of an

association type but can only be used as the target type

As with any other type of software design it is important that your schema design is a

faithful model of the real-world activities you wish to describe

108






enabled with the server property Check Value Visibility This additional check is disabled

by default See ldquoServer propertiesrdquo for details

Creating verbs for association types

The verb of an association type is used as its name and appears as its field label in the

Dataform It is important that wherever possible you use an active form of the verb rather

than a passive form You should also take care to use the singular form of the verb in an

association type name

It can be useful to include the source type name when you create an inverse verb as this

prevents ambiguity For example the association type Course start date Date could

have the inverse association Date course start date Course

If you have associations with duplicate names (duplicate verbs) either you need to revise

your structure or you need to use more precise verbs (verbs based on the target not on

the English language verb)

For a multiple Association Type you can specify a plural form to be used in Dataforms

and folders in the Data Pane The singular form will still be used for individual

association instances

Modelling one-to-many association types

You can easily model one-to-many association types in Sentences When you want to

create a one-to-many data structure model the one element as the source and the

many element as the target

Iterative design and prototyping

Although detailed data modelling is essential for the design of quality applications

Sentences is a very effective prototyping and iterative development tool You can easily

design a small scale application schema as a prototype for testing and improvement It is

good practice to type in small amounts of test data to verify your structure as you build

Sentences associations can be optional or mandatory It is generally more convenient at

the design stage to create all associations as optional After you have verified your design

you can convert optional associations to mandatory ones as required

Designing for change

You should create a schema that takes account of changes that take place in the real-

world system For example a business unit always requires a manager irrespective of the

name of the person fulfilling the role of manager Your schema should reflect this fact and

take account of possible changes of personnel Schema A (shown below) makes the role

dependent on the person fulfilling it

Schema A

Person fulfills Role

Business Unit utilises (Person fulfills Role)

Schema B (shown below) gives an alternative structure in which the role is not dependent

on the person fulfilling it

Schema B

(Business Unit utilises Role) fulfilled by Person

109



Modelling behaviour common to multiple types

The associative model has two mechanisms that can be used to support the abstraction of

behaviour common to more than one type in a schema and to support the simultaneous

grouping and separation of instances of related types

bull Supertypes

are used for permanent groupings and indicate that all instances of the type are implicitly

instances of the supertype The reverse is not true An example of the use of a supertype

would be modelling Mammal as a supertype of Primate

bull Subsets

are used to describe a group whose membership is transitory An example is customers

with negative credit which is a subset of customers that depends on the customers

account balance

There is more information about using subsets and supertypes in Chapter 5 Working

with Sentences and in Chapter 6 Advanced techniques

Using instance-specific association types

You can define an association type that has an instance rather than a type as its source

This allows you to add an additional piece of information relating to only one instance

rather than to all the instances of a type For example in a customer relationship

management system you may wish to record the golf handicap of only one customer You

can do this in Sentences by adding an instance-specific association type for example Bill

Smith golf handicap of golf handicap

For more information see Instance-specific association types This association type

does not exist for other customers in your database


of the same type you can change the associations source to the type for example to

Customer golf handicap of golf handicap In this case Sentences preserves the

original data you entered

Using chapters and profiles

A users view of an associative database is defined by the profile that they are using A

profile defines a set of chapters and the sum of their contents is the users view A user



design Profiles also define the chapters to which updates are applied (see Profiles and

chapters and Creating database views using profiles and chapters )


When you develop your database application using Sentences you have a number of

different user interface design options each of which has its own advantages and

drawbacks In general if you are able to devote more time to development you can

achieve a greater degree of control over the user interface It is possible that you may

want to use more than one type of interface for your Sentences application

The range of available options include

bull using the standard Sentences Explorer and Dataform interface

bull using custom Dataforms

110



bull using the Dataform Query or Picker applets in HTML pages and using JSPs

bull using an XML-based interface

bull using the Sentences client API

bull using the Sentences End User Application Server This allows you to design an HTML5

web application interface

A range of user interface options are presented in the Application Suite examples supplied

with Sentences Enterprise Edition These are described in detail in the Application Suite

Guide

Using the Sentences Explorer and Dataform interface

The simplest user interface method for a Sentences application is to use the Sentences

Explorer (see ldquo Using the Sentences Explorerrdquo) and the base Dataform (see The

Sentences Dataform)

The advantage of this method is that it requires very little effort as you are using

Sentences as supplied The base Dataform is available as soon as you have designed your

schema and always keeps up with schema changes The drawback of this method is that

you have little or no opportunity to customise the user interface Even so this method is

suitable for many applications

Using custom Dataforms

If you want to restrict the associations presented to your application users you can use the

Query Editor to define a custom Dataform (see Creating a custom Dataform ) You can

also define a custom Dataform as the default Dataform for a type (see The base

Dataform and the default Dataform)

You can give different groups of users different default Dataforms by using different

schema chapters for the profiles of each group (see Creating database views using

profiles and chapters )

Although this method of interface design does give you a little more control than using

only the Sentences Explorer and the base Dataform using custom Dataforms does require

maintenance of your application to ensure that your custom Dataforms keep up with

schema changes

Using applets in HTML pages and using JSPs

You can deploy a Sentences Dataform a Sentences Picker and a Sentences Query using

Java applets For more information see The Dataform applet The Picker applet and The

Query applet

Each applet appears on an HTML page and you have control over the appearance of the

applet and the page Deploying an applet in this way to allows your users to view or

create or edit data in your Sentences database without giving them access to Sentences

Explorer features

You can customise your Web page interface even further by using Java Server Pages

(JSPs) JSPs allow the combination of static HTML content with dynamic information

retrieved from a Web server that differs with each page request The Sentences

Application Suite contains examples of user interfaces developed with JSPs

Developing applets and the Web pages used for their deployment does give you much

more control over user access but requires additional time and effort for creation and

maintenance

111



Using an XML-based user interface

Sentences includes extensive support for data interchange using XML This means that

you can add and retrieve Sentences data without using the standard Sentences user

interface (see ldquoSentences and XMLrdquo)

You can use the query editor to define XML documents and XML DTDs (see The Query

Editor and XML ) and add and retrieve data using servlets (see Servlet access to

Sentences )

If you export data from Sentences in the form of XML documents you can format it with

a stylesheet and display the data on an HTML page There are a variety of commercial

tools available to make this task easier

This method of developing a user interface clearly gives you much more detailed control

over presentation but at the same time demands a much greater effort on your part and

involves the use of third-party tools You should be aware that the XML Standard is still

evolving and therefore some of the tools and technologies used with XML are still under

development

Using the Sentences client API

If you are an experienced Java programmer you can create programs to submit queries

and receive data using the Sentences client API Using the API allows you to use any

available presentation technology such as Java Server Pages (JSPs) or servlets For more

information see Chapter 10 Customising Sentences and also refer to the Javadoc

documentation in the Doc directory of your Sentences installation

This approach gives you complete control over presentation and over update logic for

your Sentences data but entails some development effort

Using the Sentences HTML5 Interface

The Sentences End User Application Server (SEUAS) currently in Beta is a client to

the Sentences Server that can be deployed as a separate web application End Users can

connect to the SEUAS from any HTML5 compliant browser without the need for any

browser plugins or a Java Virtual Machine on their client device

You can create and customise an EUA definition for each Sentences profile This

definition is used by the SEUAS to generate an application suitable for end users You

can specify which Entities Reference types and Reports are exposed to the user



113

Chapter 4


This chapter explains the basic layout and appearance of the principal parts of the

Sentences client user interface the Sentences Explorer the Dataform and the Query

Editor

Detailed information about using these Sentences features can be found in Chapter

5 ldquoWorking with Sentencesrdquo Chapter 6 ldquoAdvanced techniquesrdquo and Chapter 7

ldquoSentences queriesrdquo

The topics covered in this chapter include

bull tree displays

bull the Sentences Explorer user interface

bull the Dataform user interface

bull the Query Editor user interface

bull the Message Log user interface


Tree structures are a common representation of hierarchical relationships in computing

They generally comprise a number of elements or nodes that are linked together in such a

way that any node may have no more than one predecessor and any number of successors

The predecessor of a node is called its parent and successor nodes are called children

The node that is the origin of a particular tree and as such has no parent is known as the

root It is customary to place the root at the top of a tree diagram

In Sentences both the schema and the data of the database are represented in the Explorer

as tree structures Tree structures are also used in the Query Editor The tree structure is a

useful graphical metaphor of the relationships between entities and associations even

though the Sentences database is not hierarchical The structure of the Sentences database

actually resembles a net more than a tree as its component elements can be linked to each

other in multiple ways In addition associations in Sentences are not links between

different nodes in a hierarchical tree they are nodes in their own right For more

clarification on the use of entities and associations in Sentences see the section ldquoEntities

and associationsrdquo



114


Figure 4-1 The Sentences Explorer

With the Sentences Enterprise Edition the Sentences Explorer runs as either a Java applet

in a web browser or as a Desktop application (see ldquoRunning the Sentences clientrdquo ) In

the Sentences Personal Edition the Sentences Explorer runs as a stand-alone application

The Sentences Explorer has its own toolbar menubar and status bar and is divided into

two panes with the schema displayed on the left and data displayed on the right The

information in each of the panes is shown in a tree display

The following sections look at the various parts of the Sentences Explorer

The Explorer Menu bar

The Sentences Explorer menu bar provides access to a number of pull-down menusThe

menu names and the groups of commands on each menu are listed below

menu namehellip has commands abouthellip

File

Create a new profile or open edit delete and refresh existing

profiles reload data based on Positioner and Filter settings

log out or change password

Edit Edit data and view the selected itemrsquos Properties

View

Change the current Explorer display display additional

database information change user preferences and session

options

Schema Edit and build your schema create and edit Display Name

Queries

Query Use queries and work with query results

Tools

Access to tools for User administration Server configuration

External data sources Diagram editing Text file imports and

the End User Application

Help Help topics Tutorial and support information



115

Some menu commands are only available when certain items are selected in the Explorer

Some menu commands are not available in certain Sentences editions or may be disabled

for certain users For example if the FixedProfile parameter in the applet or jnlp

definition has been set to yes the profile commands are not available

A full list of menu commands is given in Appendix A lsquoMenus and Commands summaryrsquo

The Explorer Toolbar

The Sentences Explorer toolbar is located beneath the menu bar The toolbar buttons give

rapid access to some frequently used commands


Open Profile use the Open Profile dialog to open a profile

Refresh Profile refresh the data in the current profile


Create entity type create a new entity type

Create association type create a new association type

Create query create a new query object

Properties

open the properties dialog for the selected entity

or association open the Query Editor for the

selected query




Delete delete the selected item displays the delete

impact dialog

Dataform

open the Dataform for the selected entity type or

entity instance or association instance

New tab opens a new Sentences Explorer tab on the

selected item

New tab on target

opens a new Sentences Explorer tab on the target

of the selected association

close tab closes the current tab

Positioner valuefield data entry field for the Positioner tool

Filter value field data entry field for the Filter tool

reload data

reloads data using current Positioner and Filter

conditions displays the results of a selected query

help displays help

Copying and Pasting

Any items you cut or copy from the Sentences Explorer Dataform or Query Editor are

held on the operating system clipboard and can be pasted into Sentences or other

applications However you can only paste a Sentences object into the same instance of

Sentences from which it was cut or copied If you paste a Sentences object into another

application or into another instance of Sentences you are only pasting the text

representation of the Sentences object without its unique internal identifiers

Dataform Tables can be copied (using the context menu on the first column) and pasted

into another application such as Microsoft Excel Similarly a range of cells copied from

Excel can be pasted into a Dataform Table providing the datatypes of the columns are

compatible



116

Finding data

For more information about locating data in the Sentences Explorer and using the

Positioner and Filter tools see the section ldquoLocating data in the Sentences Explorerrdquo

Sentences Explorer tooltips

The Sentences Explorer includes tooltips in a number of places If you position your

mouse pointer over the objects listed below you can see a brief explanation of the object

as follows

Position of mouse pointer Tooltip displayshellip

over the toolbar icons a brief explanation of the tool command

represented by the icon

over an association type in the

schema pane

the association typersquos name its cardinality

settings (see ldquoCardinalityrdquo ) and where

appropriate the LazyView connection name and

mapped column or key

over an entity type in the schema

pane

the entity typersquos name and its datatype and

where appropriate the LazyView connection

name and mapped column or key

over an entity instance in the data

pane

the name of the type and name of the instance

and the datatype of the instance (the instance

datatype is not shown if it is identical to the

name of the entity type or if it is ltNonegt)

over the profile schema tab list of the chapters used for schema data and

query changes in the current profile

over a query in the schema pane a list of the queryrsquos parameters and any default

parameter settings

Tree displays in the Sentences Explorer

The Sentences schema tree shown in the Explorer schema pane is made up of all the

entity types association types and values types in the current profile For convenience

these are displayed in the All types folder and Core types folder

The name of the profile is displayed on the schema pane tab Although it is not displayed

as the root node in the schema pane the profile is the parent of all the entity and value

types in the profile Subsequent levels open up below and to the right Moving ldquodownrdquo

the schema means moving away from the root

The data pane displays all the available instances for the association or entity type

selected in the schema pane Each instance functions as the parent node for the display of

all the associations that it takes part in as either source or target

Nodes and icons

Any instance or type displayed in the Explorer is a node in the tree display and can be the

parent of other nodes For example a node representing an entity type is the parent of all

the associations that it takes part in as either source or target

Each kind of node has its own distinctive icon In the schema pane entity types are

represented by magenta cubes value types by magenta discs and association types by

magenta arrows Yellow cubes discs and arrows represent subsets Arrows pointing down

and to the right represent forward association types in which the parent node is the source

Arrows pointing up and to the left represent inverse association types where the parent

node is the target



117

The shapes of the icons used in the data pane match the shapes used for the corresponding

types however they are all coloured cyan rather than magenta

Any association or association type is automatically the parent of its source and target

Source and target nodes are displayed when you double click an association type or

instance or when you select Show source and target from the shortcut menu

Yellow folders in the schema and data pane are used for collections of multiple instances

of the same type of things such as subset and supertype relations between entity types or

multiple associations

The Data Pane can display Page Nodes in the results These Pages are equivalent to the

pages generated in a Base Dataform They are a way of organising associations into

groups See ldquoUser Preferencesrdquo to turn display of Page Nodes in the Data Pane on and off

The Data Pane can display Inactive instances For details of inactive instances see

ldquoInactive instancesrdquo See ldquoUser Preferencesrdquo to turn display of Inactive instances in the

Data Pane on and off

Schema and data pane features

The schema and data pane in the Sentences Explorer share a number of commonfeatures

such as icons and tabs

Schema and data pane icons

The schema and data pane icons are shown in the following list

Icon Description

folder for groups of similar items

has subset or subtype of used for multiple associations

superset of or supertype of used for subset query used for multiple


has subset or subtype of also shows equivalence also shows

custom datatypes

subset of or supertype of also indicates subset query

entity type (magenta)

value type (magenta)

association type (magenta)

inverse association type (magenta)

metatype (magenta)

subset entity type (yellow)

subset value type (yellow)

subset association type (yellow)

inverse subset association type (yellow)

entity instance (cyan)

value instance (cyan)

association instance (cyan)

inverse association instance (cyan)

icon with a mark to the right indicates source of association type or

instance

icon with a mark to the left indicates target of association type or

instance

query



118

Expand node and collapse node buttons

The tree display in both panes of the Sentences Explorer is nested For example

association types are displayed beneath the entity type which is their source An expand

node button [plus sign (+)] is used to show that there are more nested nodes that can be

viewed The expand node button changes to a collapse node button [minus sign(-)] when

you expand the node

The expand node button is displayed in the Sentences Explorer schema pane next to type

nodes that are the sources of any association and in the data pane next to an instance that

has an association instance or an instance-specific association or where the entity type of

which it is an instance is not the source of any association type but only a target

You can double-click a type or instance to display all the associations that it is used in

either as a source or as a target

An association type that is not the source of a further association type does not show the

expand or contract symbol However you can double-click on an association type name

to display its source and target or select Show source and target from the shortcut

menu

Sentences Explorer drill-down

The tree display in both panes of the Sentences Explorer is recursive This means that you

can start navigating at any node and follow any chain of entities and associations through

the schema and data The practice of navigating through the schema and data by

selectively expanding nodes is known as ldquodrill-downrdquo Drilling down gives you

unrestricted access to data by alternative routes as you can follow chains of entities and

associations by clicking on successive source or target nodes

There is no limit to the depth that you can drill down although the data displayed


Sentences Explorer tabs

Explorer tabs appear at the top of the data and schema pane The default tab for the

schema pane is the current profile which is the parent node for all the types in the schema

The name of this tab is fixed

When you position your mouse pointer over the profile schema tab Sentences displays a

list of the chapters used for schema data and query changes in the current profile

The default tab in the data pane displays the name of the type that is currently selected in

the schema pane and therefore changes with each selection If no type is selected in the

schema pane the data pane default tab displays the profile name

You can modify the display in the schema pane and the data pane by selecting a different

object to be the temporary root of the current display This can aid viewing when working

with a large database You can highlight any object and create a new view based on it or

in the case of associations and association types based on the target Each view is

displayed on a separate tab page in the schema or data paneThese views are temporary

and are not saved



119

Figure 4-2 Example of Sentences Explorer tabs

You can use the blue arrows on the toolbar or the Create Tab commands on theView

menu to create and remove tabs

The root tab in the schema pane always shows the name of the current profile Any

schema type can be made the root of a new tab If the selected item is an association or an

association type you can open a new explorer tab on the items target You can open as

many tabs as you need

The data pane always shows the instance data for the active schema pane selected type

When you switch between schema tabs open data pane tabs are closed and are not saved

Tabs can also be removed using the Remove Tab command which is on the tab shortcut

menu and on the View menu or by clicking the Remove Tab toolbar button You cannot

remove the original default tabs

The schema pane

The schema pane is used to develop and display the structure or schema of your

Sentences database This pane displays entity value and association types The data pane

is used to display specific information about the entity value and association instances in

your database



120

Figure 4-3 The Sentences Explorer Schema pane

The left-hand schema pane always shows the schema folders Core types Core queries

All types and All queries

All the types queries in your schema are always listed in the All types and All queries

folders respectively The Core types and Core queries folders are convenient ways of

displaying the most frequently used types and queries




Finding schema

With large schemas the Schema Filter can be used Typing into the filter text box at the

bottom of the schema pane will limit the schema displayed as you type Unlike the

Positioner and Filter tools you cannot use wildcards but you can enter multiple words

The schema folders will have a filter icon next to them when they are not showing the

entire contents

The Core types folder

The Core types folder displays a selection of entity types most central to your schema

When you create a new profile you can choose to select the types for the Core types

folder yourself or you can allow Sentences to select the types automatically

If you allow Sentences to select types automatically then any entity type which is the

source of an association which is itself the source of a further association is displayed in

the Core types folder When you allow automatic selection for the Core types folder if

there are no association types in the current schema that are sourced from association

types then nothing is displayed in the Core types folder

If you choose to make the selection for the Core types folder manually you can select an

entity type by checking the Display in core types folder check box on the General page



121

of the Properties dialog Alternatively right-click on an entity type and select Display in

Core types folder from the shortcut menu

The Core queries folder

The Core queries folder displays a selection of queries most central to your schema

There is no automatic selection option for the Core queries folder You must always

choose the queries that you want to display in the Core queries folder

To display a query in the Core queries folder right-click on a query name in the schema

pane and select Display in Core queries folder from the shortcut menu

The All types folder

The All types folder contains all the entity and value types in the current profile

including those in the Core types folder You can build your database schema by adding

entity types and association types in the All types folder Association types are displayed

beneath their source entity types and inverse associations are displayed beneath their

target entity types You can use the expand node buttons to drill-down through the

schema

The All queries folder

The All Queries folder displays a list of all the queries in the current profile

You can also execute a query in the Sentences Explorer Select a query name and choose

Execute Query from the shortcut menu or from the Query menu The results are

displayed in the Explorer data pane

The data and properties pane

Figure 4-4a The Sentences Explorer Data Pane

The data pane displays the entity value and association instances that make up the data

in the database The characteristics of the entities and associations are determined by the

properties of the corresponding association types and entity types

The display of data is always nested allowing easy movement from entities to

associations In the data pane you can drill down from an entity to an association and

from there to another associated entity without any practical limit The data displayed







122

Figure 4-4b The Sentences Explorer Data Pane - Table view

If enabled in the user preferences you can view the data as a table rather than a tree of

data This limits you to viewing only singular Association Types The TableTree view is

changed by selecting the icons on the tab In the above case to the right of Group

company

Figure 4-4c The Sentences Explorer Schema Properties Pane

If enabled in the user preferences you can view the peoperties of the selected schema in

the right hand pane This allows you to quickly view and amend schema propertiesScroll

bars

The Sentences Explorer displays horizontal and vertical scroll bars automatically

whenever the amount of data to be displayed in either pane is too large for the space

available

The Status bar

The status bar is at the bottom of the Sentences Explorer window On the left-hand side is

a status indicator which displays either Workinghellip or Ready

In the centre is a display of the number of instances displayed This display does not

appear if there are more instances on the server which have not yet been loaded on to the

client In this case the Morehellip prompt is displayed at the end of the list of instances in

the data pane



123

On the right-hand side of the status bar is a server connection indicator The indicator next

to the server name is green when you have a valid server connection

Divider bar

The schema pane and data pane are separated by a divider bar You can drag the divider

bar to any convenient position in the Sentences Explorer Click the upper left facing

arrow to hide the schema pane and display only the data pane Click the lower right

facing arrow to hide the data pane and display only the schema pane

You may also use F8 to select the divider bar and then use the left and right arrows to

move it Use the Tab key to deselect the divider bar

Shortcut keys

Sentences windows menus and dialogs support keyboard shortcuts and accelerators The

shortcut key character is indicated with an underscore in menu listings Press Alt and the

shortcut key to use the accelerator Sentences also uses standard shortcuts On Windows

the Ctrl key and on Mac OS X the Command key ( ) are combined with the keys C V

and X for copy paste and cut respectively

Sentences specific shortcuts are

Ctrl+D default Dataform

Ctrl+P Properties dialog

Ctrl+N New Profile dialog

Ctrl+C Open Profile dialog

F6 toggle between schema and data panes

You can press the Tab key to move between fields in any Sentences window or dialog

You can use the up and down arrow keys to select menu items and you can use the Esc

key to close a menu You can use the left and right arrow keys to move the cursor in

editable fields and you can use the Home and End keys to go to the top and bottom of

lists of data Using the Page Up and Page Down keys to page through the displayed data

If there is more data in the database than Sentences can display in the current pane the

Morehellip prompt is shown Double-clicking the Morehellip prompt or pressing the Page

Down when the Morehellip prompt is highlighted retrieves more data items (see ldquoDemand


All the available shortcut keys are listed in Appendix A lsquoMenus and Commands

summaryrsquo

Display Session Options

There are several options that you can choose from that last for the duration of the

session after which they revert back to their defaults

To view the Session Options select Session Optionshellip from the View menu or select

Optionshellip from the status bar context menu



124

Figure 4-5 The Session Options dialog

You may want to see which objects in your Sentences database are stored in which of

your profile chapters and you may want to be able to distinguish between different

objects that have the same display name You can do this by displaying the internal

identifiers that Sentences uses for chapters and other objects

There are three possible settings for the Options dialog None (the default) Chapter

numbers and Chapter numbers and Object IDs If you select Chapter numbers

Sentences displays a number next to each item displayed in the Sentences Explorer

representing the database chapter in which that object exists for example [2] The number

corresponds to the position of that chapter in the available chapters list in the Edit Profile

dialog

If you select Chapter numbers and Object IDs Sentences displays next to each item

displayed in the Sentences Explorer a number representing the chapter file followed by a

number representing the object in the chapter files (its surrogate) for example [22097]

The storage chapter location is significant for entities and associations but not for values

as they are stored in all the chapters in a profile For this reason Sentences displays a large

number above 32000 as the chapter number for values



125

Figure 4-6 Sentences Explorer view with Chapter numbers and Object IDs option

selected

The Session Options also include options for using the Sandbox functionality (see

ldquoSandbox Modesrdquo) and setting the Transaction Visibility timestamp (See ldquoTransaction

Visibilityrdquo)

Support information

You can view a list of currently set parameters and other information useful for technical

support and diagnostic purposes in the Support Information pages

To view this information select About from the Help menu and then click Support

Information The information is divided into three sections as shown in Figure 4-7

Figure 4-8 and Figure 4-9

Figure 4-7 General support information page



126

Figure 4-8 Client parameters information page

Figure 4-9 License information page

In the Enterprise Edition the Support Information display shows the Chapter Version

and Communications Version numbers (which are internal references for support

purposes only) a list of any client parameters that have been set (see ldquoUserdefined

parametersrdquo ) and a list of certain applet parameters if they have been set (see ldquoSentences

applet parametersrdquo ) In the Personal Edition application parameters are shown instead of

applet parameters (see the Personal Edition Supplement for details)



127

Explorer shortcut menus

Figure 4-10 An example of a shortcut menu

When an object is selected you can display a shortcut menu by clicking the secondary

button on your mouse or by pressing Shift + F10 on your keyboardEntity types

association types entities associations queries and parameters displayed in the Sentences

Explorer all have shortcut menus associated with them

The command options on these menus are taken from the Schema menu the View menu

and the Edit menu The keyboard shortcuts available with each command are also

displayed on the shortcut menu The commands available differ from time to time

according to the circumstances

If the selected item is a hyperlink in the data pane the shortcut menu includes a Follow

Hyperlink option

There are separate shortcut menus available for each of the system folders and for queries



128


The Dataform is Sentencesrsquo unique dynamic format for creating editing and browsing

data Dataforms are created automatically from the Sentences schema and display the

associations sourced from a type

A typical Dataform is shown in Figure 4-11

You can open the Dataform for an object by selecting Default Dataform from the

shortcut menu or by pressing Ctrl + D or by clicking the Dataform button on the toolbar

Figure 4-11 A typical Dataform

Different kinds of Dataform

Sentences can create a Dataform which automatically displays all the associations sourced

from a specified type This is known as the base Dataform You can use the Query Editor

to design and save a custom Dataform that may only display a selection of the available

associations for that type A custom Dataform can include associations that use the

specified type as their target You may define either the base Dataform or a custom

Dataform as the default Dataform for a type

For more details see ldquoThe base Dataform and the default Dataformrdquo

If a dataform contains fields which are calculated then it will by default automatically

refresh these calculations whenever a field is changed This ldquoauto-refreshrdquo function can be


You can open a Dataform on an entity type and use it to create new associations This is

known as a Create Dataform You can also open a Dataform on any instance which can be

used to update existing associations This is known as an Update Dataform For more

details about Create Dataforms and Update Dataforms see ldquoCreate and update

Dataformsrdquo



129

You can often open a new Dataform from a field on an open Dataform using the shortcut

menu for the field In most cases changes you make in these Dataforms do not effect the

original Dataform For more details see ldquoParent Dataforms and child Dataformsrdquo

You can display a Dataform from the Explorer or from another Dataform and you can

also configure a Dataform to run in its own Java applet so that it can be displayed on its

own or as part of some other suitable web page For more details see ldquoThe Dataform

appletrdquo

Title bar

The Dataform title bar always displays the name of the source object of the associations

being displayed This source object may be an entity or an association On a Create

Dataform the title bar is always New xxx where xxx is the name of the entity or

association type

Dataform tabbed pages

The associations displayed on a Dataform may be distributed on two or more tabbed

pages as illustrated in Figure 4-11 If the type or instance for the Dataform has subsets or

supertypes or has an equivalent type the base Dataform has multiple pages one for each

of these related types If you create instance-specific associations they are displayed on a

separate tab when the Dataform for that instance is displayed For more information see

ldquoSubsets properties pagerdquo ldquoSupertypes properties pagerdquo and ldquoEquivalence properties

pagerdquo

The base Dataform displays the source object as an instance of its own type an instance

of any of its supertypes an instance of its superset type an instance of any of its

supersets subset types or an instance of its equivalent types simultaneously The base

Dataform creates a tabbed page for each of these types for which one or more associations

exist A custom Dataform creates tabbed pages as required for the association types

selected for it You can also add Page nodes in the Query Editor to create additional

tabbed pages on a custom Dataform (see ldquoPage Nodesrdquo )

For example the Dataform shown in Figure 4-11 above is from the Human resources

example application in which Employee is a subtype of Person and Resource is a

subset of Employee Employee Resource and Person are each the source of

association types The result is that these three related source types are each represented

by tabs on the Dataform

Further examples of the way using subsets and supertypes affects the display of the

Dataform are given in Chapter 6 ldquoAdvanced techniquesrdquo (see ldquoDataform tabbed pages

with subsets and supertypesrdquo )

Labels and fields

The Dataform displays two objects a label and a field for each of the source objectrsquos

associations The label is based on the verb of the association and the field is where you

can create or update the target for the association

The presentation format of the target field is based on the Format settings in the

Properties dialog for the target object For example a multiple association (an

association that permits more than one target for the same source) is displayed on the

Dataform with a multiple line entry field

The labels of mandatory associations are marked with an asterisk () on theDataform

Sentences does not allow you to save a Dataform if you do not supply a value for a

mandatory association



130

Ellipsis button and picker lists

Some Dataform fields have an ellipsis button to their right You can use this button

to select a target from a list of existing target type instances

Figure 4-12 A picker list from a Dataform ellipsis button

When you click the ellipsis button Sentences displays a picker list showing all the

available instances of the associationrsquos target Every picker dialog includes the Positioner

and Filter tools to help you select the target you need If there are more target items than

can be displayed the picker list includes the Morehellip prompt

Dataform shortcut menus

Figure 4-13 A Dataform shortcut menu



131

The options in the shortcut menu from a Dataform field allow you to open additional

Dataforms to view or create instances

Sentences uses the association verb and target type names and the current target instance

name as the names of the shortcut menu options The available options include viewing a

Dataform for the current association viewing a Dataform for the current target instance

creating a new association creating or selecting a new target and deleting the current

association If the target is a hyperlink the shortcut menu includes a Follow Hyperlink

option


Figure 4-14a The Query Editor

A full description of the Query Editor including details of how to create and edit queries

is given in Chapter 7 ldquoSentences queriesrdquo This current section describes the main

features of the Query Editor window

Figure 4-14b The Query Editor - Properties



132

Rather than open a dialog to edit the properties of each request node the right hand pane

now contains a Schema tab and a Properties tab When you select different query nodes

the appropriate properties are displayed in the right hand properties tab Note The Query

Editor used in Sentences version 1 is now referred to as the Set Query Editor If you need

information about using set queries and the SetQuery Editor please contact

supportsentencescom

Query Editor menu bar

The Query Editor menu bar contains the following menus

Menu namehellip has commands about

Query saving a query and query properties

Edit adding request nodes derived type nodes and sort and

selection nodes

closing binding and hiding nodes editing expressions

standard editing actions query node properties

View expanding and collapsing the request or result tree

Parameter creating and using parameters

Results execute a query export a CSV file export DTD export or

view XML results export XSL stylesheet

Dataform testing a custom Dataform

Help accessing help information

Query Editor toolbar

The Query Editor has the following buttons


Execute execute (run) the query


Save save the query

Properties

view or edit the properties for the

selected node




Delete

delete the selected item displays

the delete impact dialog

Dataform

display the default Dataform for the

selected item

Custom Dataform

display the custom Dataform for

the selected item

Expand Tree expand all the nodes in the tree

Collapse Tree collapse all the nodes in the tree

Expand Node expand the current node

Collapse Node collapse the current node

Query Editor icons

The icons used in the query request tree for nodes are similar to those used in the schema

pane for association entity and value types



133

Similar icons are used in the query result both in the query results pane of the Query

Editor and in the Sentences Explorer Query result icons are always displayed in green to

distinguish them from database instances

Icon Name

query name

entity type node (magenta)

association type node (magenta)

value type node (magenta)

forward or inverse request node in a recursive closure loop

derived type node

page node

result entity (green)

result value (green)

result association (green)

expression

selection node

sort node

transitive closure node

Error

Query pane

The query pane occupies the top left hand side of the Query Editor window This is where

you build your query by creating a query request tree

Schema pane

The schema pane occupies the right hand side of the Query Editor window This pane

contains a copy of the contents of the All types folder from the Sentences Explorer

schema pane After you start building your query the Query Editor schema pane displays

only those types that could be used at the currently selected query node You can drag and

drop or copy and paste the entity and association types you need to use in your query

from here

Results pane

The results pane occupies the bottom left hand side of the Query Editor window When

you execute your query the results are displayed here If the query takes longer than a few

seconds then a progress panel appears to show you when the query started the duration

and how many instances have been processed so far The instances are a count of root

items even if they have subsequently been excluded from the final results but gives you

and idea of progress if you know how many items there are in total

Query Editor status bar

The status bar is at the bottom of the Query Editor window and has two parts the status

indicator which usually says Ready and an item counter

The item counter indicates the number of items in the query results set currently loaded in

the data pane which may be less than the total number in the database (see ldquoDemand


The Message Log


134

Query Editor divider bars

There are two divider bars in the Query Editor window a horizontal bar between the

query pane and the results pane and a vertical bar between these two panes and the

schema pane

You can drag the divider bar to any convenient position in the Query Editor Click the

arrows on the divider bars to snap them to the appropriate edges of the Query

The Message Log

Sentences displays a message in the Message Log whenever it is unable to complete an

action you requested The message that Sentences displays should help you identify and

resolve the problem For example if you try and save a Dataform without giving a value

for a mandatory association field Sentences displays the Message Log with a message

reminding you to complete the mandatory field

Sentences displays the Message Log when an error occurs anywhere in Sentences

including the Explorer the Dataform and the Query Editor

You can view the Message Log at any time by selecting Messages from the View menu

Sentences messages are classified in three groups Errors Warnings and Information

and you can use the check boxes on the message log display to select which kinds of

messages you wish to see

Figure 4-15 The message log

You can copy the text of messages from the message log by using the Copy command on

the shortcut menu for the message log You can then paste the message text into another

application using the appropriate commands for your systemEditor window



135

Chapter 5


This chapter describeshow to work with Sentences to design create and use a

database

The topics discussed in this chapter include

bull working with profiles and chapters

bull using the Sentences Explorer

bull locating data in the Explorer

bull properties datatypes and formatting

bull working with the Dataform

bull working with the Dataform Picker and Query applets

bull data exchange with external formats


A Sentences database is highly flexible being made up of chapters which are files in

which data is stored and profiles that define which chapters are visible to usersThis

flexibility means that you can control access to certain kinds of data in your database by

excluding or including the chapter containing that data in a particular profile

Both the structural schema information and the data content of a Sentences database are

stored in chapter files User access to the database is through a profile which is a selection

of one or more of the database chapters Different users may use different profiles with a

different selection of chapters to access the same database (see ldquoCreating database views

using profiles and chaptersrdquo )

Updates and changes to the schema or data information in a database are stored in

chapters that you specify when you create or edit a profile (see ldquoUsing the Edit Profile

dialogrdquo ) Using separate chapters for schema data and query changes allows you to

separate schema information from data information in your database and to create

different views for different users and therefore this is strongly recommended For more

details see ldquoUsing multiple profilesrdquo 0 and ldquoCreating database views using profiles and

chaptersrdquo

In addition to the chapters defined as changes chapters a profile may contain other

chapters The schema and data information in these chapters is available to

Sentences and is displayed and used in the profile but any updates and changes are made

only to the defined changes chapters

All the commands concerned with managing chapters in a profile including creating

adding removing and defining changes chapters are accessed through the Edit Profile

dialog

Data and schema updates

All data or schema changes made using the Sentences client are updated to the database

as soon as they are executed This means that when you select Save or Delete in any

Sentences Explorer dialog or select Save Save amp Reset or Save amp Edit in the

Dataform your changes are applied to the database immediately



136

You must select the Save command to save queries when you are using the Query Editor

Any Dataform that has an Apply or an Apply amp Reset button is known as a child

Dataform Changes you make in a child Dataform are only saved to the Sentences

database when the parent Dataform is saved (see ldquoParent Dataforms and child

Dataformsrdquo) In some circumstances the server may not accept the update (see

ldquoTransaction processing in Sentencesrdquo)

If you make changes in the Dataform and close the Dataform without clicking on Save

the changes you made are not saved Sentences displays a warning message if you close a

Dataform that contains unsaved selections

Chapter file locations

You can place your database chapters in one or more defined locations The possible

locations must be listed in the Serverproperties file under the ChapterPathList

property (see ldquoThe Serverproperties filerdquo) The first location listed for this property is the

location you selected for chapter files when you installed Sentences This is the default

location for all chapter files including the system chapters

The defined locations may be on one or more computers which can be accessed as local

or network drives When you create a new chapter you must specify the location from the

drop-down list in the New Chapters dialog The directory path names that appear in this

list are based on the paths as viewed from the computer running the Sentences server

System chapters

Sentences uses three system chapters Metaschemachap Schedulerchap and

Profileschap When you install Sentences these chapters are placed in the location you

specify for chapter files You can move these files to another location but if you do so

you must specify the new location under the SystemChapterPath property in the

Serverproperties file You must shut down the Sentences server before you move the

system chapters

Metaschemachap contains information that is internal to Sentences It does not contain

any user-visible or user-modifiable data You should not delete this file or attempt to

modify it in any way If this file is deleted accidentally Sentences creates a new copy of

this file when the Sentences server starts up

The Profiles database and the Profiles profile

The system chapter Profileschap contains information about all the profiles in your

Sentences installation Do not delete this file or attempt to modify it in any way If this

chapter file is deleted accidentally Sentences creates a new copy of it when the Sentences

server starts up A new copy of profileschap created by Sentences does not contain

any information about your profiles In this situation use the Edit Profile dialog to create

all the profiles you need including the example profiles included in a default Sentences

installation

Sentences includes a system profile named Profiles that is hidden from users by default

This profile contains one chapter Profileschap and constitutes a profiles database

This profile can be addressed using the Sentences API

To make this profile visible to users and to view the profiles database in the Sentences

Explorer you can set the optional applet parameter ProfileProfileVisible to Yes (see

User-defined parameters) You cannot give the name Profiles to a profile that you create

and you cannot delete the Profiles profile if it is visible

Sentences 40 extends the Profiles database and profile to include User Security details

As a User Administrator you may open the Profiles Profile to administer users by

selecting Administer Users from the Tools menu



137

The Profiles profile now includes two additional queries The first is used to export the

Users and their privileges This can be used in conjunction with the original two queries

for exporting chapter and profile information

Another new query identifies Chapters that have been orphaned Orphaned Chapters are

no longer used by any profiles This is useful when housekeeping the chapter directories

System administrator passwords

With the introduction of a User Security model the System Administrator requires an

initial password which must be changed at first login to the system

For the Personal Edition this is hard-coded as ldquoSys Adminrdquo For the Enterprise Edition

each license file contains itrsquos initial encrypted password

If the System Administrator looses their password then the only way to regain access is to

delete the Profiles profile This will restore the original password that came with the

license file but you will loose all your chapter profile user role and privilege

information

It is advisable to use the built-in queries to regularly back-up the profiles database The

individual user passwords will not be exported in plain text

Using multiple profiles

You can create multiple profiles that use different selections of chapters from the same

database A userrsquos view of the database is defined by the sum of all data and schema

updates in the chapters of their profile and therefore different users can have different

views of a single database You can use the profile mechanism to customise different

Sentences views for different users For more details see ldquoCreating database views using

profiles and chaptersrdquo

Profile and chapter commands

The Sentences Explorer File menu includes commands for creating opening editing and

deleting profiles

Command name Action

New Profile displays an empty Edit Profile dialog

Open Profile displays the Open Profile dialog

Edit Profile displays the Edit Profile dialog with details of

thecurrent profile

Delete Profile displays the Delete Profile dialog

Refresh Profile closes and reopens the current profile

You can export a database and the profiles it contains and import the chapters that make

up the database using server commands For more details see ldquoExporting and importing

databasesrdquo

Profile and chapter constraints

You must be aware of the following constraints in the use of profiles and chapters

bull A schema definition specifies separate changes chapters for schema data and query

information Users can only save updates to the database if the definition of the current

profile includes an appropriate changes chapter For example if the profile definition does

not specify a query changes chapter users cannot save any changes they make to queries

(see ldquoChanges chaptersrdquo)



138

bull When the FixedProfile parameter in the jnlp or javascript definition is set to ldquoyesrdquo

the profile commands on the File menu are not available and users cannot change their

Sentences profile (see ldquoSentences Applet Parametersrdquo)

bull The EditOption parameter in the jnlp or javascript definition can restrict a userrsquos

ability to change parts of the database For example when the EditOption parameter is

set to data users cannot save changes to the schema even if a Schema changes chapter is

specified in the Edit Profile dialog (see ldquoSentences Applet Parametersrdquo)

bull You cannot open or edit a profile if one or more of the chapter files used in the profile is

no longer available for example if it has been deleted from disk In this case you can

create a new profile with valid chapter files and give it the same name as the profile that is

no longer valid and this overwrites the previous invalid profile information

The Open Profile dialog

Figure 5-1 The open profile dialog

All the profiles available are shown in the Open Profile dialog The list of available

profiles is controlled by the Profileschap file on the Sentences server

You can only use one profile in any Sentences session at any time Opening a profile

closes any previous profiles However you can run more than one Sentences session at a

time

You can open the Open Profile dialog by selecting the Open Profile command on the

File menu or the Open Profile button on the Sentences Explorer toolbar

Creating a new profile

To create a new profile select New Profile from the File menu Sentences displays an

empty copy of the Edit Profile dialog See the section below for details

Creating a new profile with the profile wizard

Version 40 introduces a New Profile Wizard to assist with the repetitive task of creating a

new Profile with one data chapter and one schema chapter set as the appropriate targets

for data schema and query changes

The wizard also helps with the creation of Profiles that can dynamically or statically

connect to Relational Databases

Creating a new standard profile using the wizard

To create a new standard Profile follow these steps



139


open The default choice is to create a Standard Profile so you can leave this

unaltered


3 If you select Show Advanced to view the advanced properties you will see that









process so for very large databases you have the option for a Profile to assume

that child associations are present and always show a plus sign To choose to

assume that child associations are present unselect the checkbox

7 Select Finish to create the new profile

Creating a new LazyView profile using the wizard

To create a new LazyView Profile follow these steps


open

2 Select External Data




140

If you select Show Advanced to view the advanced properties you will see that









process especially for dynamic LazyView profiles For these and very large

databases you have the option for a Profile to assume that child associations are

present and always show a plus sign To choose to automatically determine

whether a tree node has any children select the checkbox

7 Select Next to progress to the next page



141

The second page allows you to enter details of the database you wish to connect to

8 Select the Database Vendor There may be several different database versions for

each vendor

9 Enter the Server name where the database is located If you have connected

successfully to that database before then the drop-down list will contain the

server and you can select it from the list

10 Enter the Database name If you have connected successfully to that database

before then the drop-down list will contain the name and you can select it from

the list

11 For Microsoft SQL Server only you have the option of selecting Integrated

Security If so then your Windows credentials will be used to connect to the

database

12 If Integrated Security is not available or desirable then enter the username and

password that will allow you access to the database

13 By default once a LazyView Profile has been created the LazyView wizard will

be opened for you to define the mapping between relational database and

Sentences You may optionally deselect the checkbox if you do not wish to

perform the mapping immediately

If you select Show Advanced to view the advanced properties you will see that the

profile name you have entered is used to generate the default name for the Lazy View

chapter



142

14 You may optionally change the Lazy View chapter name

15 You may optionally choose an alternative JDBC Driver

16 You may optionally change the port number used to connect to the database if it

is not the default one shown If you have connected successfully to that database

before then the drop-down list will contain the ports used previously and you

can select it from the list

17 The option choices dictate whether you would like to connect statically or

dynamically to the database For details see the LazyView - Using Sentences to

view relational databases section

18 You can click on the Test Connection button to test your connection parameters

If you do not the connection will be tested when you select Finish

19 Select Finish to create the profile and launch the LazyView Import Wizard (if

requested) or Back to return to the previous page

The Edit Profile dialog

Figure 5-2 The edit profile dialog

The Edit Profile dialog is displayed when you select either New Profile or Edit Profile

from the File menu When you select New Profile the Edit Profile dialog is displayed

with no information When you select Edit Profile the Edit Profile dialog is displayed

with the settings for the current profile

Using the Edit Profile dialog

The Edit Profile dialog is shown in Figure 5-2

bull Profile name

Enter a name for the profile in the profile name field You can refer to a named profile in

the jnlp or javascript definition for the Sentences client applet in the start up pages for



143

other Sentences applets and when using the Sentences API Because of this you should

make sure that profile names do not include any special characters that need to be

represented by escape sequences in HTML which may not be interpreted correctly by

Sentences

Note The name Profiles is reserved for the system profiles database and cannot be used for

user-created profiles (see ldquoThe Profiles database and the Profiles profilerdquo )

bull Renaming a profile

You can change the displayed name of a profile by entering a new name in the Profile

name field Sentences does not actually rename the profile but creates a new profile with

the new name you have entered If the new name is the same as that of an existing profile

the existing profile is overwritten

If you only change the case of a profile name when you edit it this does not create a new

profile

You can reset the profile definition used on a client to be the same as the current saved

version of the profile by selecting the Refresh command on the File menu or by clicking

the Refresh button on the toolbar

bull Profile description

You can optionally enter a description for the profile that will appear in the Open Profile

dialog

Chapters

The chapters field lists all the chapters that are available in a profile (the available

chapters) The schema and data information in all the available chapters is displayed and

used in the profile

Changes to schema data or query information are saved in the specific chapters defined

for schema data and query changes

Changes chapters

Use the Edit Profile dialog to set the active chapters which Sentences uses for updating

changes to the schema data and queries of your database These are known as the

Schema changes Query changes and Data changes chapters

Although you may use the same chapter for more than one of these change chapters using

separate chapters makes it easier to create different profiles for different users

A user may save changes to the database only if the appropriate changes chapter is

defined in the Edit Profile dialog This means that if a Schema changes chapter is not

specified users cannot save changes to the database schema and if a Data changes

chapter is not specified users cannot save changes to database data If a Query changes

chapter is not specified users can create new temporary queries and run them in the

Query Editor and make temporary changes to existing queries butthey cannot save any

of these changes

Generate Core types automatically

The Core types folder displays a selection of the types in your schema (see ldquoThe Core

types folderrdquo ) The selection of types for this folder can be manual or automatic To

choose automatic selection check the Generate core types automatically checkbox To


Determine if child associations are present





144





Metaschema)

Saving a profile

When you make any changes to a profile you can either save the changed profile or

modify the current profile to use the changed settings for your current Sentences session

only or discard all your changes

After you make any changes the OK button is available Click OK if you wish to save

your changes or use your changed setting for the current session only Sentences displays

three options in a confirmation dialog

bull Yes confirms and saves all your changes to the profile

bull No modifies the profile to use the changed settings for the current session only but does

not update the saved profile

bull Cancel returns you to the Edit profile dialog

To discard your changes click Cancel in the Edit Profile dialog

Deleting a profile

To delete a profile select the Delete Profile command from the File menu Sentences

displays the Delete Profile dialog

Highlight the profile you want to delete and click the Delete button Sentences displays a

confirmation dialog Click Yes to delete the profile

Deleting a profile does not affect the chapter files used in that profile in any way The

chapter files still exist on your hard disk and can still be used in other profiles

Working with chapters

Add chapter

Figure 5-3 The Add Chapter dialog

To add a new or existing chapter to the profile click the Add button to open the Add

Chapter dialog shown in Figure 5-3

To add an existing chapter to a profile highlight the chapter name in the Add Chapter

dialog You can use standard Windows selection techniques to select more than one

chapter from this list



145

Click OK to add the selected chapter or chapters to the list of available chapters for the

profile To return to the Edit Profile dialog without adding chapters click the Cancel

button

The first chapter added to a profile is set as the default changes chapter for schema data

and queries Apart from this the order in which chapters are listed in a profile has no

significance

To create a new chapter click the New button This opens the New Chapter dialog

shown in Figure 5-4

New chapter

Figure 5-4 The new chapter dialog

To create a new chapter type in the name in the New Chapter dialog and click OK This

adds the new chapter to the list shown in the Add Chapter dialog You must repeat this

action for each chapter you want to create To return to the Add Chapter dialog without

adding a new chapter click the Cancel button

You can select the physical location for your new chapter from the Location dropdown

list Locations for chapter files are only listed here if you have defined them in the

ChapterPathList parameter of the Sentencesproperties file (see ldquoChapterPathListrdquo)

If the paths defined for your chapters are very long you may not be able to view the

complete path in this dialog In this case you can resize the dialog window by clicking on

its right edge and dragging to the right

To create a chapter for use by the LazyView tool to view data from a relational database

click the LazyView Chapter checkbox on the New Chapter dialog For more

information see the LazyView Guide

Naming chapter files

When you create a new chapter the name you assign to it in the New Chapter dialog is

generally used as the basis of the chapterrsquos file name on disk Chapter files on disk have

the extension chap Sentences chapter names are case sensitive

There are no restrictions on the characters that can be used in Chapter names However if

you use a character that has a special meaning in your computerrsquos file system Sentences

automatically maps that character to an alternative character when it creates the disk file

for that chapter

The Edit Profile dialog displays a chapterrsquos logical name which is stored in the system

chapter Profileschap All profiles use this chapter to look up chapter names so when a

chapter is renamed in one profile it is subsequently visible in other profiles using its new

logical name

Rename

To rename a chapter click Rename in the Edit Profile dialog and enter the new name

Like other elements in Sentences all chapter files have a unique hidden internal identifier

which never changes Sentences identifies chapter files using these internal identifiers so



146

chapter files can be renamed and still be visible to Sentences When you rename a chapter

in the Edit profile dialog you only change the visible (logical) name of the chapter Both

the internal identifier and the disk file name of the chapter remain unchanged

Properties

Click Properties in the Edit Profile dialog to display the properties for a chapter For all

chapters Sentences displays the following information

bull Name the chapter file name

bull Chapter UID the unique internal identifier for the chapter

bull Block Size the chapter block size

bull Read-only whether or not the physical file is editable

bull Chapter Type either a LazyView or a Standard chapter

bull Chapter size the physical size of the chapter file on the server

All these fields are read only

When LazyView is installed and licensed there is an additional tabbed page which is

used to set the connection properties for the chapter For more information about the

LazyView tool which is used for viewing data from relational database tables see the

LazyView Userrsquos Guide

Checking chapters used for changes

If you position your mouse pointer over the profile schema tab in the Explorer Sentences

displays the profile name and the names of the chapters used for schema data and query

changes This is an alternative way of checking which chapters are used for changes

Deleting a chapter

If you need to delete a chapter you must first make sure that it is not used in any profile

We recommend keeping a backup copy of any chapter before you delete it You can then

delete the chapter from your disk If you delete the chapter while

Sentences is still running the chapter name is still visible in the Add Chapters dialog

until you restart Sentences

Password-protected chapter files

You can define a password to protect a chapter file Once you have assigned a password

to a chapter file it can only be accessed when the password is entered

Sentences provides a command line procedure only for setting changing and deleting

passwords This mechanism is supported by a dedicated Sentences servlet When users

wish to access a profile that includes password-protected chapter files they must first

access a specific HTML page and enter the necessary passwords before accessing the

profile

System administrators should note that the password entry HTML page is not in itself

secure and therefore server-based security measures are recommended

When you use a command line procedure that references password protected chapter files

Sentences displays a prompt requesting the password for each protected file

The Sentences API includes an interface and methods for use with password protected

chapter files

To set a password




147


the command




3 Sentences prompts you to type in a password for the chapter and then prompts you to

type in the password a second time for confirmation



To change a password



the command





4 Sentences prompts you to type in a new password for the chapter and then prompts

you to type in the new password a second time for confirmation



To delete a password



the command





4 When Sentences prompts you to type in a new password for the chapter press Enter

without typing in anything Repeat this action when Sentences prompts you to type in the

new password a second time for confirmation

5 Sentences displays a message asking you to confirm that this action removes the

password from the specified chapter Type in y (for yes) to confirm or n for no to retain

the password

To enter a password

1 Start the Sentences server

2 Using a Web browser access the following URL

lthostnamegtltportnumbergtSentencesPasswordEntry

where lthostnamegt and ltportnumbergt are the hostname and port number respectively for




148

3 Sentences displays an HTML password entry page listing the files that have passwords

Type in the correct password for each file and click the Submit passwords button

The password entry page displays the names of all the chapters that have passwords You

only need to enter passwords for the chapters in a profile you wish to access

4 Sentences responds with either Password accepted or Incorrect password for each

chapter file password you enter

5 After entering the correct passwords start the Sentences Explorer and access the

profiles in the normal way

Password-protected files and the Personal Edition

The Personal Edition cannot access any Sentences chapter file that currently has a

password assigned to it


Sentences requires you to log in with your username and password The functions you are

allowed to perform and the information you are allowed to view and update will depend

upon the privileges that you have been granted

A Sentences User Administrator will be able to change the privileges you have been

granted

Logging into Sentences

When you open a Sentences application you will be asked to enter your username and

password

The System Administrator will have set up a maximum number of times that you can

attempt to log in before you are locked out If you are locked out you will need to contact

a User Administrator to reset your password

The first time you log in (or the first time after your password has been reset) you may be

required to change your password

Changing your password

To change your password follow these steps

1 In the Sentences Explorer select Change Passwordhellip from the File menu

2 The Change Password dialog will appear You must enter your existing

password and then the new password twice to confirm

3 Select Change



149

Changing to a different user

To change to a different user follow these steps

1 In the Sentences Explorer select Logout from the File menu

2 Enter the username and password of the user you wish to log in as

3 Select Login

User Preferences

Previous versions of Sentences allowed you to change certain preferences by editing the

parameters of in a client HTML file or the Applicationproperties file for the Personal

Edition Sentences Version 40 introduces preferences specific to each user

To change your preferences follow these steps

1 In the Sentences Explorer select Preferenceshellip from the View menu

2 Amend the available preferences and select OK or Cancel when you are finished

to change or cancel your preferences

Available User Preferences

Not all preferences will be available to all users depending upon the Edition of Sentences

and whether Functionality such as LazyView are enabled

bull Veto Welcome (General)

You may use this preference to specify whether to show the welcome screen upon start-

up This preference is only applicable and available in the Personal Edition

bull Table view of data (General)



150

You may use this preference to specify whether to allow users to display results in the

data pane as a table rather than the default tree This feature is at the Beta stage for

example query results cannot be displayed as a table yet

bull Data request size (General)

You may use this preference to specify the number of results to initially show Rather

than load the entire results Sentences will show by default the first 50 results followed by

a ldquomorerdquo node

bull Executing Query Status refresh (General)

You may use this preference to specify the frequency with which the Query Editor

updates the progress of an executing query The default is every three seconds

bull Table view of data (Data Pane)

You may use this preference to specify whether or not to allow the user to change the

Data Pane between displaying a Tree of data to displaying a Table of data

bull Show pages in the data pane (Data Pane)

You may use this preference to specify whether or not to show Page Nodes in the data

pane

bull Show inactive instances in the data (Data Pane)

You may use this preference to specify whether or not to show Inactive instance in the

data pane

bull Show the properties tab in the Data Pane (Data Pane)

You may use this preference to specify whether or not to show the properties of the

selected schema in the data pane as a tab next to the data tab

bull Show the Data Tab first - and by default (Data Pane)

When the properties tab is visible (see above) you may use this preference to specify

whether or to show the properties tab or the data tab first ie to the left The left tab will

also be selected by defaultbull Automatic Foreign Key Matching (LazyView)

You may use this preference to specify whether or not to attempt to automatically match

foreign key columns to those available when creating user-defined Foreign keys in the

LazyView Mapping wizard This preference is only available if the LazyView

functionality is enabled

bull Check Relational Schema (LazyView)

You may use this preference to specify whether or not the system will check to see if the

Relational Schema has changed This will be done before viewing the current LazyView

Mapping Definition re-mapping or re-importing static data This preference is only

available if the LazyView functionality is enabled

bull Show Subsets (Schema Pane)

You may use this preference to specify whether to include Subset Metaschema


bull Show Supertypes (Schema Pane)

You may use this preference to specify whether to include Supertypes Metaschema


bull Show Equivalent Types (Schema Pane)

You may use this preference to specify whether to include Equivalent Types Metaschema


bull Show Custom Dataforms (Schema Pane)



151

You may use this preference to specify whether to include Custom Dataforms information

in the Schema Pane of the Sentences Explorer

bull Show Domains (Schema Pane)

You may use this preference to specify whether to include Business Rule Domain


bull Hide unused System Domains (Schema Pane)

You may use this preference to specify whether to hide those System Domains that do not

have Effectors in the Schema Pane of the Sentences Explorer

bull Show Business Rules (Schema Pane)

You may use this preference to specify whether to include Business Rules Metaschema


bull Include a Business Rules Schema Folder (Schema Pane)

You may use this preference to specify whether to include a Business Rules Schema


bull Include a State Domains Schema Folder (Schema Pane)

You may use this preference to specify whether to include a State Domains Schema


bull Include a System Schema Folder (Schema Pane)

You may use this preference to specify whether to include a Specialist Schema Folder in

the Schema Pane of the Sentences Explorer and the Query Editor This folder includes

schema for the End User Application definition Server Text Documents and Tag Clouds

bull Include a Transactions Schema Folder (Schema Pane)

You may use this preference to specify whether to include a Transactions Schema Folder

in the Schema Pane of the Sentences Explorer This preference is only available if the

Transaction Visibility functionality is enabled See the Transaction Visibility section for

details


You can deploy a Sentences database by moving all the chapters and profiles that make

up your database from your development environment to your deployment environment

For example you may choose to develop a Sentences database by running the Enterprise

Edition in local mode (with the server and client running on a single machine) and then

deploy your database on a live intranet or Web server

Important You must have a separate license for each server running Sentences

The two possible methods for deploying your database are exporting the database or

copying chapters

Exporting the database requires using a profile which includes all your chapters and then

reconstructing the profiles on the target system after import This method is explained

fully in the section ldquoExporting and importing databasesrdquo

Alternatively you can copy all your chapter files (chap files) from the

SentencesChapters directory on your development server to the SentencesChapters

directory on your deployment server You can then reconstruct all the profiles for your

database using the Edit Profile dialog There are some limitations and restrictions on

using this method This method is explained fully in the section ldquoCopying chapter filesrdquo



152

Schema and data visibility

You can create multiple profiles in a single database A userrsquos view of the database is

defined by the sum of all data and schema updates in the chapters of their profile and

therefore different users can have different views of a single database You can use the

profile mechanism and the delete mechanism to customise different Sentences views for

different users (see ldquoCreating database views using profiles and chaptersrdquo )

Exporting and importing databases

You can export your Sentences database using the Export command which creates a

database export file You can import the set of chapters from a database export file using

the Import command By default the Import command does not automatically recreate

the profile definitions for a database

Export and import operations are command line procedures and are normally carried out

by the administrator of the Sentences database The administrator must have at least

readwrite access to the computer running the Sentences Web server in order to carry out

export and import operations

A database export file contains all the schema and data information contained in a single

export profile including the chapter configuration We recommend using the file

extension lze to identify database export files

Export and import require exclusive access to the Sentences server and therefore you

must close down the Sentences server before you perform an import or an export

operation If you try to export or import a profile while the server is in useSentences

displays an error message Database in use

Benefits of exporting a database

In Sentences all schema and data changes including delete actions are treated as

additions to the chapter files This can have certain advantages as discussed in the section

ldquoCreating database views using profiles and chaptersrdquo

However it is possible that after a time the quantity of changes applied to a database may

make the chapter files very large and may possibly result in poorer performance

The export procedure consolidates data and schema updates and therefore exporting a

database and then importing it may enhance the performance of large databases

Database export and internal identifiers

Sentences uses unique internal identifiers for every schema and data element in the

database These identifiers are used in any links between chapters When you export and

import a database Sentences consolidates the details of schema and data updates creating

a new version of your database By default this new version of your database maintains

the existing internal identifiers and preserves cross-chapter links

Note In earlier versions of Sentences up to Version 21 Sentences automatically renumbered

all the internal identifiers when performing an import operation which meant that cross-

chapter links were not maintained In later versions from Sentences Version 22 you can force

Sentences to renumber by specifying the -renumber switch

To export a database you must specify a profile that includes all the schema and data

chapters that are relevant for an application You may use an existing profile if a suitable

one exists or create a new profile for this purpose



153

Default export behaviour

When you use the Export command Sentences checks cross-chapter references to make

sure all required chapters are included in the export profile and displays an error message

if a required chapter is not found By default if Sentences finds that any required chapters

are missing the export operation fails

You can change the default behaviour and run the export command even if some chapters

referenced by other chapters are not included by using the -force switch with the Export

command The result of using the -force switch may be that some of the data from the

original database is missing from the database export file


Note The following command line examples use Windows system conventions

You must have write access to all the chapter files used in the database you wish to

export


1 Choose a profile that includes all the schema and data files that are relevant to the

application database you wish to export The profile to be exported must meet these

conditions

bull the profile must contain all of the chapters holding your data or schema

bull the profile must not include the system chapters Profileschap or Metaschemachap

bull the profile should not include any other chapters supplied with Sentences such as the

Human resources chapters New chapterchap or any of the Application Suite

chapters except under special circumstances

You may use an existing profile if a suitable one exists or create a new profile for this

purpose You may find it helpful to keep a note of the names of the chapter files used in

the profile you export



Run the following command at the command prompt

cgt Export [-force] ltprofile namegt ltpathgtltexport file namegt

where ltprofile namegt is the name of a profile recognised in

the current loginchap file and ltpathgtltexport file namegt is

the full path and the name of the database export file you

want to create and [-force] is an option switch If the profile

name includes spaces some operating systems require the

name to be enclosed in quotation marks




Export command option switch

The Export command may include the following option switch

option switch Meaning

-force The -force switch exports a profile even if Sentences finds that some

chapters referred to by other chapters in the profile are missing



154

To import a set of chapters

Carry out the following steps to import a set of chapters


2 Make sure that no copies of any of the chapters being imported exist in any of the

chapter locations specified in the Serverproperties file If Sentences finds a chapter

with either the same name or the same internal identifier as a chapter being imported the

Import command fails

3 Open a command prompt and navigate to the Sentences server directory At the

command line prompt run the following command

cgt Import [-renumber] [-overwrite] ltpathgtltexport file namegt sect

[-location chapterNo=location ]

where ltpathgtltexport file namegt is the full path and file name for the database export

file you want to import and [-renumber] [-location] and [-overwrite] are option

switches as explained in the section ldquoImport command option switchesrdquo

During the import and export procedures Sentences displays a row of asterisks on the

command line screen Each asterisk represents 1000 lines of data that have been

processed

If the Import command fails for any reason any incomplete information is deleted If an

export or import program is interrupted by a user action the Sentences database may be

locked If you find you cannot run Sentences after a failed export or import operation

check the SentencesChapters directory to see if a file named databaselock is present

in any of your chapter file locations If you find this file delete it and then restart the

Sentences server (see ldquoShutting down and restarting the Sentences serverrdquo )

4 When the import operation ends restart the Sentences server and open a Sentences

client

Note If the profile you are referencing with this command includes password protected





155

Import command option switches

You may specify any of the following options by adding the appropriate switch to the

Import command If you do not specify any switch the default behaviour is as described

for the -preserve option

Option switch Meaning

-preserve Use the -preserve switch to import the set of chapters without

changing the existing internal identifiers for chapters and objects

and to maintain links between chapters

You may not use this switch with -overwrite or with

-renumber

-renumber Use the -renumber switch to import the set of chapters and change

all the internal identifiers for chapters and objects This means that

links to chapters outside the imported set of chapters are not

maintained

Import with the -renumber switch adds the definition of the exported

profile to the Profiles database so that it is automatically listed in the

Open Profiles dialog You may use this switch with -overwrite but

not with -preserve

-overwrite The -overwrite switch instructs the import program to overwrite any

existing profile with the same name as theprofile being imported

If you do not specify the -overwrite switch and a profile with the

same names as the imported profile already exists Sentences adds

a numeral to the end of the name of the imported profile

The -overwrite switch does not have any effect on existing

chapters and Sentences always adds a numeral to the names of any

imported chapters that have the same names as existing

chaptersYou may use this switch with -renumber but not with -

preserve

-location The -location switch allows you to specify the chapter directory for

the chapter files in the profile being imported You may specify

different locations for each chapter in the profile by giving a different

location for each chapter number All the locations must already be

designated in the ChapterPathList property of the

ServerProperties file You can check the chapter number of the

chapters in the profile being imported by opening the lze file in a

text editor

On Windows systems you should enclose the location specification in

quotation marks for example

ldquo1=Fchaptersrdquo

You may use this switch with any other switch

Visibility of imported profiles

When you import a set of chapters using the default setting (the -preserve option) the

exported profile may not be visible in the Open Profile dialog when you restart

Sentences This is because Sentences does not add the profile to the profiles database in

Profileschap when you use the -preserve option

If the imported profile is a new version of an existing profile the previous profile

definition is still available in the Open Profile dialog and can still be used This occurs

when you have exported a database to re-import it to the same system or to move an

application from a development system to a deployment system where it had previously

been deployed



156

If the imported profile is not a new version of an existing profile you must create the

profile definition You may do this using the Edit Profile dialog and selecting the

chapters belonging to the imported profile

If the imported profile is complex for example if you created a single profile to export all

the profiles and chapters of a large Sentences application it may be easier to use an XML

Import procedure to create the profile or profiles you need This procedure is described in

the section ldquoTransferring the profiles databaserdquo 7

Visibility of imported profiles using the -renumber option

If you import a set of chapters using the -renumber option switch Sentences adds the

exported profile to the profiles database in Profileschap and the profile is visible in the

Open Profile dialog when you restart Sentences

If a profile being imported with the -renumber switch or a chapter in the profile has the

same name as an existing profile or chapter Sentences appends a numeral to the name of

the imported profile or chapter for example My Data Chapter 1

Sentences recognises that the old and new profiles and chapters are different as they have

different internal identifiers due to the use of the -renumber switch

Limitation on parameters with Import command on Windows

If you are running the Sentences server on Windows and the command you use to import

a profile needs to include a more than eight parameters for example if you wish to

specify a large number of chapter locations you cannot use the supplied Importbat file

This is because of a limitation on the number of parameters that can be included in

Windows batch files

In this case you must enter the Java command with all the necessary parameters at a

command line There is no restriction in the number of parameters when using Linux

Unix

Importing a database export file from a previous version

Database export files from Sentences Version 22 and Sentences Version 30 may be

imported into Sentences Version 40 However you must ensure that you are using the

current releases of these versions before creating your export files (build 2232 or later or

build 3043 or later respectively) Please refer to the Sentences Installation Guide for

further details

If you need to import a database from any other version of Sentences please contact

supportsentencescom

Transferring the profiles database

When you deploy a Sentences application for the first time on a system other than the one

it was developed on you may wish to transfer the profiles database particularly if you

need to replicate the profile and chapter structure of a complex Sentences application The

procedures in this section explain how to do this

You do not need to use these procedures to update an application that already exists on

the deployment system

These procedures involve using Sentencesrsquo built-in XML Export and XML Import

commands to export the Sentences profiles database from one system and import it on

another system

To export the profiles database follow these steps

1 On the source (development) system make sure that the system profile Profiles is

visible in the Open Profile dialog If this profile is not available you must set the

optional parameter ProfilesProfileVisible in the jnlp or javascript definition to yes



157

(see ldquoAdditional optional parametersrdquo ) Note that if you make any changes to the jnlp or

javascript definition you may have to restart the Sentences server before the changes

become effective

2 Create a database export file as described in ldquoTo export a databaserdquo

3 In the Sentences Explorer select the Profiles profile

4 Open the All queries folder and highlight the query Export profiles

5 Select Results then Export XML Results from the Query menu

6 Select External for the DTD Reference option

7 Save the output to a file named for example profilesxml

As an alternative to these last three steps you can create an XML export file using the

following command line after stopping the Sentences server

ExportXML -doctype external -file ltfilenamegt Profiles ldquoExport profilesrdquo

You now have two files on the source (development) system the database exportfile and

the XML file of profile definitions

To import the profiles database follow these steps

1 Copy the two files (the database export file and the XML file of profile definitions)

from the source (development) system to the target (deployment) system or make them

available across a network

2 Make sure that none of the chapters in database export file exist on the target

(deployment) system in any directory that is on the chapter path list

3 Stop the Sentences server on the target system and import the database export file using

the default setting for the Import command as described in ldquoTo import a set of chaptersrdquo

You may optionally use the ndashlocation switch to place these chapters in different

directories

4 Start the Sentences server and use the Edit Profile dialog to create a new profile

named for example Profiles This must be the same name as the profile you used to

create the database export file This profile must contain only the system chapter

Profileschap

5 Use the Edit Profile dialog to create a second new profile This may have any name

you wish This profile must include all the chapters imported from the database export

file

This makes sure that details of all the chapters are recorded properly in the profiles

database After you have created and saved this new profile once it can be deleted

6 Stop the Sentences server

7 Copy the exported Profilesxml file from the source system to the target system


9 Run the following command

ImportXML -file Profilesxml

10Re-start the Sentences server

The set of profiles exported from the source system is now visible in the Open Profile

dialog

Export command troubleshooting

The Export command checks that all referenced chapters are included in an exported

database unless you use the -force switch with the command Sentences always checks

the internal identifiers of the chapters in a profile rather than the chapter names and an



158

export command may fail even though a chapter with the correct name is in the profile

Sentences display an error message similar to the following

1734 Chapter ldquoltchapter_name_Agtrdquocontains a reference to chapter

ldquoltchapter_name_Bgtrdquo which is not in profile ldquoltprofile_namegtrdquo

If this error occurs it is likely that the original chapter referenced in the profile has been

replaced by a different chapter with the same name You can check the list of other

chapters referenced by a chapter and their internal identifiers by using the

InspectChapter command with the header option (see ldquoChapter file analysisrdquo)

Copying chapter files

You can copy chapter files (chap files) from the ltSentences_chaptersgt directory on

your development server to the ltSentences_chaptersgt directory on your deployment

server provided that both installations are using the same version of Sentences You can

then reconstruct all the profiles for your database using the Edit Profile dialog You do

not need to reconstruct the profiles if you copy the Profileschap file as well as your

application chapter files but the effect of copying the Profileschap file is to delete any

existing profile definitions on the deployment server

You must shut down the Sentences server on both the source and target Sentences

installations before copying any chapter files After you restart the Sentences server on

the target installation all the copied chapters are visible in the Add Chapters list of the

Edit Profile dialog

If you copy the Profileschap file the copied profiles are also visible in the Open

Profile dialog If you do not copy the Profileschap file you can reconstruct your

profiles using the Edit Profile dialog

Restrictions on copying chapter files

If the Sentences server detects two or more chapter files that are duplicates Sentences

does not start and instead displays an error message (see ldquoErrors reported at the Sentences

clientrdquo )

The Sentences server does not identify chapter files as duplicates by their file system

names but by their internal identifiers When you copy a Sentences chapter file the copy

has the same internal identifier as the original This means that you must take great care

when copying chapter files never to allow two copies of the same file to be accessed by

the same server at the same time

Chapter format

From time to time as improvements are made to Sentences there are changes to the

internal format of the chapter files used by Sentences You can check the chapter format

used by your version of Sentences by selecting the About command in the Help menu

Click the Support Information button for a display of additional information including

details of the current chapter format

You can copy chapter files from one version of Sentences to another as long as the

chapter format is the same in both versions If the chapter format has changed you cannot

use copied chapter files You must export a profile from the earlier version of Sentences

and import the profile into the later version For more information see ldquoExporting and

importing databasesrdquo

Changing chapter file block size (single chapter export and

import)

If you wish to change the block size of a specific chapter file you can use the

ExportChapter and ImportChapter commands Both of these commands are run from a

command line For further information about block size see ldquoBlockSizerdquo



159

Both of these commands are run on a single file The commands do not use the

ChapterPathList setting from the Serverproperties file or check for the existence of

the databaselock file You must therefore use the fully-qualified path and file name

for example


It is strongly recommended that you shut down the Sentences server before running these

commands

ExportChapter command

To export a single chapter file open a command prompt navigate to your


ExportChapter ltchapter filegt ltexport filegt

where

ltchapter filegt is the file name of a Sentences chapter file to be exported and ltexport

filegt is the file name of the export file to be created

After you export a single chapter file in order to change the filersquos block size you must

remove the original file from any directory that is listed in the chapter file list

ImportChapter command

To import a single chapter file open a command prompt navigate to your


ImportChapter [-blocksize ltblock sizegt] ltexport filegt ltchapter filegt

where

ltblock sizegt is an optional number representing the block size in KB to be used when

creating the new chapter file

ltexport filegt is the file name of an export file created by the ExportChapter

command and ltchapter filegt is the file name of a Sentences chapter file to be created

The ImportChapter command creates a Sentences chapter file that has the same internal

identifieras the original chapter file so that references to it from other files can be

retained If you wish to use the same file name as that of the chapter file that you

originally exported you must make sure that the original chapter file is removed from the

directories in the chapter path list before running the ImportChapter command


You can use the Sentences Explorer to create your schema and to browse schema and

data You can launch the Dataform to type in data and the Query Editor to create and run

a query

Delayed display of inverse associations

In order to speed up the display of data in the Sentences Explorer Sentences postpones

the download and display of inverse association data When you expand an entity instance

node that is the target of one or more association types Sentences displays a folder for

each association type Sentences does not retrieve the instances contained in these folders

until you expand the folder itself

Display order of instances

When you select an entity type or association type in the schema pane the corresponding

entity or associations are displayed in the data pane For all entity types that are not

subsets the display order of instances in the data pane is determined by the sort algorithm

of their typersquos datatype If not all the visible instance data has the same datatype

instances of the same datatype are grouped together and then ordered by the sort

algorithm of their typersquos datatype



160

For all association types that are not subsets the display order of instances in the data

pane is determined first by the sort order of their sources and then by the sort order or if

it exists by the defined sequence of their targets Inverse associations are sorted by target

first

For all entity and association types that are subsets the display order of instances in the

data pane is determined by settings of any sort nodes in the subset query If no sort nodes

exist in the subset query the display order is determined by the sort algorithm of the typersquos

datatype

All of the display rules given above apply to the top level display in the data pane When

you expand a node in the data pane the data displayed is ordered automatically by

Sentences and this ordering cannot be changed

Refreshing the display

To refresh the display of the Sentences schema click the Refresh button on the Sentences

Explorer toolbar or select the Refresh command from the File menu

Refreshing the display also resets the clientrsquos definition of the current profile To refresh

the display of data in the Sentences Explorer data pane click the Reload Data button on

the toolbar or select Reload data from the File menu

Determining if child associations are present







Metaschema)

To change whether a Profile attempts to determine if child associations are present follow

these steps

1 In the Sentences Explorer select Edit Profile hellip from the File menu



To change whether a particular type attempts to determine if child associations are present

follow these steps

1 In the Sentences Explorer select the type for which you wish to change the

option

2 Select Propertieshellip from the Edit menu

3 Select the Retrieval Methods tab



Hiding the data pane

Sentences Version 40 introduces the ability to temporarily switch of the display of data

When you select a type in the left-hand Schema pane the right-hand Data pane displays

instances of that type If you are working on the schema design and not concerned with

the data at that moment it is useful to be able to hide the data pane

To toggle whether the data pane is visible or not select Data Pane from the View menu

Alternatively you may use the shortcut key combination of Alt+D



161

Sandbox Modes

Sentences 40 has added the ability to put the Sentences Client into a Data or a Full

Sandbox Mode Sandbox Modes are intended to be used to experiment with changes to

the database in a temporary environment where you can at any time revert back to the

state of the database before you switched to Sandbox Mode

You could add a new chapter to your profile and direct all changes to that chapter to

experiment and once finished you could remove the chapter again Sandbox Modes work

in the same way but the creation and removal of a temporary chapter is handled for you

You can quickly switch Sandbox mode on or off to compare the schema and data changes

you have made

Whilst in a Sandbox Mode any Simple Email Action Requests will not send emails

Instead a dialog will show the number of emails that would have been sent

bull Data Sandbox Mode

The main reason for using a sandbox will be when experimenting and refining an Update

Query or an Effector Query In this situation you may wish to repeatedly execute your

query and inspect the results after making small changes to the query In this case you can

use Data Sandbox Mode so that the changes you make to the query are permanent but the

changes to data can be discarded after you have finished refining the query

bull Full Sandbox Mode

A Full Sandbox Mode is also provided so that any changes to data or schema can be made

for experimentation and then all discarded afterwards

Access to Sandbox Mode

A User must be granted a specific privilege to be able to use Sandbox Mode There is a

Sandbox User Role or the privilege can be granted directly to a particular User See the

sections on User Privileges and Roles for details

Changing Sandbox Mode

Sandbox Mode must be enabled for each User as described above When enabled the

status bar of the Sentences Explorer and Request Query Editor will display the current

Sandbox Mode In addition the Options Dialog will include Sandbox Mode options

To change the sandbox mode in the Options Dialog follow these steps


Menu

2 The Options Dialog will open and if Sandbox Modes are enabled for the user the

dialog will include the three sandbox modes (Off Data and Full) The current

Mode will be selected

3 Select the mode you would like to change to and select OK

To change the sandbox mode from the Status Bar follow these steps

1 In the Sentences Explorer or Query Editor open the context menu for the

Sandbox Indicator The current mode will be disabled

2 Select the mode you wish to change to



162

Note that if there are open Query Editors that have unsaved changes you will be

prompted to confirm changing Sandbox Mode This is because the Schema will have to

be reloaded and any unsaved query changes will be discarded

Transaction Visibility

Sentences 40 now includes the ability to set a Visibility Timestamp to a point in the past

that is used to show the Profile at that time This function has no impact on performance

The current Transaction Visibility is displayed in the Status Bar of the Sentences Explorer

and Query Editors

Sentences 40 also includes the ability to browse the existing Transactions to identify a

point in time that you may wish to view See the Browsing Transactions section for

details

Access to Transaction Visibility

A User must be granted a specific privilege to be able to use Transaction Visibility There

is a Transaction Visibility User Role or the privilege can be granted directly to a

particular User See the sections on User Privileges and Roles for details

Changing Transaction Visibility

Transaction Visibility must be enabled for each User as described above When enabled

the status bar of the Sentences Explorer and Request Query Editor will display the current

Transaction Visibility In addition the Options Dialog will include Transaction Visibility

options

To change the Transaction Visibility in the Options Dialog follow these steps


Menu

2 The Options Dialog will open and if Transaction Visibility is enabled for the user

the dialog will include the current selection

3 Select either the current date and time or enter a new date and time and select

OK



163

The Options Dialog can also be opened from the Status bar context menu

Browsing transactions


the Transactions in your Schema You can also use the position and filter tools to narrow

your search

The information includes transactions that were aborted ndash these are transactions for which

a commit time is not set Most Transactions can have a description associated with them

but some perform many operations at once such as changing the properties of a Type and

can only describe themselves with the Type that was being modified ndash not all the changes

made

This is a useful tool if you are trying to find a significant event and set the Transaction

Visibility to view before and after it

Also available on the Options Dialog is a button that opens a dialog to show the

Transaction History This includes a summary of the first and last transaction timestamps

together with the number of transactions started and committed

Database components


164

The Transaction Schema Folder is displayed according to your User Preferences See the

section on User Preferences for details

Database components

The Sentences database includes both schema and data information The Sentences

database schema is built up of entity types and association types referred to collectively

as types The data in a Sentences database is built up of entities and associations which

are referred to collectively as instances Types and instances are introduced and explained

in Chapter 2 ldquoIntroducing the associative modelrdquo

You can work with types and instances in the Sentences Explorer and the Dataform and

also in the Query Editor These three mechanisms for viewing and working with

information are introduced in Chapter 4 ldquoThe Sentences Quick Tourrdquo

The next part of this chapter describes in more detail how you can work with types and

instances in the Sentences Explorer and the Dataform Working with the Query Editor is

described in Chapter 7 ldquoSentences queriesrdquo

Entity types and entities

The least complex data items in a Sentences database are entities which areinstances of

entity types Entity types are created and managed in the Sentences Explorer and entity

instances are created in the Dataform Entity types and association types are displayed in

the schema pane and entities and associations are displayed in the data pane For more

information see ldquoEntities and associationsrdquo

Creating entity types

To create an entity type you can either

bull click the Create Entity Type button on the toolbar or

bull right-click the All types folder and select the Create Entity Type command from the

shortcut menu or

bull select the Create Entity Type command on the Schema menu

You can also create entity types from the Create Association type dialog

Database components


165

Figure 5-5 The Create Entity type dialog

Each of these actions opens the Create Entity Type dialog Type in a name for the entity

type and click create The new entity type is added to the All types folderYou can create

another entity type or click Close to dismiss the dialog box

Entity types always appear under the All types folder in the schema pane Entity types

may also appear in the Core types folder (see ldquoThe Core types folderrdquo )

Entity type names can contain any standard alphanumeric characters including blanks

They should not contain any special characters as this may cause errors when evaluating

expressions in queries Make sure that the first character after a blank space is alphabetic

not numeric Entity type names are not case-sensitive

Sentences uses unique hidden identifiers for entity types (and for many other elements)

This means that you can rename an entity type or create an entity type with a duplicate

name without compromising the data in your database Sentences always prompts you to

confirm that you want to create a duplicate entity type when an entity type with the name

you are using already exists

You can optionally specify the Datatype to use at this time or later If you select a

Datatype other than the default of ltNonegt then the dialog will show you any datatype-

specific options to choose

If you enter an Entity Type name that contains one of the standard Datatypes (for example

ldquoDate Createdrdquo or ldquoPercentagerdquo) then the datatype will be automatically selected for you

Creating entities

Entity instances can only be created through the Dataform (see ldquoCreating an entity

instance in the Dataformrdquo )

Size of entity and value instances

Sentences has no specific limit on the size of items that can be stored as entity or value

instances although some datatypes do impose limitations (see for example the

ldquoNumberrdquodatatype )

You should be aware of the memory usage capabilities of your own system when

deciding to store large data items in a Sentences database It may be more practical to

store items such as large images outside the database and to create references to them

using the Hyperlink datatype (see ldquoString datatypesrdquo)

Database components


166

Value types and datatypes

Value types in Sentences represent things in the real world that you do not need to record

additional information about This includes for example dates times and numbers Value

types are created by assigning datatypes (see ldquoDatatype properties pagerdquo )

The distinction between value and non-value entity types is very important and is

discussed in the section ldquoEntities and valuesrdquo You should understand this distinction

fully before you make extensive use of datatypes in your database

In certain cases you may wish to record additional information about entities that are

defined as dates times or numbers Some data may be recorded in a numerical form

because you wish it to have a numerical presentation or to be sorted in numerical order

even though you do not need to perform any calculations on the data This happens when

you use a numerical format as the label of an entity for example as an order number or an

employee number

Value types and values are distinguished in the Sentences Explorer by disc-shaped icons

Because value types cannot be the source of an association you must not define any entity

type that you want to use as the source of an association as a value type In most cases the

majority of entity types can and should use the undefined datatype ltNonegt

The ImageData datatype

A new datatype has been added to Sentences Version 40 The existing Image datatype

allows you to specify images stored on the Sentences Server by name eg LazyImagesCarolHoffmanjpg

The new Datatype ImageData stores image data as bytes You can view images in the

dataform You can paste an image into an ImageData Dataform field from the system

clipboard and import them from relational databases using a LazyView Chapter

Default formats and presentations

When creating Entity Types and Association Types Sentences Version 40 introduces

several new default presentations for specific datatypes

Datatypes can now specify a default field width and a default format pattern The built-in

datatypes have the following defaults

Datatype Default Field Width

Date

Time

12

String

Number

Currency

Mixed Currency

Percentage

13

Hyperlink

Email

Image

ImageData

No default variable length

Timestamp 18

ltNonegt 30

Currency C000C-000

When an Association Type is created if its source is an Association Type then Sentences

sets the source presentation automatically to Table for Associations if it is multiple and

Nested panel if singular If a specific dataform width was set then this value is used for

the table column width and the original width is set to variable so that it takes up all the

available space or the sum of the column widths if this is less

Database components


167


Sentences Version 40 introduces two differences in the way one or more type or instance

is deleted For dynamic LazyView chapters deletion of read-only data is not relevant and

so Sentences does not attempt to determine the impact of deleting types or instances

Otherwise the process of determining the impact is broken down into smaller

components and can be cancelled or confirmed before the results are known if it is taking

a long time to determine

This is similar to how the request to execute a query can be cancelled before the results

have been determined

Subsets of subsets


previously not allowed

This is required to represent some Relational Database Schema and allow subsets to have

their own State Domains

Defining value types with datatypes

Some display formatting characteristics in Sentences are associated with datatypes that

may be assigned to a type When new entity types are created they do not have a datatype

assigned to them and their datatype property is set as ltNonegt

Datatypes are assigned using the Datatypes tab on the Properties dialog (see ldquoDatatype

properties pagerdquo ) For example in order to display a number with decimal places you

must assign the Number datatype Assigning a datatype may also determine certain

behaviour characteristics for example whether or not you can perform arithmetic

calculations with the instances of a type

When you assign one of the Sentences-supplied datatypes to an entity type you can decide

whether the type should be a value type or not using the Instances are values property

If you choose to make the type a value type instances of the type have both the

formatting and the behaviour characteristics associated with value types which are

described in more detail in the following section If you choose not to make the type a

value type instances of the type have only the formatting characteristics of the datatype

and not its behaviour characteristics

When you assign a datatype to a type you should check or clear the Instances are values

checkbox according to whether or not you wish to make the type a value type (see

ldquoInstances are valuesrdquo )

If you create an entity type with the same name as one of Sentencesrsquo own datatypes for

example Date or Time Sentences automatically assigns that datatype to the type and

converts it to a value type (see ldquoDatatype properties pagerdquo )

This does not apply to the Currency datatype You can clear the Instances are values

checkbox if you do not wish the type to be a value type

Note It is possible to create a custom datatype that is not a value datatype (see ldquoCustom

datatypes APIrdquo )

Impact of changing a datatype

Changing the datatype of an entity type or changing the setting for the Instances are

values property (see ldquoInstances are valuesrdquo ) has a serious impact on the visibility of your

data Any change you make to the datatype or to the value status of instances of any

entity type is not applied to existing instances which may no longer be visible after you

make a change

Database components


168

bull If you change from any datatype to ltNonegt existing instances remain visible

bull If you change between Number and Percentage existing instances remain

visible

bull If you make any other change between datatypes existing instances are no longer visible

bull If you change the state of the Instances are values checkbox existing instances are no

longer visible

bull Instances with different datatypes are not sorted together hence a list of such instances

may not be sorted as expected

bull Calculations in queries for example for custom dataforms may rely on the type and

instance datatypes matching and be broken by instances with different datatypes

If you do need to change a datatype where a considerable amount of data exists you may

wish to recreate the effected data and all data depending on it One method of doing this

would be to export the effected data to a CSV file and then delete the data from your

database and set the correct datatype before importing the CSV file

However this method is not always reliable and should be used with great caution

Visibility of value instances

When an entity type has ltNonegt as its datatype all the instances of that type are visible

in the data pane when the entity type is selected in the schema pane When you have

created a value type by assigning a datatype only instances with the same datatype are

visible This means that if you change the datatype of a type after you create entity

instances those instances may no longer be visible depending on the new datatype

A more strict visibility constratint can be placed upon Value Instance visibility where in

addition instances of value types are only displayed in the data pane when they are used

as targets of associations in the database As this is an expensive constraint to make it is

turned off by default To turn this additional visibility constraint on change the ldquoCheck

Value Visibilityrdquo flag in the Troubleshooting tab of Server properties (see ldquoServer

propertiesrdquo for details)

Behaviour of value types and values

In general value types and value instances behave in the same way as entity types and

entity instances with the following important exceptions

bull Two instances of a value type with the same name cannot exist they are the same

instance For non-value types it is possible to have duplicate instances that istwo distinct

instances with the same name

bull Value types and value instances can only be used as the targets of association types and

associations and they can never be the source of association types or associations

bull Value instances are only visible when they are used as the targets of associations

bull Non-value instances are associated with a particular Sentences chapter but value

instances are not A value instance exists wherever there are associations that use it as

their target

bull Although the Rename command is not available on the shortcut menu for value

instances you can replace one value with another in the Dataform

bull Value types and instances are displayed in the Sentences Explorer with a discshaped

icon

Database components


169

Creating value instances

You can only create a value instance as the target of an association in a dataform You

cannot open a dataform on a value type to create value instances

Association types and associations

Association types are more complex than entity types as they require three components

source verb and target The sources and targets of association types are typically entity

or association types but the source of an association can be an entity or association

instance For more information see ldquoEntities and associationsrdquo

Creating association types

To create an association type you can either

bull click the Create Association Type button on the toolbar or

bull right-click the All types folder and select the Create Association Type command from

the shortcut menu or

bull right-click an existing entity or association type and select the Create Association Type

command from the shortcut menu or

bull right-click an existing entity or association instance and select the Create Association

Type command from the shortcut menu or

bull select the Create Association Type command on the Schema menu Each of these

actions opens the Create Association Type dialog

Figure 5-6 Create Association Type dialog

When you create an association type you must define its source verb and target and its

cardinality properties (see ldquoCardinalityrdquo ) After you have created the association type you

can alter some of these properties and define some additional properties in the Properties

dialog (see ldquoPropertiesrdquo )

Schema and data change visibility

Some changes to schema and data such as the addition of instances to a new association

type may not be automatically reflected in the data pane of the Explorer if entities of the

Database components


170

source type are being displayed As soon as you reselect the entity type or refresh the

display all changes are displayed correctly in the data pane

Source verb and target

You must define a source a verb and a target for any association type you want to create

The source of the association type must be an entity or association type or an entity or

association instance The target of the association type must be an entity or association

type The verb defines the nature of the association between the source and the target

Source

If you select an existing type or instance before you open the Create Association Type

dialog Sentences displays the selected type or instance as the source for the new

association type You can use the displayed source or select another source from the

Valid source types folder or type in the name of a new entity type

If you type in a new entity type name Sentences prompts you to confirm that you want to

create a new entity type You cannot type in a new association type as the source

The Valid source types folder displays all the types that may be used as the source of an

association type This means that value types are not displayed in this folder

Selecting an entity instance or an association instance as the source of an association type

creates an instance-specific association type which is discussed in the section ldquoInstance-

specific association typesrdquo

Verb

The verb defines the association type and describes the nature of the association between

the source and the target A precisely named verb can be very useful in schema design

You may use the same word to name the verb and the target of an association type It is

helpful to use an upper case (capitalised) name for the target and a lower case name for

the verb for example Actor award Award When you create association instances the

name of the association type verb is preserved for example David Garrick award Best

Actor

Verb names should be singular Multiple Association Types allow you to also enter a

plural form The singular form is used when referring to one instance The verb name (or

plural form) is capitalised when it is used as a field label in the Dataform

Target

You can select a target for the association type from the All types folder or you can type

in the name of a new entity type Alternatively you may select an existing metatype from

the Metatypes folder which is a subfolder of the All types folder You cannot type in the

name of a new metatype (see ldquoMetatypesrdquo )

You must always select not type in the name of an existing type If you type in a new

entity type name Sentences prompts you to confirm that you want to create a new entity

type You cannot type in a new association type as the target

Inverse verb

You need to specify an inverse verb for the association type The inverse verb expresses

the same link as the verb but as seen from the target to the source For example if the

verb of an association type is has colour then the inverse verb might be colour of

Sentences suggests a default inverse verb based on the verb you entered usually by

adding the word ldquoofrdquo You can always type in an inverse verb of your own choice instead

of the one suggested by Sentences

Database components


171

Page

Association Types can be placed on Pages These are purely used to arrange the fields in a

Dataform (see ldquoSchema Pagesrdquo)

Cardinality

The cardinality of an association type determines whether you can have zero one or

more than one associations of a given association type for one source instance You

define association type cardinality by checking the OptionalMandatory and

MultipleSingular radio buttons

The following table shows the possible combinations of these settings

Optional Manditory Multiple Singular Number of Associations

Manditory Singular One only ndash Zero not allowed

Optional Singular Zero or One

Manditory Multiple One only ndash Zero not allowed

Optional Multiple Zero or more

Cardinality rules and data display

Sentences monitors the data you type in to ensure that you conform to the cardinality

rules that you have defined for your association types If you use the Dataform to type in

data and do not complete the field for a mandatory association Sentences displays an error

message Similarly if you try and create more than one value for a singular association

Sentences displays an error message

In some situations Sentences is unable to enforce cardinality rules In these cases the data

displayed in the Sentences Explorer does not match the data displayed in the Dataform

For example if you define an association type as Multiple and create multiple

associations for a particular source and then change the definition of the association type

to Singular the database has more targets for the association than its current definition

allows

When you view this association in the Sentences Explorer all the targets in the database

are displayed because the Sentences Explorer uses an open tree structure to display data

(In this situation the Explorer does not use the associations folder normally used to group

multiple associations)

If you try and view this association using the Dataform Sentences displays an error

message

Error 1710 Singular AT (association type name) has multiple instances

This is because the Dataform has a rigid structure determined by the schema and the

schema rules If the schema rules allow only one value then only one value can be

displayed in the Dataform

Singular inverse

When you define a new association type you can also determine whether to limit the

association from the target to the source using the inverse verb (the inverse association) in

some way Use the Singular Inverse check box to ensure that the inverse association

must be singular That means that any entity or association instance may be the target for

only one association of this type The Singular Inverse property is not available for

Symmetric association types

Database components


172

Symmetric

An association type is symmetric if the relationship between source and target is always

the same in both directions The source and target must be of the same type and the target

may not be a value type For example the association type Person is married to

Person is symmetric However the association type Person is employed by Person

is not symmetric

The Symmetric check box is only available if the source and target of an association are

of the same type equivalent types related subsets or subtypes When the Symmetric

property is selected the inverse verb is not used and the inverse verb field is not editable

Display ordering

If you select the multiple option when you choose the cardinality of the association type

you can choose to display associations as sorted or as sequenced (see ldquoSorting and

sequencingrdquo )

Instance options


You can create an association type that does not have any instances of its own but that

may be a supertype for other related association subtypes by checking the Instances may

not be created checkbox The related association subtypes may themselves have

instances (see ldquoSubsets properties pagerdquo )

You can create some association instances and then select the Instances may not be

created checkbox on the Association type properties dialog This forces users to choose

from a limited range of instances







Schema Pages

Schema Pages can be used to arrange Association Types into Tabbed pages on a

Dataform Association Types are automatically placed on a different page if they are

sourced on a Subset or Subtype and the Dataform Tab is given that Subset or Subtype

name Schema Pages allow any arrangement of Pages and are used as the default pages

when a Custom Dataform Query is created

To create a Schema Page you can either enter a new Page Name in the Association Type

Properties General Tab or you can select the Create Pagehellip Menu Item when a type is

selected in the Schema Pane

To organise which pages all Association Types are displayed on and the order

1 Select the Type that you wish to organise Pages for in the Schema Pane and

select Organise Pageshellip from the Schema Menu

Database components


173

The Organise Pages Dialog allows you to

bull Create Delete Rename and Reorder Pages

Use the Add Delete Rename and Move buttons at the bottom of the dialog to

change the pages used for the selected Type and their order

bull Change Association Type Pages

Select one or more Association Type select a page and click the Change Page

button to move the selected Association Type(s) onto that page

bull Reorder Association Types

Using the Move Up and Move Down buttons the order of Association Types on

each Page can be altered

bull Hide Association Types

Select one or more Association Type and set or clear their ldquoHidden on dataformrdquo

property

Database components


174

Once pages exist in the Schema Pane you can also drag and drop individual Association

Types onto different pages You can also reorder pages by dragging one onto another

If there is an empty page after you have finished organising then it will not be saved

between sessions

Metatypes

Metatypes are the categories of data that appear in the schema pane You can create an

association type that uses a metatype as its target The available metatypes are Entity

type Association type Query and Custom Dataform The instances of a metatype are

the types that are defined in the current schema

Metatypes may only be used as the target of an association and not as the source An

association type that has a metatype as its target behaves in the same way as any other

association type and may be used in queries and custom Dataforms

Using metatypes

To use a metaschema type as the target of an association select a type from the

Metatypes folder The Metatypes folder is a subfolder of the All types folder in the

target area of the Create Association Type dialog You cannot type in the name of a new

metatype

Creating associations

Associations can only be created through the Dataform (see ldquoCreating an association in

the Dataformrdquo )


You can use the Delete button on the toolbar or the Delete command on the Edit toolbar

to delete any entity or association type or instance You can delete a value type but you

cannot delete a value instance

Figure 5-7 Impact of deleting dialog for a data item

Impact of deleting dialog

Sentences displays an Impact of deletinghellip dialog which displays the items that are

affected by the delete action and prompts you for confirmation The name of the dialog

shows the name of the item you want to delete

Database components


175

Figure 5-7 shows an example of an Impact of deletinghellip dialog for a data item and

Figure 5-8 shows an example of an Impact of deletinghellip dialog for a schema item which

includes a display of the relevant part of the schema tree

Figure 5-8 Impact of deletinghellip dialog for a schema item

Internally Sentences does not physically delete any element but instead makes the

particular element invisible The delete action is recorded in the relevant changes chapter

defined in the current profile This means that you could devise an arrangement of

chapters and profiles in such a way that certain information was available in one profile

and was not available in another profile

You cannot undo Delete actions You can recreate any item that you have deleted but as

every item in Sentences has a unique internal identifier the recreated items are not

identical to the items they replace even if they share the original deleted itemrsquos name and

attributes

Implicit deletion

Sentences automatically enforces referential integrity constraints when any item is

deleted If you delete an entity instance you also delete any association that uses that

entity as its source or target and these associations are listed in the Impact of deletinghellip

window If you delete an entity type you also delete all its instances along with any

association types that use it as a source or as a target along with all the associations that

are instances of those association types

When you delete an item any other items that are dependent on it are also deleted The

following list summarises the dependencies in Sentences that are affected by a delete

action

bull An association type is dependent on its source and target whether they are types or

instances

bull An entity or association instance is dependent on its type

bull An association instance is dependent on its source and target instances

bull Instances of a subset type are dependent on the existence of the superset type

bull A schema type is dependent on another type that you have defined as its

equivalent

There is no dependency in the following cases

bull A subset type is not considered dependent on the existence of the superset type even

though instances of it are This means that you can use a type originally defined as a

subset after its superset is deleted If you delete a superset type the subset type becomes a

Database components


176

normal type and you can create instances of it You cannot re-establish a subset-superset

link after you delete the superset

bull Subtypes and supertypes are not considered to be dependent on one another

Renaming types and instances

You can rename any entity type or instance or any association type that appears in the

Sentences Explorer You can rename a value type but you cannot rename a value

instance Renaming an association type changes the verb of the association not the source

or target

The unique internal identifier of the type or instance is not affected by renaming and the

new name appears automatically wherever the type or instance is used

To rename a type or instance highlight it in the Sentences Explorer and select the

Rename command from the Edit menu or the shortcut menu Sentences displays an

editing box around the existing name You can now type in the new name When you

move to another field or press Enter your changes are saved

The Rename command is not available for value instances in the Sentences Explorer If

you need to change a value instance you must use the Dataform

Inactive Instances

During the life of an application data often becomes inactive and no longer ldquocurrentrdquo but

is still needed for historical reference More importantly the application designer may

wish to prevent the user from continuing to reference these inactive instances Sentences

provides a way to identify instances as ldquoinactiverdquo and to hide them from the user to de-

clutter the user interface and prevent their accidental use

In addition if a user does select such an inactive instance in a Dataform then Sentences

can warn them of this

To specify that an Association Type is to be used as the sourcesrsquo ldquoinactiverdquo indicator it

has an attribute on the Association Type property page in the Instance options section

Database components


177

The presence of an association instance indicates that the source (in the example above a

instance of Employee) is no longer active If there are two Association Types ndash for

example (Person inactive Flag) and (Employee inactive Flag) then either or both will

make an Employee inactive Both will have to be clear for the Employee to be active

The Data Pane will not include inactive instances by default This only applies to the root

instances When you drill down all data will be shown If the user preference is changed

to show inactive instances then they are highlighted with a suffix Inactive and the font

is in italics

The Query Editor has a ldquoShow inactive instancesrdquo checkbox for convenience to include

inactive instances in the results This is off by default and it is only the root results that

are filtered



178

The Dataform pickers also default to not initially including inactive instances This can be

overridden by checking the box at the bottom

When applying a child dataform or saving a parent dataform Sentences informs the user

if they have included inactive instances Any pre-existing inactive instances are not

highlighted


When you select a type in the Explorer schema pane you send a data request from your

Sentences client to the Sentences server In response the Sentences server loads and

displays data from your database in the Explorer data pane Whenever you execute a

query or use the Positioner and Filter tools you are also making a data request

Sentences does not automatically load all the available data for a type from the server and

display it in the data pane each time you make a request This is to reduce unnecessary

network traffic between the Sentences server and client

Sentences provides a number of tools to help you locate data in the Explorer which are

described in this section

Also be aware that the visibility of instances can be affected by the Transaction Visibility

mechanism (See ldquoTransaction Visibilityrdquo for details)

Demand loading of data

The number of data items loaded at each data request can be configured using the optional

applet parameter RequestSize The default value for this parameter is 50 data items You

can change this value by adding the RequestSize parameter to the jnlp or javascript

definition (see ldquoAdditional optional parametersrdquo)

The More prompt

Whenever more data than that already displayed in the data pane is available in the

database Sentences displays a special prompt in the data pane (the

Morehellip prompt) to indicate that more data items exist in the database as shown in Figure

5-9

The Morehellip prompt appears in the Explorer data pane and in the Query Editor results

pane for the top level data request (the type selected in the Explorer schema pane or the

root node of the query) and for forward and inverse associations The Morehellip prompt



179

also appears in multiple association fields in the Dataform such as list boxes tables and

tree displays

When derived types or derivations are used in queries Sentences needs to calculate all

values before displaying the derived type or derivation result For this reason the Morehellip

prompt is not displayed for nodes used in calculating derived types or derivations The

Morehellip prompt is also not displayed for any node that includes the type referenced in the

derived type or derivation apart from those nodes directly between the derived type or

derivation and the root node of the query

Figure 5-9 An example of the Morehellip prompt

To load more data double-click on the Morehellip prompt displayed at the bottom of the

data pane or press the Page Down key on your keyboard

Each time you click the icon or press Page Down Sentences loads more data items

according to the number of items specified by the RequestSize parameter until all the

available data items are displayed at the client

The Positioner and Filter tools

The Sentences Explorer has two tools to help you locate data more quickly the

Positioner and the Filter These tools are located on the right hand side of the toolbar

They are also available on Picker dialogs in the Dataform

Figure 5-10 The Positioner and Filter tools

The Positioner and Filter tools each have a value entry field on the toolbar On the far

right there is the data reload button The Positioner and Filter both work only on the top

level of displayed data that is the data level that matches the type currently selected in the

schema pane



180

The Positioner tool

The Positioner tool locates the first data item that matches the value you entered in the

entry field Sentences clears the data display and then displays data items starting at the

first matching data item This is not the same as the ldquoFindrdquo feature found in some other

applications

To use the Positioner tool type in a value in the entry field and press Enter or click the

Reload Data button The value you choose must be a valid value for an instance of the

current type but it does not have to be a value that exists in the database For example if

the current type allows character strings for names you can type in the value P in the

Positioner field and press Enter or click the data reload button Sentences displays names

beginning with the first item that begins with that letter as shown in Figure 5-11 The

Positioner tool does not use wildcards

Figure 5-11 Sentences Explorer display with Positioner value P

If you type in a value that does not exist the Positioner displays data starting with the

first available item after the value you entered Figure 5-12 shows the result of entering

the value Ps in the Positioner field



181

Figure 5-12 Sentences Explorer display with Positioner value Ps

For associations Sentences applies the same rule to the original source entity type For

example if the current association type is ((Person customer of Store) visited on

Date) then the Position field needs a Person value since the list is ordered by Person

The Filter tool

The Filter tool locates all the data items that match the value you entered in the entry

field To use the Filter tool type in a value in the entry field and press Enter or click the

Reload Data button

Sentences clears the data display and then displays the filtered data items If there are

more items available than there is room in the data pane Sentences displays the Morehellip

prompt

Pattern matching with the Filter tool

The Filter tool is case insensitive but it does supports pattern matching with wildcards

Filter Tool Wildcard Meaning


matches from zero to any number of characters

| or

If you want to use any of the wildcard characters as part of your pattern you need

toldquoescaperdquo the character with a backslash as follows





| Represents a literal | character

Single Backslashes are ignored



182

The Filter tool searches from the start of the value stored This means that if you want to

filter using partial string that is not at the start of the stored value you should use the

asterisk wildcard before the filter term Similarly if you want to filter using partial string

that is not at the end of the stored value you should use the asterisk wildcard after the

filter term

For example and would return band hand sand and so on and and would also return

and grand and brand The filter argument profile|chapter would return any

string that contained the word profile or the word chapter By contrast the filter

argument profilechapter would only return a string that contained both the word

profile and the word chapter

Figure 5-13 shows the result of using the filter Ven

Figure 5-13 Sentences Explorer display with Filter value Ven

Using Filtering and Positioning tools together

You can use the Positioner and the Filter tools together If you type in values in both

entry fields Sentences displays entities or associations matching the Filter value starting

at the point specified by the Positioner value

Figure 5-14 shows the result of using the Positioner value M with the Filter value Ven

Compare this result to that shown in Figure 5-13 which showed the Filter being used on

its own



183

Figure 5-14 Sentences Explorer display with Positioner value M and Filter value Ven

Reloading data

To restore your view to all the available data clear any values from the Positioner entry

field and the Filter entry field and click the Data Reload button If there is more data

available than can be shown Sentences displays the Morehellip prompt

If you highlight the name of a query in the schema pane you can use the Data Reload

button to display the results of the query in the data pane


When you request data from the Sentences server Sentences returns a number of data

items up to the limit specified in the RequestSize parameter (see ldquoAdditional optional

parametersrdquo ) Occasionally this data retrieval action may take a long time for example

because the RequestSize parameter is set to an inappropriately high value

The Stop button


This button is only available while a data retrieval action is taking place and the message

Retrieving data is displayed in the data pane

This is shown in Figure 5-15



184

Figure 5-15 Using the Stop button



The Stop button is available in the Sentences Explorer the Diagram Editor and the

Query Editor You can only stop a data retrieval action by using the Stop button in the

same window that started it You cannot for example use the Stop button in the Explorer

to stop a data retrieval action started in the Query Editor

Sorting and sequencing

You can sort data and schema items in Sentences The Sentences default sort algorithm

which is alphanumeric and case insensitive applies to instances of types that do not have

a defined datatype (their datatype is displayed as ltNonegt) Defined datatypes each have

their own specialised sorting algorithm which are described in the datatypes section (see

ldquoDatatype properties pagerdquo )

The Sentences sequencing feature lets you define explicit data sequences in the Sentences

Explorer and Dataform You can use sequencing with a series of association types

sourced from a particular type and with a set of instances of a multiple association type If

you change the sequence of association types in the schema pane the corresponding data

items appear in the sequence you defined when the display is refreshed

Sequencing association types

The order in which associations appear in the Default Dataform is the same as the order in

which they appear in the schema pane A change in the order of association types in the

Sentences Explorer schema pane is always reflected in the Default Dataform

The default order of association types is the order in which they were created To change

this order you can cut and paste or drag and drop an association type to a new position in

the schema pane with either the same or with a different source If you change the source

of an association type any associations of that type which exist are no longer visible

Properties


185

When you use the shortcut menu command Create Association Type or use the Create

Association Type toolbar button new association types are added to the end of the set of

existing association types for their source You can create a new association type in a

specific position by using the shortcut menu command Insert Association Type Above

This command creates a new association type and positions it above an existing selected

association type from the same source

Sequencing multiple instances

You can apply an explicit sequence to the instances of a multiple association type When

you create an association type or set its properties you can select the Multiple option

which means that you can create many instances of the association for each source By

default Sentences displays multiple association instances as sorted by their targets

according to the sort algorithm of the target type

If you select the Sequenced option in the Association Type Properties dialog the

instances of the association type are always displayed in their defined sequence which by

default is the order in which they were created You can change this sequence in the

Sentences Explorer data pane using the cut and paste options This is similar to the way

you can change the sequence of association types as described earlier

The sorting algorithm applied to a set of target entities is determined by the datatype of

their entity type (see ldquoDatatype properties pagerdquo )

Properties

Several new property pages have been added to types in Sentences Version 40 and some

include additional items

Business Rules introduce two new property pages for State Domains and Business

Rules See the Business Rules section for details


Sentences interface See the Display Name Query section for details

On the Retrieval Methods properties page there is an additional option for whether to

determine if child associations are present or not This means that both Entity Types and

Association Types now include a Retrieval Methods properties page See the Determining

if child associations are present section for details

The Datatype properties page now includes the new ImageData datatype The Format

properties page will be affected by default field widths and format patterns See the

Database Components section for details


previously not allowed This means that the properties of a Subset have an additional

Subsets page for their subsets as well as the existing Presentation and Description pages

Subsets can have their own (and inherited) State Domains so the properties of a Subset

also include a State Domains page but not a Business Rules page

When an Associative Model is generated automatically by importing a Relational

Database Schema the description field of types is populated with the catalog schema


The Mapping property page used by the previous version of LazyView is no longer

required

You can define a number of properties for entity types and association types in the

Sentences database by using the entity type and association type Properties dialogs

These dialogs have a number of tabbed pages some of which are common to both entity

types and association types as shown in the following list

Properties


186

Property Page Appears for entity types Appears for

association types

General Yes No

Datatype Yes No

Format Yes Yes

Presentation Yes Yes

Display Name Query Yes Yes

Subsets Yes Yes

Supertypes Yes Yes

Equivalence Yes Yes

Triggers Yes Yes

Description Yes Yes

Custom Dataform Yes Yes

State Domains Yes Yes

Business Rules Yes Yes

Diagram Images Yes Yes

Default Sorting Yes Yes

Association Type No Yes

Target Parameters No Yes

Derived Target No Yes

Dataform No Yes

Retreval Methods No Yes

General properties page

Figure 5-16 The General properties page

The General properties page applies only to entity types Some of these properties are

available on the Association Type properties page

Properties


187

Display in Core types folder

If you have not chosen the Generate Core types automatically option in the Edit

Profile dialog you can select an entity type to be displayed in the Core types folder by

selecting the Display in Core types folder checkbox (see ldquoThe Core types folderrdquo )

Instance options

The following options apply to instances of this type When a type is defined as a Value

type all of these properties are disabled and cannot be changed


You can define an entity type that does not have any instances of its own but that may be

a supertype for other related association subtypes by checking the Instances may not be

created checkbox The related entity subtypes may themselves have entity instances (see

ldquoSupertypes properties pagerdquo )

You can create some entity instances and then select the Instances may not be created

checkbox This forces users to choose from a limited range of instances For example you

could define an entity type Boolean with instances True and False and then select the

Instances may not be created checkbox


automatically or by a trigger See Instance name creation options below




bull Instances may not be renamed

Note Instances may not be renamed does not apply to association types and does not

appear on the Properties dialog for association types

Check the Instances may not be renamed checkbox to prevent users from renaming any

of the instances that are created for this type

Note Instances may not be renamed is automatically selected if instance names are not

being created by the user The name is automatically generated using one of the methods below




Note The Instance Options check-boxes for association types are on the Association type

properties page The options Instances may not be renamed and Instances created by

trigger do not apply to association types

Instance name creation options

Note Instance name creation options do not apply to association types and do not appear

on the Properties dialog for association types

Note Instance name creation options do not apply to value entity types The name will

always be given by the user


automatically or by a trigger


by the system This may be used for example to automatically create invoice numbers or

order numbers in a business application

bull Instance name created by user

Properties


188

If you select this option for an entity type the user must enter a name for the Entity Type

bull Instance name created by trigger


by a trigger This may be used for maximum flexibility when generating identifiers but

requires some programming resources The other options require no programming

knowledge


typing into a Dataform field You must open a Create Dataform from the entity type An

entity type that uses the Instance name created by trigger option may be the source of

association types in the same way as any other entity type

For general information on triggers see the section ldquoTriggersrdquo There is a worked

example of an Order Entry application which uses a trigger to create instance names for

orders in the section ldquoDerivations examplerdquo This worked example uses a trigger named

RenameInstance which is included in the ExampleTriggersjar file in the directory

ExamplesJars

If you use XML Import to add data instances for entity types which use the Instance

name created by trigger option you must make provision for the trigger action in your

XML data structure (see ldquoXML Import and triggersrdquo )

bull Instance name created by generating a GUID


by a generated Globally Unique Identifier (GUID) The value of a GUID is represented as

a 32-character hexadecimal string such as

063a1d33-2189-49d3-969c-967d60e3dab5

The total number of unique keys is 2128 or 34times1038 This number is so large that the

probability of the same number being generated randomly twice is negligible



GUID is generated when you save the Dataform

bull Instance name created by incrementing ID


by a generated ID The value of the ID starts with the one that you enter here and this is

incremented each time an entity is created



ID is generated when you save the Dataform

The ldquoseedrdquo ID can be either a whole number or an alphanumeric identifier When

incrementing the ID Sentences will take the trailing numerical part of the ldquoseedrdquo and

increment this by one A decimal point or comma will be treated as a non-numerical

character

If there is no trailing numeric part then Sentences will start with a zero If the numeric

part has leading zeros then these zeros will be retained until the number is larger than the

number of digits and then the ID will increment as normal

Some examples

1 2 3 4 5 hellip

0098 0099 0100 0100 hellip

ID0098 ID0099 ID0100 ID0100 hellip

PER PER0 PER1 PER2 PER3 hellip

1234997 1234998 1234999 12341000 12341001 hellip

Properties


189

bull Instance name created by current timestamp


by using the current server timestamp



timestamp is generated when you save the Dataform

Datatype properties page

The Datatype properties page applies only to entity types

Figure 5-17 Selecting a datatype

Use the Datatype page of the Properties dialog to set the datatype for an entity type

Using datatypes allows for example input values to be checked for validity and

determine the range of formatting and presentation options that are available for instances

of a type and how instances are sorted

The use of datatypes also affects instance behaviour and visibility in that instances of

types that have datatypes assigned to them generally behave as values (see ldquoValue types

and datatypesrdquo ) You can prevent instances behaving as values by clearing the Instances

are values check box when you assign a datatype (see ldquoInstances are valuesrdquo ) This

allows you to make use of the formatting and presentation options associated with the

datatype without creating a value type

Value types and value instances are distinguished in the Sentences Explorer by

discshaped icons Because value types cannot be the source of association types you must

not define an entity type that you want to use as the source of an association type as a

value type For more information about values and value types and their relation to

datatypes see ldquoValue types and datatypesrdquo and ldquoImpact of changing a datatyperdquo

Instances are values

Check or clear the Instances are values checkbox to determine whether or not the type is

a value type and its instances are values This checkbox is selected by default for all

Sentences-supplied datatypes Clearing this checkbox means that instances have the

formatting and sorting characteristics associated with the datatype but the instances are

not values and the type is not a value type You may can also create your own custom

datatypes (see Chapter 10 ldquoCustomising Sentencesrdquo)

For more information about values value types and datatypes see ldquoValue types and

datatypesrdquo and ldquoImpact of changing a datatyperdquo

Properties


190

Assigning datatypes

To assign a datatype select a datatype from the drop down list on this page Depending

on the datatype selected other fields may be displayed on this page such as the

Maximum Decimal Places field for number datatypes The characteristics of each

datatype are described in the following sections

bull Undefined (displayed as ltNonegt)

If you do not assign a datatype the Datatype page displays ltNonegt as the datatype The

only presentation formats allowed are single-line or multi-line edit fields (using Tab and

Return characters)

Entity instances for types that do not have a defined datatype are limited to strings of

standard printable ASCII characters with a maximum string length of 64000 characters

Instances of types that do not have a defined datatype are sorted in a case-insensitive

alphanumeric order (that is 0hellip 9 Aa Bb hellipZz)

String datatypes

The string datatypes are Text Image Email and Hyperlink String datatypes are value

types but they do not support arithmetic operations

bull Text

In the Text datatype Tab and Return characters are allowed and therefore multiline

values can be created if the multiple line presentation method has also been selected

Multiple line values are only displayed as multiple lines in the Dataform In the Sentences

Explorer multiple line values are displayed all in one line and a semi-colon character is

used to mark the position of line breaks You can only use the multiple line presentation

method for singular associations and not for multiple associations

Instances of types that are defined with the Text datatype are sorted in a casesensitive


Using the Hidden style for the Text datatype results in the display of asterisks on the

dataform instead of the actual text entered

bull Image

Sentences supports the display of JPEG and GIF image file formats When you type in the

location of an image file in a target field defined with the Image datatype the Dataform

displays the image The Sentences Explorer displays the file name or URL

Sentences can display any image hosted on any web server that it can access if the image

file is referenced by a full URL such as httplazysv04databasesimagesJanejpg

You cannot specify an image location using a file path

You can reference images more easily if you specify a location for all your image files

using the ImageURLBase parameter in your jnlp or javascript definition (see ldquoAbout the

ImageURLBase parameterrdquo) You could then use the file name on its own or a partial

URL For example if the ImageURLBase parameter was set to

httplazysv04databasesyou could refer to an image file simply as

imagesJanejpg

Instances of types that are defined with the Image datatype are sorted in a casesensitive


bull Hyperlink

When you use the Hyperlink datatype the entered value is treated as a World Wide Web

Uniform Resource Locator (URL) When such a value is opened (by double clicking or

Properties


191

by selecting Follow Hyperlink from the shortcut menu) the Web page or file to which the

URL refers is displayed

The Hyperlink datatype allows Sentences to link to a variety of electronic documents

You can use any kind of URL for the Hyperlink datatype including http for Web

page addresses mailto for email addresses and file for host-specific file names If

you are using Microsoft Outlook you can use the outlook prefix to create a URL that

links to a Microsoft Outlook folder

Instances of types that are defined with the Hyperlink datatype are sorted in a

casesensitive alphanumeric order (that is 0hellip 9 A B hellipZ a b hellipz)

The Hyperlink properties includes a default Protocol which can be set to ltAutogt

mailto http https file or specified yourself This will be used if no

protocol is entered in a dataform field

bull Email

The Email datatype is a convenient specialisation of the Hyperlink datatype with the

protocol hard-coded to be mailto

Numeric datatypes

The numeric datatypes are Number Currency MixedCurrency and Percentage All of

these datatypes support standard arithmetic and comparisons Any two Number or

Percentage instances can be used in arithmetic or compared Two Currency instances can

only be used in arithmetic or compared if they represent values in the same currency

When you select Number MixedCurrency or Percentage you must define the maximum

number of decimal places as shown in Figure 5-19

Figure 5-18 Defining decimal places for a number datatype

bull Number

The Number datatype supports storage to 17 significant digits with an optional sign

character (+-) of both floating point and integer values This datatype does not support

ldquoexponent and mantissardquo style inputs (for example 123e+10) Magnitudes smaller than

1e-16 are rounded to zero Magnitudes larger than 1e+17 are rounded to 17 significant

digits Numbers which cannot be stored exactly are rounded up or down to the nearest

exactly storable value

Instances of types that are defined with the Number datatype are sorted in numerical

order

Properties


192

Figure 5-19 Selecting the currency for a Currency datatype

bull Currency

The Currency datatype supports the use of monetary values A standard international set

of three character currency codes is used for example USD GBP and EUR The

currency datatype ensures that arithmetic can only be conducted between monetary values

in the same currency For example monetary values in queries must be of the same

currency in order to be compared

When you select the Currency datatype you need to select the currency as shown in

Figure 5-19

Instances of types that are defined with the Currency datatype are sorted in numerical

order

International considerations for the currency datatype

The way currency values are displayed on your system depends on your computerrsquos


your computer

bull MixedCurrency

The MixedCurrency datatype supports monetary values in more than one currency Each

value entry has two parts specifying the currency and the monetary value The only

arithmetical operations that are available with the MixedCurrency datatype are either

multiplication and division by a Number datatype or an arithmetical operation with

another value that has the MixedCurrency datatype

Instances of types that are defined with the MixedCurrency datatype are sorted by

currency type and then in numerical order

bull Percentage

Value instances defined with the Percentage datatype are floating-point numeric values

Instances of types that are defined with the Percentage datatype are sorted in numerical

order

Date and time datatypes

The date and time datatypes are Date Time and Timestamp Each of them has an

internal numeric representation allowing arithmetic and comparisons to be performed

correctly For arithmetic none of them supports the multiply divide or remainder

operators For comparisons earlier dates or times are considered to be less than later ones

Properties


193

International considerations for date and time datatypes

The way dates and times are displayed on your system depends on your computerrsquos


your computer

The Sentences date and time datatypes are based on the Java formats Date and time

formats for locales other than the US are only supported by the International version of

the Java Runtime Environment

bull Date

The Date datatype represents an individual date such as September 14th 1998 The

stored value is a whole number of days since a starting date This makes it independent of

time zones and ensures that comparisons for equality can be done correctly

Sentences does allow you to enter a year using only two digits although this is not

recommended Sentences calculates the century for two digit years by assuming a century

that begins 80 years before the current date and ends 20 years after the current date

If you enter a year using only one digit or using three or four or more than four digits

Sentences accepts the year value exactly as entered Sentences does not allow negative

values for years

Sentences does not accept invalid month and day of month values including leap year

calculation

For details of arithmetic operations that are supported with the Date datatype please see


Instances of types that are defined with the Date datatype are sorted in chronological

order

bull Time

The Time datatype represents a time of day such as 114305 The stored value is a whole

number of milliseconds since midnight Sentences stores and displays time without any

reference to time zones or time schemes This means that a value entered as 1100AM is

always displayed as 1100AM regardless of the time zone it is displayed in

When you perform arithmetic with time values additions and subtractions wrap around

2400 For example 2300 plus two hours gives 0100 not 2500

For details of arithmetic operations that are supported with the Time datatype please see


Instances of types that are defined with the Time datatype are sorted in chronological

order

bull Timestamp

The Timestamp datatype represents single point in time with millisecond precision such

as 1998 September 14th at 114305 BST Timestamp values are displayed in the context

of the current time zone However this affects only the display not the stored value

For details of arithmetic operations that are supported with the Timestamp datatype

please see ldquoArithmetic operations with Date and Time datatypesrdquo

Instances of types that are defined with the Timestamp datatype are sorted in

chronological order

Properties


194

Format properties page

Figure 5-20 (The Format properties page

The Format properties page is available on the Properties dialog for both entity types

and association types This page allows you to define the input and output formats

displayed on the Dataform The options available vary according to the datatype selected

and according to whether the association type is singular or multiple

The default format of association types is inherited from the datatype of the association

typersquos target You can use settings on the Format page to override the default settings

Presentation

Presentation options define the display of fields on the Dataform The first field in a

dataform represents instances of the source type and the label for this field is the name of

that type All the other fields on the Dataform represent the targets of associations sharing

the same source and the labels for these fields are the association verbs

You can define presentation options using the Properties dialog opened on an entity type

or an association type Presentation options defined for an entity type are inherited by any

association in which the entity type is a target but can be overridden by options set for the

association type

The following table shows the presentation options that are available for the different


Properties


195

Datatype of Target Presentations for Singular

Association Types

Presentations for Multiple

Association Types

Currency

Date

Hyperlink

Image

MixedCurrency

Number

Percentage

Time

Timestamp

Single Line

Combo

Radio Button

Tree

Table for targets


Nested panel

Button for target

Button for association

Label

List

Checkbox

Tree

Table for targets


ltNonegt

Text

Single Line

Multiple Line

Combo

Radio Button

Tree

Checkbox

Table for targets


Nested panel

Label

List

Checkbox

Tree

Table for targets


In addition the Checkbox and Combo are supported within tables when they can be

edited

The appearance of each of these presentation methods is as follows

bull Label

The association target is represented as a non-editable field with no border and so appears

as if a label The contents can be copied

bull Single Line

The association target is represented on the Dataform by a single line editable field

bull Multiple Line

The association target is represented on the Dataform by a multiple line editable field

bull Combo

The association target is represented on the Dataform by a single line field with a drop-

down arrow that can be used to display a list of existing target instances

bull List


bull Tree


displayed as an expandable tree similar to the display used in the Explorer data pane

bull Checkbox


by a small box and a text label More than one target may be selected

bull Radio Button

Properties


196


by a small circle and a text label Only one target may be selected In the following

definitions the term primary association refers to an association whose source is the entity

or association instance for which the Dataform is opened

bull Table for Associations

Table for Associations displays a primary association and all singular associations whose

source is the primary association The columns display the targets of the associations

concerned and the headings are the associations types The first column heading is the

type of the target of the primary association

bull Nested panel

A Nested panel displays a primary association (similar to a Single Line presentation) and

below it all associations whose source is the primary association within a nested panel

The secondary associations could themselves have any presentation including Nested

panel

bull Table for Targets

Table for Targets displays a primary association and all singular associations whose

source is the target of the primary association The columns display the targets of the

associations concerned and the headings are the associations types The first column

heading is the type of the target of the primary association

bull Button for Target

Button for Target displays a button that opens a child dataform on the target of the

singular association and its children The right-alignment format property is honoured

bull Button for Association

Button for Association displays a button that opens a child dataform on the singular

association and its children The right-alignment format property is honouredbull Disable

in-place editing

When the presentation option is set as either Table for Associations or Table for

Targets you can edit the target value directly in the Dataform table without the need to

open a child Dataform

You can disable this feature by checking the Disable in-place editing checkbox

Picker

Some Dataform fields allow you to select target instances from a list known as a Picker

launched from the ellipsis button next to the field The Picker field allows you to choose

either the List picker or the Tree picker for selecting values A List picker displays a

simple list of instances while a Tree picker displays a list of instances that can be

expanded to display associations as in the Explorer data pane

You can also select a special Calendar picker for types defined with the Date datatype

To disable the display of a picker select None as the Picker type

Style

The table below shows the different styles (for output) that are available for different


In the formats for Currency and MixedCurrency the letter C represents the currency

symbol for example pound or $ and the letter I represents the three letter ISO currency code

for example GBP or USD

Properties


197

Datatype Styles

ltNonegt ltNonegt

Currency ltDefaultgt

C0C-0

C000C-000

C0C-0

C000C-000

0C

000C

0C

000C

I 0I -0

I 000I -000

I 0I -0

I 000I -000

MixedCurrency ltDefaultgt

C0C-0

C000C-000

C0C-0

C000C-000

0C

000C

0C

000C

I 0I -0

I 000I -000

I 0I -0

I 000I -000

Date ltDefaultgt

Short

Medium

Long

Full

Number ltDefaultgt

0

000

0

000

Percentage ltDefaultgt

0

000

0

000

Text ltDefaultgt

Hidden

Time ltDefaultgt

Short

Medium

Long

Full

Properties


198

Datatype Styles

Timestamp ltDefaultgt

Short

Medium

Long

Full

SDateSTime (Short Date and Short Time)

SDateMTime (Short Date and Medium Time)

SDateLTime (Short Date and Long Time)

SDateFTime (Short Date and Full Time)

Display width

The Display width parameter specifies the width of the display field for an instance in

characters The unit for this setting is based on the width of a lower-case ldquowrdquo character

and the default setting is twenty-five characters

You can only use positive numeric values This parameter is disabled if the Presentation

method is set to Radio Button or Check box

Table column width

The Table column width field allows you to set the width for the association or entity

when it appears in a table on the Dataform The unit for this setting is based on the width

of a lower-case ldquowrdquo character The default setting if no value is specified is two-thirds of

the length specified for Display width

Display height

The Display Height parameter specifies the height of the display field in rows for multi-

line entries The default setting is six rows

Format options

The following options can be selected by checking the check-boxes on the Properties

dialog Format page for association types and entity types

bull Read only on Dataform

The Read only on Dataform option defines an association or entity that cannot be altered

by the user through the Dataform This setting is useful for association types whose

values are generated automatically by customised triggers For more information see

Chapter 10 ldquoCustomising Sentencesrdquo

bull Hidden on Dataform

The Hidden on Dataform option defines an association or entity that is not displayed on

the Dataform If you select this property there is no label or field for this type on the

Dataform and therefore no access from the Dataform for this type


automatically

bull Inverse Hidden on Dataform

The Inverse Hidden on Dataform option defines an association or entity that is not

displayed on the Dataform in the inverse direction If you select this property there is no

label or field for this type on the Dataform and therefore no access from the Dataform for

this type in the inverse direction

The default is to hide Association Types in the inverse direction

bull Hidden in Dataform tables

Properties


199

The Hidden in Dataform tables option defines an association or entity that is not

displayed in a Dataform table If you select this property there is no column for this type

in a Dataform table


automatically

bull Right-align in Dataform fields

The Right-align in Dataform fields option defines associations or entities which are to

be displayed as right-aligned in Dataform fields

bull Right-align in Dataform tables

The Right-align in Dataform tables option defines associations or entities which are to

be displayed as right-aligned in Dataform tables

bull Allow multi-line label on Dataform

The Allow multi-line label on Dataform option allows the label of a Dataform field (the

name of the source type or the verb of an association type) to be displayed over multiple

lines

Presentation of date formats

The presentation of Date formats depends on the version of the Java runtime environment

installed on your computer The US version of Java only supports the US date format

(monthdayyear) The Internationalised version of Java supports the European date

format (daymonthyear) If you only use two digits for the year Sentences assumes a

century that begins 80 years before the current date and ends 20 years after the current

date

Presentation of time formats

The presentation of Time formats depends on the version of the Java runtime

environment installed on your computer The US version of Java only supports a 12- hour

clock format with AM or PM The Internationalised version of Java supports the 24-hour

clock format If you are using the US version of Java you can input times as for example

130PM and if you are using the Internationalized version you need to enter 1330

Restore Default settings button

The Restore Default settings button on the Format properties page allows you to reset

all the values to the defaults for the current datatype For association types the Restore

Default settings button resets all the values to the current Format settings for the

associationrsquos target which may differ from the defaults for the datatype

Properties


200

Presentation properties page

Figure 5-20a The presentation properties pages for Entity Types and Association Types

The presentation properties are used to customise the presentation of Types and Instances

in Sentences This can be in the Sentences Explorer a Dataform or XML output that has

been transformed into HTML

bull Small icon large icon

The icons specified here will be used to replace the standard icons in the Sentences

Explorer and used in any XML output You can select an image from the Image picker by

clicking on the button The available images are those in the directory of image files on

the server

bull Start of section

Note Start of section is not applicable to Entity Types

The Start of section determines whether an instance of this association should start a new

section of the XML output Each section can have a title icon and some introductory text

assigned to it

bull Section title Section icon Introductory text

Note Section title Section icon Introductory text are not applicable to Entity Types

Each section can have a title icon and some introductory text assigned to it This is

intended to be used where the child results of this item will form the section details

You can select an image from the Image picker by clicking on the button The available

images are those in the directory of image files on the server

Properties


201

Display Name Query properties page

Figure 5-20b The display name query properties page

Display name queries can be used to enhance the ldquonamerdquo of an Entity or Association by

providing an alternative based on the instances attributes A Display Name Query can use

the full power of the query mechanism to form a name This is particularly useful when

the identifier for an Entity is an ID rather than a name as when mapping relational data

into Sentences In this scenario a Display Name Query can be used to display the name

attribute of the entity and the unique ID together making the display of those instances far

more readable and intuitive

For more details on Display Name Query capabilities and how to construct them see

ldquoDisplay Name Queriesrdquo

To specify a display name query

1 Open the Display Name Query page of the Properties dialog for one type

and click on the button

2 Select the query you wish to use or ltNonegt to remove an existing display

name query and click OK

Properties


202

Subsets properties page

Figure 5-21 The subsets properties page

bull The subsets mechanism

Subsets are one of the two mechanisms that allow different types in a database to share

common features The other mechanism is Supertypes

The subset mechanism allows you to define a group of instances of a given type that

match a particular condition You may create a subset that contains all the instances of its

superset The supertype mechanism allows you to define a hierarchy of types with certain

associations common to more than one subtype

Association types sourced on supersets and supertypes are shared by the respectivesubsets

and subtypes

bull Subsets properties

The subsets mechanism in Sentences allows you to define a set of instances of an existing

type as a new type You cannot select instances to be members of a subset as subset

membership is defined by a condition that is implemented as a query You can create a

new instance which is a member of a subset by opening a create Dataform on a subset

type When you save the Dataform Sentences checks that subset instances created in this

way meet the conditions for the subset

The subset properties page includes command buttons for creating a new subset query or

for attaching an existing query to a subset definition Whenever a subset is used its

membership is determined by evaluating the condition against the membership of the

superset

You can use the subset mechanism for association types as well as entity types

A subset type has all the source and target behaviour of its superset type This means that

all association types that have the superset as their source or their target exist in the same

form for the subset A subset can be a subset of only one superset type A subset cannot

be the superset of another subset which means that Sentences does not allow subsets of

Properties


203

subsets Also a subset cannot behave as a subtype (see ldquoSupertypes properties pagerdquo ) If

subtype behaviour is required you must define the superset type as a subtype

Sentences displays the existing subsets for a type using an expandable tree display

To create a subset definition

1 Click Create to open a dialog box in which you can name the subset and then click

OK

2 Click Edit Query to open the Query Editor (see Chapter 7 ldquoSentences queriesrdquo) and

define the subset query The subset query can include a condition that restricts

membership of the subset to items that meet the condition If you do not create a subset

query all the members of the superset are members of the subset A subset that contains

all the members of its superset can be a useful tool in defining the appearance of a

Dataform (see ldquoDataform tabbed pages with subsets and supertypesrdquo )

3 Use the Query Editor to create a query and then attach it to a subset using the Attach

Query command (or the Attach Set Query command if available) on the Schema menu

Using the Attach Query command replaces any existing subset query There is also a

menu item to Detach Subset Query

The result of a subset query must be a set of instances of the same type as the superset

type For example a subset query to define the type Married Person as a subset of

Person must return a set of instances of the type Person

A subset query must always use the superset type as its root node You cannot use another

subset of the same superset type as the root node The subset query can be edited from the

Subset properties page Subset queries appear with other queries in the All Queries folder

of the schema pane and can be edited from there in the same way as any other query

(Subset set queries appear in the Subset Queries sub-folder under the Set queries folder

of the schema pane)

Sentences displays an expand button next to subset queries in the schema pane Clicking

the expand button displays details of the type to which the subset query applies

After you define the subset query the subset type appears with all the other defined types

in the All types folder of the schema pane The superset and subset are both marked as

such in the schema pane by the addition of the system associations has subset and

subset of Examples of the use of subsets and supertypes are given in Chapter 6

ldquoAdvanced techniquesrdquo

Comparison of subsets and supertypes

In general a supertype should be used when the relationship between the instances of the

type and the parent supertype is a permanent one As an example of a permanent

relationship consider a schema which defined the entity types domestic dogs wild dogs

and wolves as subtypes of a supertype called canines In this case the status of an entity

instance is unlikely to change

A subset relationship is suitable where the status of entity instance is likely to change As

an example of this consider a schema in which the entity type customers with overdue

accounts is defined as a subset of the entity type customers In this case it is expected

that an entity instancersquos membership of the subset customers with overdue accounts is

temporary

There are some relationships that are less easy to define as being either permanent or

temporary and these need to be considered on a case-by-case basis bearing in mind the

requirements of the Sentences application you are developing

The relationship between the entity types Employee and Person is an example of this

An Employee is clearly a Person but may be an Employee for as long as 40 years or

for as little as 4 weeks In a business application you may need to record significant

Properties


204

information for an Employee and for a former Employee but not for any other Person

It is possible that some individuals entered in the database as Persons may go on to

become Employees In these circumstances it is appropriate to create a schema in which

the Person entity type is a supertype of the Employee entity type This has been done in

the Human resources example application (see ldquoThe Human resources example

applicationrdquo )

Dataform behaviour with subsets and supertypes

There are important differences between the behaviour of Dataforms when using

supertypes and subsets For a description of the differences for the base Dataform see the

section ldquoDataform tabbed pages with subsets and supertypesrdquo 9

Where custom Dataforms have been defined a type and its supertypes may have different

custom Dataforms selected as their default Dataform However where subsets are used all

the subsets will use the default Dataform set for the base type For more information on

custom Dataforms see the sections ldquoCreating a custom Dataformrdquo and ldquoCustom

Dataforms with subsets and supertypesrdquo

Subsets of association types

You can define subsets of association types in the same way you define them for entity

types using the Subsets tabbed page of the Properties dialog

The name that you enter when you create the association subset is its verb name The

subset association type uses the same source and target types as its superset type

Subset association types are displayed in the Explorer schema pane with yellow arrows

Where a subset association type is the source of one or more further association types the

base dataform for the superset association type has an additional tabbed page named for

the subset association type to display those associations

Viewing subset type instances

When instances of subset types are displayed in the data pane of the Sentences Explorer

they are identical in appearance to the instances of any other types

If the subset includes all the instances of its superset then the list of instances displayed

for the subset and the superset is identical You must remember that such listings are not

duplicates They are the result of the same instance being valid for display as an instance

of a type and as an instance of a subset type

Properties


205

Supertypes properties page

Figure 5-22 The Supertypes properties page

Supertypes are one of the two mechanisms that allow multiple types in a database to share

common behaviour The other mechanism is Subsets

The supertype mechanism allows you to define a hierarchy of types with certain

associations common to more than one subtype Supertypes should be used when the

correspondence between a type and its parent is permanent and subsets should be used

where the correspondence is temporary

Association types sourced on supersets and supertypes are shared by the respective

subsets and subtypes

An entity type can be a subset or a supertype of another entity type and an association

type can be a subset or a supertype of another association type

Supersets and subtypes are created in the database schema and are stored in the schema

changes chapter Subset entity types are displayed in the Sentences Explorer schema pane

with yellow icons

The Supertypes properties page allows you to associate a type with another existing type

in a hierarchical relationship A type that is defined as a subtype implements all the source

and target behaviour of its supertype This means that all association types that have the

supertype as their source or their target exist in the same form for the subtype A type may

be a subtype of more than one Supertypes A subtype may be the supertype for further

subtypes

To define a supertype

1 Click the Addhellip button to select an existing type as the supertype

After you define the supertype the supertype and subtype are both marked as such in the

schema pane by the addition of the system associations supertype of and subtype of

Properties


206

You can create instances of a subtype directly These instances are also members ofthe set

of instances for the supertype

Using supertypes with association types

You can define supertypes for association types as well as for entity types

Both the source and the target of the subordinate association type must be either the same

as or a subtype of or a subset of or a subset of a subtype of the source or target

respectively of the supertype association type

Examples of the use of subsets and supertypes are given in Chapter 6 ldquoAdvanced

techniquesrdquo

Equivalence properties page

You can use the Equivalence properties page to define two or more types as the same

This can be useful if you wish to merge databases and for example one database uses a

type named Clients and the other uses a type named Customers The types being linked

in this way must either be both association types or both entity types If they are value

types (entity types with defined datatypes) they must both have the same datatype

If you wish to make two association types equivalent they must share the same source and

the same target

The result of creating an equivalence between two types is similar to the result of creating

a supertype-subtype link between two types Instances of each of the two types share all

the associations of both types A Dataform display for either type or any instance of either

type shows a page for each of the equivalent types

To make two types equivalent

1 Open the Equivalence page of the Properties dialog for one type and click Add

2 Select the equivalent type from the picker list

To cancel an equivalence highlight the equivalent type and click Remove

You can also define equivalent instances (see ldquoInstance equivalencerdquo )

Triggers properties page

Figure 5-24 The Triggers properties page

Properties


207

Triggers are elements of custom Java classes and methods that users can add to

Sentences A trigger generally performs an action in the database whenever a specified

action called a trigger event takes place

You can view a list of available triggers by selecting Triggers from the View menu To



the Serverproperties file You can then use the Triggers properties page to assign the

trigger to a particular entity or association type The detailed steps for attaching a trigger

to an entity or association type and how to edit trigger assignments are given in the

section ldquoAttaching a triggerrdquo

There are examples of how triggers may be used in Chapter 11 ldquoWorked examplesrdquo

Description properties page

Figure 5-25 The Description properties page

The Description properties page allows you to add a free text description to any entity or

association type

Properties


208

Custom Dataform properties page

Figure 5-26 The Custom Dataform properties page

You can use the Query Editor to design a custom Dataform (see ldquoCreating a custom

Dataformrdquo ) You can use the Custom Dataform properties page to delete or rename an

existing custom Dataform and to create a new custom Dataform

Sentences displays the existing custom Dataforms for a type using an expandable tree

display

When you create a custom Dataform you can either attach an existing query or launch the

Query Editor to create a new query

You can also choose which Dataform should be used as the default Dataform for the type

Properties


209

State Domains properties page

Figure 5-27 The State Domains properties page

This property page is used to view and edit the tree of User and System State Domains for

this Type By default only System and Inherited Domains that are in use are displayed

You can select the Inherited and System checkboxes to include all Domains in the tree

See ldquoBusiness Rulesrdquo for details of Business Rule and State Domain functionality

Business Rules properties page

Figure 5-28a The Business Rules properties page

This property page is used to view and edit the list of Business for this Type See

ldquoBusiness Rulesrdquo for details of Business Rule and State Domain functionality

Properties


210

Diagram Images properties page

Figure 5-28b The Diagram Images properties page

You can use these properties to specify how this Type will appear on Sentences Diagrams

by default


bull Image Image link

You can specify either an image from the available images on the server or a URL that

specifies an image accessible from the Sentences client

bull Use default images

If you select to use default images the images specified in the ldquoPresentation Propertiesrdquo

will be used in preference to the images specified above

bull Text and Image

You can specify whether to display just text just an image or both If you choose both

then you can also specify whether to align the Text at the top bottom left or right of the

image

bull Hide border

You can specify whether to display a border around the diagram item or not by selecting

or deselecting Hide border

bull Background Colour

You can specify use of the default colour (the Sentences system colous) a transparent

background or a specific colour Click on the Change colourhellip button to select a custom

colour

Properties


211

Default Sorting properties page

The Default Sorting properties allows you to set how the Type will be sorted by default

when used in a Dataform or Custom Dataform

Sorting can use any of the nodes that will be available in the query used to display the

base Dataform You can have multiple sort nodes with different sort directions

Properties


212

Dataform (Navigation) properties page

Figure 5-28c The Dataform properties page

You can set the following properties on this dialog for both navigation to the target and

navigation to the source (if included on a dataform in the inverse direction) Only the

forward direction is described here but the same behaviour and rules apply to both

directions and can be set independently from one another



instances



Navigation





illustrated in Figure 5-28c














Properties


213

Dataform Filter properties page

AssociationTypes that are presented as a column in a table can be used as a filter when

the target is an Entity Type

The default filter can be either a specific instance or an expression

This peoperty is used as the default when creating a base or Custom Dataform that

includes the Association Type For more information see ldquoFiltering Dataform Tablesrdquo


EntityTypes only have one retrieval property








Association Type properties page

Figure 5-29 The association type properties page

Properties


214

The association type properties page resembles Create Association Type dialog You can

change the properties you set when you created the association type

Changing the properties of an association type may affect the properties appearance or

visibility of association instances based on it For example changing the cardinality of an

association type from Singular to Multiple allows you to use a list input field instead of a

single line input

If you change the cardinality of an association type from Multiple to Singular after

creating multiple associations for a source entity only the last association you created can

be seen in the Dataform All the created associations remain visible in the Explorer data

pane

If you change the cardinality of an association type you should always click OK on the

Association Type properties page before you make any other changes on any of the

other tabbed pages in this dialog

For more details on association type properties please see the section ldquoCreating

association typesrdquo

Target Parameters properties page

Figure 5-30 The Target Parameters properties page

The Target Parameters properties page allows you to restrict the targets for an

association type This properties page is not displayed on an entity type properties dialog

This mechanism is only available when the target of an association type is a subset

This properties page displays a list of the possible common source associations You can

define the association from which the target for the current association type may be

chosen

For an explanation of the use of Target Parameters see ldquoTarget parametersrdquo

Properties


215

Derived target properties page

Figure 5-31a The derived target properties page - default instance

Figure 5-31b The derived target properties page - derived expression

Properties


216

The Derived target properties page is available for association types only

As an aid to data entry you can define a default or derived target for an association type

When you open a create Dataform any default targets defined for the associations on that

Dataform are displayed If the target is derived then the target may be subsequently re-

calculated

This property page combines two previous mechanisms used in Custom Dataforms for

deriving a target if none already exists when the dataform is saved or always The

simpler mechanism simply specifies an existing instance to use

On a Custom Dataform there is an additional property to make the field read-only which

does not apply to the schema properties The derived target definition set for this

Association Type will be used as the default if it is used in a Custom Dataform Query

The derived target setting may be none an instance or an expression

bull Instance

Select an instance of the target type

bull Expression

Enter a valid expression The expression is validated in the context of the query that will

be generated to make the base dataform This means that other nodes can be referenced

For further information on expressions (see ldquoUsing expressions in queriesrdquo )

If the schema subsequently changes such that the expression is invalid then no target will

be derived until the expression is updated to reflect those schema changes


Figure 5-32 The Retrieval Methods property page for Entity Types and Association Types

The Retrieval Methods properties page allows you to specify two things

For Entity Type and Association types you can specify whether the server should try to

determine whether child associations are present (usually indicated by a plus sign to show

that the instance has children)

For Association Types only you can specify the way in which association instances are

retrieved from the database These settings can influence server response times

These properties determine the default behaviour when an association type is selected in

the schema pane and when a folder is expanded in the data pane You can override this

Properties


217

default behaviour by selecting a different option from the association type shortcut menu

or the View menu The shortcut menu is also available on data pane folders for multiple

instances You can define different settings for forward and inverse instances


bull By source (forward associations) By target (inverse associations) (default)

When you select the association type in the schema pane Sentences finds all the instances

of the source or target type and then searches for associations This option provides a

good response where most source or target instances have associations If only a few

source or target instances have associations this option can provide a slow response

bull Sorted

When you select the association type in the schema pane Sentences finds all suitable

instances of the association type and then sorts them by their source or target type and

displays the first 50 instances If there are a large number of associations this can be very

slow If there are a large number of source or target instances but only a small number of

associations this option can provide the fastest response

bull Unsorted

When you select the association type in the schema pane Sentences finds the first 50

suitable instances of the association type and displays them without sorting This option

can be used to display a sample of the available associations relatively quickly or where

neither of the other options provides a good response








Operations on instances

There are a number of operations that can be carried out directly on instances in the data

pane of the Sentences Explorer

These operations allow you to make one instance supersede another and to define one

instance as the equivalent of another It is also possible to create an association type

which has an instance rather than a type as its source

Properties


218

Supersedes

Figure 5-33 The supersedes dialog in the data pane

You can replace an instance with another instance of the same type using the supersedes

command Both instances must exist in the database before you use this command After

using this command the instance that has been superseded no longer exists in the

database

Supersedes is not available for value instances

To supersede one instance by another follow these steps

1 Highlight the instance to be superseded and select Superseded by from the shortcut

menu Sentences displays the Superseded by dialog box for the instance

2 Select the name of the superseding instance from the picker list and click OK

Sentences displays the Impact of supersession dialog listing the associations in which

the instance being superseded is involved

3 Click Supersede to continue or click Close to cancel the supersedes action

When you use Supersedes with a singular association type you may create a situation in

which a singular association has multiple instances If this occurs Sentences displays an

error message when you open the Dataform To remedy this error you must view the

association in the Sentences Explorer and delete the additional instances that are no

longer required When you use Supersedes with a multiple association type the lists of

associations from the superseding and superseded associations are merged

After a supersedes action the original instance no longer exists in the database in contrast

to instance equivalence where both equivalent instances persist in the database A

Supersedes action cannot be undone

Instance equivalence

You can define two entity or two association instances as being equivalent For example

you can make the instance International Business Machines equivalent to the instance

IBM The instances must be of the same or equivalent entity type or association type but

Properties


219

may be from different data chapters Equivalent instances have identical behaviour that is

all the associations of either instance are displayed as associations of both

Equivalent instances are displayed in the Explorer data pane in an instance subfolder

labelled equivalent to Instance

Where an instance is equivalent to more than one other instance then the same behaviour

is displayed by all the equivalent instances

Equivalent instances persist in the database in contrast to superseded instances which do

not Equivalence is not available for value instances

To make one instance equivalent to another follow these steps

1 Highlight an instance that you wish to make equivalent and select Equivalents from

the shortcut menu Sentences displays the Instances equivalent to dialog box for the

instance If any equivalent instances are already defined they are displayed in the list box

2 Click Add to display a picker showing suitable instances (instances of the same or of

an equivalent type) select an instance and click OK Repeat this step if necessary to

make more instances equivalent to the selected instance

3 Click OK to close the dialog

The following table lists the buttons on the Instances equivalent to dialog box and their

meanings

Button Action

Add Displays a picker so that you can select an existing

instance to be added to the list

Remove

Removes a selected instance from the list

(The selected instance is no longer equivalent to any of

the other instances shown)

Remove All

Clears the list This has the same effect as using the

Remove button on the current instance in the dialog for

another instance

OK Implements the selected changes and closes the

dialog

Cancel Discards the selected changes and closes the dialog

You can also define equivalent types (see ldquoEquivalence properties pagerdquo)

Instance-specific association types

If you select an existing entity instance or association instance as the source of an

association type that association type applies only to that instance This allows you to add

information that is specific to a particular instance

For example in a customer relationship management system you may wish to record the

golf handicap of only one customer You can do this in Sentences by adding an instance-

specific association type for example Bill Smith golf handicap golf handicap This

association type does not exist for other customers in your database


of the same type you can change the associationrsquos source to the type for example to

Customer golf handicap golf handicap When you make this change Sentences

preserves the original data you entered

The Dataform for an instance that has instance-specific association types includes an

additional tabbed page for the instance-specific associations The title of the tab is the

name of the instance

Business rules


220

To create an instance-specific association type highlight an instance in the explorer data

pane and select Create Association Type from the shortcut menu or click the Create

Association Type button on the Toolbar

Business rules

Version 40 of Sentences introduces Business Rules

Introduction

You may define State Domains for Sentences Types Each of these Domains has a set of

States that instances of the Type can exist in together with an assumed ldquoundefinedrdquo State

The way an instances State is determined is defined in a special Query called a Predicate

Query You can define rules stimulated by changes in State that either prohibit the change

or effect further changes mandated by them

There are two sorts of change those that alter an instance from a specified state to its new

state and those that alter an instance to its new state without regard for its prior state In

the latter case there must have been some change so all we can say is that the prior state

was not previously the ldquotordquo state

change = [state to] state

Sentences utilises two kinds of Business Rule State Rules and Change Rules A State

Rule prohibits a change

state rule =

ltchangegt prohibited

[when [not] state and | or [not] state] | Always]

The rule is created to stop a particular change from happening in specified situations

A Change Rule detects when a particular change has occurred and mandates further

changes

change rule =

ltchangegt mandates ltchange actiongt [ ltchange actiongt]

[when [not] state and | or [not] state] | Always

The changes you may wish to action are as follows

Create instance(s)

Delete instance(s)

Change association target(s)

Display a message to the user

Send a simple email

Fire a Sentences Trigger

Request that an instance changes to a specified state

Sentences V40 introduces new functionality to queries to facilitate such actions Queries

that include these actions must do so in the context of a Transaction For Business Rules

such queries are called Effector Queries

Business rules


221

Independently from Change Rules you may define an Effector Query and specify that it

will be executed when an instance changes to a given State When you create a Change

Rule you specify the change actions by specifying one or more States If the Change Rule

is stimulated then the Effector Queries of each mandated state are executed

System state domains

As well as user-defined Domains Sentences has built-in System State Domains These

allow you to define Business Rules and Effectors that are stimulated by changes managed

by the Sentences Database For example when an instance of a type comes into existence

the instances System Domain Existence changes to the System State of

ExistenceExistent You could use this state change to stimulate a Business Rule that

performs further actions when instances of that type are created

The full set of System State Domains is as follows

Domain State Cause Applies

Attributes Changed The attributes of an instance have been changed

ETs ATs

Equivalents EquivalentsAdded An instance has been made equivalent to another instance

ETs ATs

EquivalentsRemoved An instance has been made no longer equivalent to other instances

ETs ATs

Existence Nonexistent An instance has been deleted

ETs ATs

Existent An instance has been created

ETs ATs

Superseded An instance has been superseded by another instance

ETs ATs

Name Renamed An entity instance has been renamed

ETs

Sequence Resequenced An association instance has been moved within a sequence

ATs

Target Changed The target of an association instance has been changed

ATs

Uniqueness Violated An instance has been duplicated

ETs ATs

You must also be aware of timing issues when these state changes will be recognised

Once an instance has been deleted or superseded it is no longer visible even in the

context of the transaction that deleted or superseded it For this reason the

ExistenceNonexistent and ExistenceSuperseded states stimulate rules and fire their

Effector Queries just prior to them being deleted or superseded so that the effector

queries still have visibility of the instance in question

Domains and states

You may define any number of Domains for each Entity Type or Association Type

Types inherit Domains and their States from their supertypes and supersets Each Domain

can have any number of States States must have unique names within any Domain

Naming

Business rules


222

You cannot name a Domain with one of the System Domain names Duplicate Domain

names are not allowed on any one type but unrelated types can have Domains of the

same name

Generally for readability when naming Domains and States domain names should be

nouns and state names should be adjectives

The undefined state

The Undefined State is a ldquocatch allrdquo that is automatically included in all Domains It is the

state that is returned if none of the other states are valid

The Undefined State can be renamed to better reflect the Domain For example if you

have a Domain Archival with only two possible states of Ready and Pending you can

add the State Ready which you can define using an expression and rename the Undefined

State to Pending Anything that is not evaluated as Ready will have the state Pending

Viewing a types state domains

To view the State Domains for a type follow these steps

1 In the Sentences Explorer select the type that you wish to view the Domains for

in the Schema Pane and open its properties by Selecting Properties hellip from the

Edit menu

2 The Properties dialog will open Select the State Domains tab

3 The tab shows a list of all user-defined domains for that type

4 By default it will also include any inherited domains and the system domains

You may hide these domains by deselecting the Inherited and System

checkboxes on the page Inherited Domains can only be edited from the type that

they belong to

State Domains that are visible will also appear on the base Dataform











Creating a state domain

To create a State Domain follow these steps

1 From the State Domains tab of the types Properties select the Create State

Domain button to open a Create State Domain Dialog

2 Enter the name of the new Domain you wish to create and select OK

3 The new Domain will be created and added to the list A blank Predicate Query

and the Undefined ldquocatch allrdquo State are also created for the new Domain

Creating states

To create one or more States for a Domain follow these steps

Business rules


223


you wish to add a State to and select the Create State button to open a Create

State Dialog

2 Enter the name of the new State you wish to create and press Enter or Select

OK The Create State Dialog does not close

3 You can enter several States by typing in the names and pressing Enter

4 When you have finished adding States select Close to close the Create State

Dialog

Editing the predicate query to define states

The Predicate Query attached to each user-defined Domain is a specialised query for the

purpose of defining how Sentences determines which state an instance of that type is in

States are not set They are transient and are interpreted at a moment in time by their

Domains Predicate Query

You cannot delete a Domains Predicate Query and it does not appear in the list of

standard queries in the Sentences Explorer

To edit a predicate query follow these steps


you wish to edit and select the Edit Query button to open a Request Query

Editor

2 If you have not edited the Predicate Query before then it will contain a data

request node for the type a domain definition request node and the undefined

state definition

3 For each State you may add a state definition request node and define its

expression such that when evaluated it will indicate whether each instance has

that State

4 To add individual states select Add State from the context menu of the domain

definition node and then the desired state from the child menu

5 To add all state definition nodes for all the states not already added select Add

all State Definition Nodes from the context menu of the domain definition node

6 The expressions entered will depend on your needs In the example below we

are concerned with an employee bonus scheme and the state of an individual

Employee

Business rules


224

The states are not necessarily mutually exclusive Ideally they would be but this is not

always practical

In the above Predicate Query the Validity can be both Close to retirement age and Invalid

at the same time In this case it is the order of the predicate expressions that determines

the state If none of these conditional statements evaluate to true then the ldquocatch allrdquo state

of Undefined becomes the instances State for the Validity Domain In this example it has

been renamed to Invalid to be more meaningful than Undefined

State Domain Analysis

When designing the State Domain and its predicate query on an existing set of data it is

useful to be able to see what the current states are There is a tool to perform this in the

Query Editor

To analyse the instances for a State Domain follow these steps

1 When editing the State Domain predicate query select the State Domain

Analysis menu item from the Tools top level menu

2 The Schema tab on the right hand side will display a panel showing the progress

and then results of the analysis This may take some time depending upon the

volume of data

3 You can select the Copy Details button to copy this summary to the clipboard

4 You can use the List button against each state count to list the individual

instances in the results pane

5 You can use the Query button against each state count to open a new query that

will return only instances with that state This is inteded to be used to manipulate

those instances For example to find all the invalid instances and perform actions

on them to make them valid Note that the predicate query must be saved before

the generated query will produce the correct results

Business rules


225


An instances state can be obtained in a regular query in two ways You may add a state

request node or use the GetState function in an expression

To add a State Request Node follow these steps

1 Select the Node you wish to request the State for From the context menu select

Add and then Stateshellip

2 In the dialog that opens select one or more Domain that you wish to request the

State of

3 The State Request Nodes will be added to the query node

The GetState Function for use in Query Expressions takes two parameters The first

parameter is a reference to the node for which the state is required The second parameter

should resolve to the name of the Domain for which the state is required

Note that only one state will be returned per instance If several of the State definition

expressions evaluate to true then the first one will be returned so the order of the State

definitions is important Only if none of the state definition expressions evaluate to true

will the Undefined State be returned

If a State request is included in the query that defines a Custom Dataform then the state

will be displayed as a read-only field on the dataform

Business rules


226

If the state request is bound to an instance and a Button Text attribute is specified then

the state will be represented as a button Clicking the button will fire the effecters for that

state on the dataform instance

Effector queries

Effector Queries like Predicate Queries are extensions to the standard Sentences Queries

They do not appear in the list of regular queries as their use is very specific to Business

Rules functionality

An Effector Query is a special kind of Update Query which has the ability to modify data

Its execution is intended to effect one or more changes By attaching an Effector Query to

a State you are instructing Sentences to execute the query when an instance changes to

that state In a Change Rule when you specify a State as mandated by a change you are

instructing Sentences to execute all the Effector Queries attached to that state for the

given instance

In a Change Rule the inference is that you desire one change to lead to a particular state

but this does not mean that the instance will necessarily gain that particular state or that an

Effector Query will bring about that state


Update Queries or Effector Queries This allows you to try your Query explore and check

the results and then revert to the state the database was in before execution In this way

you can experiment without fear of corrupting your data See the section on Sandbox

Modes for details

Because an Effector Query can modify data those changes may lead to further state

changes and thus further Effector Queries being executed in the transaction

Effector query parameters

Effector queries have three built-in parameters that are populated depending upon the

kind of change that led to their execution

bull update_subject

The update_subject is populated with the instance that has been affected For

example the new instance the instance about to be deleted the instance that has been

renamed the association that has had its target changed and so on

bull update_old_name

For the special situation where an entity has been renamed it may be useful to know the

name before it was renamed The update_old_name is populated with the old name

bull update_old_target

For the special situation where an association has its target changed it may be useful to

know what the old target is The update_old_target is populated with this old target

Business rules


227

Creating an effector query

To create a new Effector Query follow these steps


wish to add an Effector Query to and select the Add an Effector Query button

A new blank Effector Query will be created and opened in a Query Editor for

you to define

By default the query will be based on the Domains type with a Data Request

renamed to ldquoupdate_subjectrdquo so that it is bound to the parameter of the same

name

2 You can now construct the query to include relevant data and action the changes

you desire See the next sections for each kind of change Select the Save toolbar

button and close the Query Editor once you are finished

3 The name of the query will be derived from the domain and state that you are

creating it for but you are free to rename it from the State Domains tab of the

types Properties Select the query you wish to rename and select the Rename

button or press F2

An Effector query has the same functionality as an Update Query For details of Update

Query abilities see the ldquoUpdate Queriesrdquo section

Effector triggers


were the only available mechanism to do so prior to Version 40

As well as executing one or more Effector Query when a State is mandated you may also

fire one or more Sentences Trigger


details of what was changed and why If a trigger is fired in this way then this information

is included

Creating an effector trigger

To create a new Effector Trigger follow these steps


wish to add an Effector Trigger to and select the Add an Effector Trigger

button The Add Effector Trigger dialog showing the available triggers will be

opened



4 Select another trigger or Close when done

Business rules

Business Rules allow you to define the behaviour of your application without the need for

specialist programming knowledge Once you have designed and created your State

Domains to define the states that your application entities may exist in you can use

Business Rules to prohibit undesirable behaviour and mandate desired actions when

suitably stimulated

Creating a state rule

You may use State rules to prevent undesirable behaviour

To create a State Rule follow these steps

Business rules


228

1 From the Business Rules tab of the types Properties select the Create State

Rule button A New State Rule dialog will open

2 Define the change that will be prohibited You may optionally specify the




4 Select Always to specify that the change will always be prohibited

OR

5 Select When to specify how the change will be prohibited You must enter the

condition that needs to be fulfilled for the change to be prohibited

In the example below when a Projects Name System Domain changes to the Renamed

state then that renaming is prohibited only when the instances user defined Cycle

Domain is in the Closed or Progressing states

Creating a change rule

You may use Change rules to define mandated changes as a result of suitable stimulus

To create a Change Rule follow these steps

1 From the Business Rules tab of the types Properties select the Create Change

Rule button A New Change Rule dialog will open

2 Define the change that will stimulate this rule You may optionally specify the




4 Select one or more States to be mandated You may add as many States to the

selected list as required Each will have their effector queries executed when this

rule is fired

Business rules


229

States with a red background do not have any associated Effector Queries or

Effector Triggers As such they will not affect anything You are not stopped

from adding these as you may later add effectors to them

5 Select Always to specify that the change will always mandate these states

OR

6 Select From to specify under which conditions the states will be mandated You

must enter the condition that needs to be fulfilled

The From State

When a User Defined State change triggers a business rule there are several ways to

determine if a change has taken place If you specify a specific change from state and a

different change to state then it is obvious to the system how to act You may wish to

trigger a rule to fire whenever an instance ends up in a state such as invalid regardless of

its initial state even if it started in that state You may wish to trigger a rule even if there

was no previous state before the transaction started (because the instance did not exist)

Because of this there are four predefined Change From states that you can use to

indicate the desired behaviour

bull ltAny Stategt triggers the rule when the initial state is any state including the change to

state including no previous state Any instances already in the change to state will be

triggered

bull ltAny Other Stategt triggers the rule when the initial state is any state except the

change to state including no previous state Any instances already in the change to state


bull ltAny Existing Stategt triggers the rule when the initial state is any state including the

change to state except for no previous state Any instances already in the change to

state will be triggered

bull ltAny Other Existing Stategt triggers the rule when the initial state is any state except

for the change to state or no previous state Any instances already in the change to state


Business rules


230

Disabling individual rules

All Business Rules or individual Business Rules can be enabled or disabled in the

properties for that Type

Business rules reference


administrators

Business rules parameters in the Serverproperties file

The following parameters in the Serverproperties file are used by Business Rules

bull MaxConcurrentEffectorMessages

You may use this property to specify the maximum number of Messages generated by an

Effector Query before we curtail reporting to the client (to avoid overwhelming the client)

bull MaxConcurrentEffectorSMTPEmails

You may use this property to specify the maximum number of Simple Emails generated

by an Effector Query

bull BusinessRulesDisabled

You may use this property to disable the Business Rules functionality By default

Business Rules are not disabled

bull MailSMTPHost

The MailSMTPHost property must be specified in order to send simple emails from

Effector Queries If the server requires authentication then you will also need to provide

details

bull MailSMTPUser

bull MailSMTPPassword

bull NotifyUserOfSMTPMailFailures

If the simple email SMTP details are not set up or fail for another reason the user will be

informed This property is true by default You may use this property to stop such

information being displayed by setting it to false

bull MailSMTPValidFromList

Business rules


231

As it will be an application rather than an individual that is sending the email one or more

such ldquonoreplyrdquo accounts will need to be set up for this use This property can be set to a

list of accounts that you wish to allow the users to send email from Multiple addresses

are separated by semi-colons

Browsing state domains


the State Domains in your Schema at once You can also use the position and filter tools


The State Domains Schema Folder is displayed according to your User Preferences See


Browsing business rules


the Business Rules in your Schema at once You can also use the position and filter tools




232

The Business Rules Schema Folder is displayed according to your User Preferences See



The Sentences Dataform is a dynamically generated data viewing and data entry window

In the Sentences client all entity value and association instances are created using a

Dataform

You can open a Dataform either on an association or entity type to create new instances

and optionally create the associations for those instances (see ldquoThe create Dataformrdquo ) or

on an association or entity instance to edit or update the associations for that instance (see

ldquoThe update Dataformrdquo )

The base Dataform for an entity or an association displays associations which have that

entity or association type as their source Each association is represented by a labelled

field The field label is the same as the verb of the association type and the field itself

allows you to view or define a target Each target defined in the Dataform represents an

association instance

If you defined an association type as singular then the Dataform field for that type only

allows a single entry If you defined an association type as multiple then the Dataform

field for that type allows multiple entries You can control the display of Dataform fields

using the Properties dialog or panel for each entity and association type as described in

the section ldquoPropertiesrdquo

Dataform Layout Systems

There are two systems for laying out fields in dataforms Page Layout and Section

Layout The original Page Layout system has been replaced with the more flexible and

sophisticated Sections Layout system The Section Layout system is the default but can be

changed by setting a server property See the Server properties section for details

Dataform Page Layout System

The original Dataform Page Layout System for dataforms uses a single column of fields

on multiple tabbed pages Tabbed pages are automatically generated according to the

schema structure Different supertypes subsets equivalent types and schema groups



233

The order in which the fields are displayed in the Dataform depends on the order in which

they appear in the schema pane If there are any association types sourced on instances of

a type the instances are displayed on their own tabbed pages as well

For further information see ldquoDataform tabbed pages with subsets and supertypesrdquo

Dataform Section Layout System

The Dataform Section Layout system uses a separate structure of Sections to define the

layout of forward and inverse Association Types and State Domains For a Custom

Dataform Derived Types can also be included in Sections

Each Section can be a logical grouping of fields but can also define presentation

attributes A Section can represent a tabbed page a bordered panel or allow the designer

to place multiple columns of fields on one dataform These Sections can themselves be

added to other Sections and so sophisticated dataform layouts can be defined

Each Entity Type and Association Type has an associated set of Sections that define the

default (base) layout for Association Types sourced on it To organise the child

Association Types and Sections select Organise Dataform Sections from the Schema

menu

The organiser dialog allows you to move child schema around create delete and modify

sections and alter some of the dataform presentation attributes common to the standard

schema properties For example whether an inverse association should be visible on

dataforms by default Hidden Association Types are shown in grey

Unlike the Page Layout System the inclusion and location of inverse associations and

State Domains can be defined

The Sections have attributes to affect the way that these children are displayed in-line

new-line or tabs There are attributes to give the section a border a title some

introductory text or footer text and how to fill the available space The title attribute is

used for a bordered panel and tabs If no title is set for a tab then the section name is used

as a default If no title is given for a bordered panel then the panel simply has a plain

border

Schema Section defaults are generated when schema is created and modified

1 When an ET or Subset is created no sections are generated



234

2 When an AT is created then both the source and target have Sections added (if

not already there) and then the AT is included (forwards for the source and

inverse for the target) Inverse ATs are still hidden by default Note they appear

greyed out in the Section Organiser

3 When a State Domain is created a section is added to the owning Type (if not

already there) and the domain is included in that section

4 When an AT changes its Schema Group (including being included in a group for

the first time and including being removed from all Groups) then the AT is

removed from the previous Section and included in the new Section Any

required new Section will be created (with the Group name or SourceTarget

name) If a Section is now empty after the AT is removed then the Section is

deleted

5 When an AT is deleted then it is automatically removed from the source and

target Sections created in item 2 If a Section is now empty after the AT is

removed then the Section is deleted

6 If a Type is renamed then if it has an existing Section with the old name it is

renamed to match

7 If a Schema Group is renamed then if it has an existing Section with the old

name it is renamed to match

8 If a Schema Group is deleted then the contents are moved to the appropriate type

Section (if available) If the Section for the Schema Group is empty then it is

also removed

9 If an AT has its source or target changed then any Sections for the old

sourcetarget have the AT removed and if now empty the sections are removed

The new AT is included in the new relevant Section creating a new Section if

needed

The default Schema Sections created for types will be formatted as Tab Pages that will fill

the available space vertically and horizontally by default For an Association Type that is

to be represented as a Table for Associations the default Section will be an in-line

section

In the Sentences Explorer a new schema menu item View Base Dataform Query

opens up the Query Editor with the request that is generated from the Dataform Section

metaschema This query can be saved as the starting point for a Custom Dataform

This includes the second-level requests required for tables and nested panels

Dataform Field Formatting

The way fields are displayed in the Dataform is defined in the properties for the

association type concerned For example an association that has been defined as multiple

has by default a list-box display in the Dataform

Mandatory association types are marked with an asterisk () on the Dataform You cannot

save a Dataform unless you supply a value for every mandatory association

If a dataform contains fields which are calculated then it will automatically refresh these

calculations whenever a field is changed by default This ldquoauto-refreshrdquo function can be


For the Section Layout system there is an additional attribute for Association Types and

State Requests The Label positioning of Top Left or None can be specified



235

The base Dataform and the default Dataform

Sentences can always create a Dataform which automatically displays all the associations

belonging to a particular source type This is known as the base Dataform State

Domains that are viusible will also appear on the base Dataform











You can use the Query Editor to design and save a custom Dataform that may only

display a selection of the available associations or inverse associations For information

see ldquoCreating a custom Dataformrdquo

You may define either the base Dataform or a custom Dataform as the default Dataform

for a source type

Sentences displays the default Dataform whenever you select the Dataform for a type

either from the Explorer or from another Dataform If you do not define a default

Dataform Sentences uses the base Dataform

To define a Dataform as the default Dataform follow these steps

1 In the Sentences Explorer highlight the entity or association type

2 Select Properties from the shortcut menu or click the Properties button on the Toolbar

3 Select the Custom Dataforms tab

4 Highlight the Dataform that you want to use as the default and click Set as Default

Create and update Dataforms

You can open a Dataform on a source entity type and use it to create new associations

This is known as a create Dataform You can also open a Dataform on any source type

or instance which can be used to update existing associations This is known as an update

Dataform

The create Dataform

You can display a create Dataform from the shortcut menu on an entity type in the

schema pane or by highlighting an entity type and clicking the Dataform button on the

toolbar An example of a create Dataform is shown in Figure 5-34 If you open a create

Dataform on a subset entity type Sentences displays the create Dataform for the subsetrsquos

superset type

Create Dataforms always show the words New xxx in their title bar (where xxx is the

name of the entity type) You can use this Dataform to create an entity and its

associations and optionally create new entities to be the targets for its associations all in

one operation



236

Figure 5-34 A Create Dataform

The first field on the Dataform has the name of the entity type as its label Type in the

name of the new entity you want to create in this field

You can type in new names in other fields to create additional new entities as targets of

the associations shown on the Dataform as long as those new names are valid for the

target type Alternatively you can select the association targets from existing instances of

the appropriate type

Some of the association target fields on the create Dataform include an ellipsis button

which you can click to display a picker list showing the existing instances If the display

format of the association target field does not include an ellipsis button you can right-

click on the field and choose the Select Existing Instance command from the shortcut

menu

The buttons on a parent create Dataform are Save amp Reset which updates the Dataform

contents to the database and displays a new blank Dataform Save amp Edit which updates

the Dataform contents to the database and allows you to continue to update the same

Dataform and Close which closes the Dataform If you make changes to the Dataform

the label for this button changes to Cancel

Selecting Cancel closes the Dataform without updating the database Sentences displays a

warning message that any new information in the Dataform is not saved A child

Dataform has an Apply command button which temporarily saves the Dataform contents

and allows you to continue to update the same Dataform and an Apply amp Reset button

which allows you to add additional child associations before returning to the parent

dataform Changes made on a child Dataform are only saved to the Sentences database

when you select a Save button on the parent Dataform from which it was called (see

ldquoParent Dataforms and child Dataformsrdquo)

When you open a create Dataform that includes any association type defined as

mandatory you cannot save the Dataform if you do not supply a target for that association

The update Dataform

The update Dataform is displayed when you select Dataform from the shortcut menu on

an entity or association instance in the data pane An example of an update Dataform is




237

Figure 5-35 An entity instance update Dataform

When you open a Dataform on an entity instance the name of the entity is shown as the

first field in the window The only shortcut menu options for that field are Rename and

in the case of a Hyperlink Follow Hyperlink When you open a Dataform on an

association instance the identifying source verb and target of the subject are shown in the

window title bar

You can use the Dataform to rename the entity that appears in the first Dataform field

This field has the entity type name as its label To change the name of an entity select

Rename from the shortcut menu on this field

The Rename command is not available for value instances To change a value instance

either select a different instance from the picker list or delete the current instance and type

in a new one

Some association target fields on the update Dataform include an ellipsis button which

allows you to choose an existing entity as the target for each association Alternatively

you can create a new target entity by typing in a valid value (depending on the datatype

selected for this entity type)

The buttons on the update Dataform are Save (or Apply on a child Dataform) which

updates the Dataform contents to the database and allows you to continue to update the

same Dataform and Close which closes the Dataform If you make changes to the

Dataform the label for this button changes to Cancel Selecting Cancel closes the

Dataform without updating the database

Parent Dataforms and child Dataforms

A Dataform can be a parent or a child depending on how it was opened Any Dataform

opened from the Explorer is a parent Dataform A parent Dataform is modeless

Any Dataform opened from another Dataform is a child Dataform except in two specific

cases listed below A child Dataform is modal with respect to its own parent Dataform

but modeless with respect to any other parent Dataform the Explorer or the Query

Editor

The only cases in which a Dataform opened from another Dataform is a new parent

Dataform are

bull if the target of an association shown on the Dataform is an association and you open a

Dataform on the source of the target association

bull if the target of an association shown on the Dataform is displayed as a tree and you

open a Dataform on any level of that tree below the top level

Creating an association in the Dataform

To create an association instance using the Dataform you must first select an instance of

the required associationrsquos source and then open the Dataform for that instance



238

To open the Dataform you can either


and select Default Dataform from the shortcut menu or


and select the Default Dataform command on the View menu or


and select the Dataform button on the toolbar

You create an association in the Dataform by entering data in the target field As an

alternative to typing in a new value you can select from existing instances of the

appropriate type

To select an existing instance click the ellipsis button to the right of the entry field

Sentences displays a picker list from which you can select the target You canalso display

the picker list by right-clicking on the entry field and selecting Select lttarget typegt from

the shortcut menu or by pressing Alt + down arrow on the keyboard

If you select an entity or value instance from the picker list for a multiple association

Sentences first places the value in the edit field where you can edit it When you press

Enter or move to another field Sentences moves the value to the main list If you select

an association Sentences places it directly in the main list

Association type targets and metatype targets

If the target of an association type is an association type you cannot create a new instance

of the target by typing into the target field on a Dataform You can only create a new

instance by clicking the ellipsis button and selecting a target from the list displayed

Similarly if the target of an association type is a metatype you cannot create a new

instance of the target by typing into the target field on a Dataform You can only create a

new instance by clicking the ellipsis button and selecting a target from the list displayed

Dataform shortcut menu

When you right-click on a field in the Dataform Sentences displays a shortcut menu The

text of the shortcut menu commands includes the name of the association or the target

concerned This is indicated by the text in square brackets in the table below Not all

commands are available at all times for example the Create Select and Delete options

are not available if the presentation format is Radio Button or Check box


Follow Hyperlink If the target is a hyperlink

Opens browser or mail

program as required by

Hyperlink

View [association with this

target] Always

Displays a child Dataform for

the association If no

association exists the

displayed Dataform shows

the target only

View [target] Always Displays a child Dataform for

the target

View [source] When target is an

association type

Displays a parent Dataform

on the source of the target

association



239


Create [new association]

If this association is the

source of a further

association

Displays a child create

Dataform for the association

Create [new target] If this target is an entity type Displays a child create

Dataform for the target

Select [existing target Always Displays a picker list

Delete [association] When an association exists Deletes the association

Note The options Create [new target] Select [existing target] and Delete [association] may

be restricted or disabled by the query defining a custom Dataform

Selecting targets in the Dataform

The display of an association target in the Dataform varies according to the datatype of

the target type and the Format and Presentation options defined for the association type

and the target type

If an association target in a Dataform field is underlined this means either that the target is

a Hyperlink or that the association is itself the source of one or more further associations

If you double click a Hyperlink Sentences displays the target page for that Hyperlink in

your Web browser mail program or other application depending on the protocol being

used

If you double click an underlined target that is not a Hyperlink Sentences displays a

Dataform that has that association as its source

Double-clicking a word in a multi-line edit field selects that word

When association targets are displayed in a Table for target or Table for associations

format each field may be edited directly in the table This property can be disabled by

selecting the Disable in-place editing checkbox on the Format page of the Properties

dialog To open a child Dataform for the row displayed in a Dataform table double-click

any cell in the row The source of the child Dataform is the instance displayed first

column of the table

Creating an entity instance in the Dataform

Entity instances are always created in a Dataform When you are working in the

Sentences Explorer and want to create an entity instance follow these steps

1 Highlight an entity type name in the All types folder and select Dataform from the

shortcut menu

Note You cannot open a Dataform for a value type

Sentences displays a create Dataform (see ldquoCreate and update Dataformsrdquo ) which has the

selected entity type as its source

2 Enter the entity instance name in the first Dataform field This field has the entity type

name as its label

3 If there are any association types defined for the entity type the appropriate association

fields are displayed on the dataform and you can create the corresponding associations at

the same time as you create the entity To create an association either select an existing

instance from a Picker list or type in a new entity name Sentences automatically creates a

new entity instance of the appropriate type with the name you have used



240

Note Only the base Dataform contains all the associations for a type If you have defined a

custom Dataform as the default for the entity type it is possible that some associations may not

be displayed

4 Click Save amp Edit or Save amp Reset

Targets with duplicate names

Sentences uses unique hidden identifiers for entities (and for many other elements) This

means that you can create entities with duplicate names and rename entities as needed

Sentences always prompts you to confirm that you want to create a duplicate entity when

an entity with the name you are using already exists

If you type in a target name for which duplicate instances already exist Sentences

prompts you to select the correct instance by displaying the Resolve Instances dialog

This dialog displays all the identically named instances in a tree picker window which

allows you to expand the names and view their associations so that you can select the

correct instance Highlight the correct instance and click OK to make your selection

The Resolve Instances dialog is not displayed if you select a target instance from a picker

list

Targets that are subsets

The target of an association type may be a subset If you enter a new target instance for an

association type whose target is a subset Sentences checks that the instance you have

entered is a valid member of the subset

If the instance is not a valid member of the subset Sentences displays an error message

For more information on subsets see ldquoSubsets propertiesrdquo

Changing the target in a Dataform

You can change the target of an association in a Dataform either by selecting an existing

instance from a picker list or by typing in a new entity name

When you change a target Sentences checks whether the association you are changing is

the source of further associations If it is then Sentences treats changing the target in the

same way as it treats deleting a target Sentences may display a Deletion Impact dialog

listing showing what else is deleted when the target is changed

If you change the target in an association and that target is the source of a mandatory

association you must provide a value for the mandatory association before you save your

changes to the database Sentences displays an error message if you try and save without

completing all the mandatory associations

When you save a changed target on a dataform Sentences automatically checks whether

the change has affected membership of subsets

Instance specific Dataforms

When you open a Dataform on an instance that has instance specific association types

sourced on it the Dataform includes additional fields for those association types (see

ldquoInstance-specific association typesrdquo )

Picker list initial selection

Whenever you open a picker on a field in which you have started to type a new value the

picker puts the text that you have already entered into the Positioner field and performs a

positioning operation on that text



241

Business rules and states

Sentences Dataforms can display instance states These are displayed as read-only fields

They are not present in a Base Dataform but can be added as part of a Custom Dataform

query When a dataform is saved and not reset any states that have changed will be

updated

If a dataform field requires a particular input format or is mandatory and these

requirements have not been met then the field is highlighted in red to indicate this when

you attempt to save the changes With the introduction of Business Rules if by changing

or entering data on a dataform you directly or indirectly cause a state change that is

prohibited then the field in question will be similarly highlighted if possible

Display names

Sentences Dataforms show types display names in the dataform title and in fields if they

have Display Name Queries attached to their types Custom Dataforms can override the

Display Name Query to use (or none) for individual fields

Table and list buttons

Sentences Version 40 enhances dataform tables and lists with convenience buttons for

viewing adding and deleting items in the list or table

Creating a custom Dataform

The base Dataform for an entity or association type automatically includes all the

associations that have that type as their source When using the Section Layout system

the schema sections are used to layout the fields on the base dataform A custom

Dataform displays only those associations you choose to display Creating a custom

Dataform involves two steps

bull defining the custom Dataform on the Custom Dataform page of the Properties dialog

for the type

bull developing a query in the Query Editor which defines the associations to be displayed

on the custom Dataform and attaching it to the custom Dataform definition You may

also attach an existing query to a custom Dataform definition

Full details about using the Query Editor are given in Chapter 7 ldquoSentences queriesrdquo



242

To create a custom Dataform follow these steps

1 Open the Properties dialog for the entity or association type and select the Custom

Dataforms tab All the dataforms for the current type are listed including the base

dataform which always has the name of the type inside angle brackets The default

dataform is marked ltdefaultgt

2 Click Createhellip and name the custom Dataform

Figure 5-36 Selecting a query to attach to a subset

3 If you have not created a query click Edit Query Sentences creates a new query with

the current type is automatically selected as its data request node saves it with the name

you gave to the custom Dataform attaches the query to the custom Dataform definition

and opens it in the Query Editor for you to customise

4 Use the Query Editor to customise the query that includes the associations you want on

your Dataform as nodes in the request tree You can use forward and inverse associations

in the query tree Hidden nodes in the query tree are not shown in a custom Dataform

The Query Editor offers a number of options that are not suitable for use in custom

Dataforms For example select and sort nodes would generally not be appropriate for

custom Dataforms Similarly the use of parameters or the use of required nodes in the

query would not be appropriate for custom Dataform use

In addition derived type nodes are displayed as a read-only fields Sentences displays an

error message if you try to create a custom Dataform using an unsuitable query

5 Save the query and close the Query Editor

6 If you have already created a query to use for the custom Dataform definition click

Attach Query Sentences displays a list of suitable queries for the current type as shown

in Figure 5-36 For details of how Sentences determines which queries are suitable see

ldquoCustom Dataform restrictionsrdquo Select the saved query you created from the list and

click OK



243

7 If you want the custom Dataform to be used as the default Dataform click Set as

Default

Using the Dataform Section Layout system custom dataforms can arrange their fields in

sophisticated ways See the Human resources example profile for examples like the

Employee Custom Dataform

Refresh button on custom Dataforms

If a custom Dataform is based on a query that includes a derived type or a derivation an

additional button Refresh appears on the dataform (see ldquoDerived types and derivationsrdquo

) When this button is selected Sentences calculates the values for the derived types or

derivations shown on the Dataform The recalculation of a derivation is dependent on the

setting of its calculation option in the Derivation properties dialog (see ldquoDerivation

propertiesrdquo )

Custom Dataform restrictions

You can only use a query as the basis for a custom Dataform if it conforms to certain

rules The following conditions apply to any query that you want to use as the basis of a

custom Dataform

bull the query must have a data request node

bull the queryrsquos data request node must have a type

bull the type of the queryrsquos data request node must be related to the type that thecustom

Dataform is intended for

bull the queryrsquos data request node must not be hidden

bull the queryrsquos data request node must not be bound to an instance

bull the query may not have any parameters

bull the query may not use recursive closure or transitive closure


are invoked as normal when you click the Save button (see ldquoTrigger invocationrdquo )

Selecting a custom Dataform

You can select a custom Dataform instead of the Default Dataform from the Dataform

sub-menu of the Explorer shortcut menu

Sentences uses the first character of the custom Dataformrsquos name as a keyboard shortcut

key for the custom Dataform If the names of two or more custom Dataforms begin with

the same letter you cannot use the keyboard shortcut key to select the second or

The Dataform applet


244

subsequent custom Dataform as the key sequence always selects the first custom

Dataform

Where one or more custom Dataforms are defined for a type or for any of its supertypes

there is a choice of Dataforms that may be used to view and to create instances Define

the Dataform to be used as the default for a type using the Custom Dataforms page on

the Properties dialog

Custom Dataforms with subsets and supertypes

You cannot define a default Dataform for a subset type independently of its base type

The pages that appear on a dataform for a subset are always the same as those that appear

on the Dataform for the base type and all the criteria for the subset must be met before

the Dataform and its data can be saved

You can define different custom Dataforms for an entity type and its related supertype

and select different default Dataforms The pages displayed on these Dataforms may vary

If a Dataform includes an association that is not relevant for the selected type the field

remains blank

For more information about subsets and supertypes see the section ldquoComparison of

subsets and supertypesrdquo

The Dataform applet

You can display a Sentences Dataform as a stand-alone Java applet This is known as the

Dataform applet You can embed the Dataform applet in an HTML page on a Web server

to create a customised user interface for your Sentences database When you use the

Dataform applet you can specify the Dataform you want to use which may be either the

base Dataform or a custom Dataform for a named entity type

The dataform applet is controlled by an HTML page that supplies parameters to the applet

specifying the host and profile to use the type to open a Dataform on and (optionally) the

specific Dataform to display

An example of the Dataform applet is distributed with Sentences and can be found in the


Enterprise Edition copy the file DataformApplethtml to your Sentences Web

application directory ltSentences_homegtTomcat4webappsSentences and open it

using your Web browser If you are using the default installation of Sentences with

Tomcat the URL is as follows

httplocalhost8090SentencesDataformApplethtml

The Dataform applet


245

Figure 5-37 Example of a Dataform applet in a browser page

The Dataform is displayed as part of the HTML page as shown in Figure 5-37 and

behaves like any other Dataform If you open other Dataforms from a Dataform applet

they are displayed in separate windows

Dataform applet code example

When you create an HTML page to launch a Sentences applet such as the Dataform

applet you can use a helper javascript library that facilitates deployment on various

browser and platform combinations See ldquoSentences client configurationrdquo for details

Applet parameters for the Dataform applet

The following parameters are used by the Dataform applet in addition to the standard

ldquoSentences applet parametersrdquo


bull ServletPort

The Dataform applet attempts to connect to the Sentences servlet using the host name and






the ServletPort parameter

bull ServletContext

The Dataform applet


246

The first part of the URL required to access the servlet The default is Sentences This

parameter depends on the configuration of the servlet container being used For example

with ServletExec you would normally use ldquoservletrdquo This parameter is optional

bull Profile

The Profile parameter defines the default profile opened when the Dataform applet is

started The name of your profile must not contain any special characters that need to be

represented by escape sequences in HTML This parameter is mandatory

bull EditOption


The possible values for the Dataform applet are schema data and none


schema allows the user to edit schema queries and data



If this parameter is set to none the Dataform is read-only This optional parameter is case-

sensitive and the default is schema

bull LazyType

This parameter specifies which entity or association type to open the Dataform on The

parameter is mandatory All of the following examples are valid uses of the LazyType

parameter

ltparam name=LazyType value=Employeegt

ltparam name=LazyType value=(Employee salary Money)gt

ltparam name=LazyType value=((Person bought Car) on Date)gt

Note The LazyType parameter replaces the EntityType parameter used in Sentences

Version 20

bull LazyInstance

This is an optional parameter which specifies an instance of the specified LazyType to

open the Dataform on If it is not specified the Dataform opens as a blank create Dataform

based on the specified LazyType All of the following examples are valid uses of the

LazyInstance parameter

ltparam name=LazyInstance value=Bill Jupitergt

ltparam name=LazyInstance value=(Bill Jupiter salary20000)gt

The LazyInstance parameter is locale-sensitive so care must be taken when using it with

locale-sensitive value datatypes such as Date or Time The HTML which gives the value

of the LazyInstance parameter must be stated in a format which is valid for that datatype

in the locale of the Sentences client For example on a client running with en_GB locale

the format for a Date datatype is as follows

ltparam name= LazyInstance value=((Bill Jupiterboughtpizza) on 22012000)gt

In contrast on a client running with en_US the format for a Date datatype is as follows

ltparam name= LazyInstance value=((Bill Jupiterboughtpizza) sect

on Jan 222000)gt

Failure to use the correct format results in an error stating that the instance cannot be

found

Note The LazyInstance parameter replaces the Entity parameter used in Sentences

Version 20

The Dataform applet


247

bull LazyId

This is an optional parameter which may be used instead of the LazyInstance parameter

The LazyId parameter specifies the internal identifier of a Sentences element The

internal identifier may be useful in identifying distinct instances which share the same

name (for example where a customer list includes more than one instance named John

Smith) The format for the LazyId parameter is

ltparam name=LazyId value=12012gt

You can retrieve the internal identifiers when you run an XML Export command (see

ldquoInclude Sentences IDsrdquo )

Do not use the LazyInstance parameter and the LazyId parameter together as this

causes an error

bull EnablePickers

This parameter disables the display of picker lists in the Dataform This prevents a user

from viewing data entered by a previous user The possible values for this parameter are

Yes which allows the display of picker lists and No which disables the use of picker lists

This parameter is optional and the default value is No If you set this parameter to No to

disable the use of picker lists you can still make use of the combo box presentation

method to allow users to select from an existing list

bull SaveButtonText

This is an optional parameter that allows you to set the text on the Dataformrsquos save

button The default value for this parameter is Save (language dependent)

bull ImageURLBase





display images By default this is the Images subdirectory created in the

ltSentences_datagt location you chose during installation For more information see

ldquoAbout the ImageURLBase parameterrdquo

bull RequestSize

This optional parameter sets the number of data items retrieved from the Sentences

database for each request If more items exist Sentences displays the Morehellip prompt in

the relevant multiple association field in the Dataform If this parameter is not set the

dataform applet uses the value for the RequestSize parameter that has been set for the

Sentences client (see ldquoSentences Applet Parametersrdquo) The default value is 500

bull Dataform

This is an optional parameter that instructs the applet to use a specific custom Dataform

for the entity type or entity specified If this parameter is not specified the applet uses the

default Dataform If the value given for this parameter is the entity type name enclosed in

angle brackets for example ltPersongt the applet uses the base Dataform for the type

bull DisplayStatus

This parameter determines whether a status bar is shown when the applet is displayed

Possible values are yes and no The default value is yes

bull Border

This is an optional parameter which specifies a border decoration style on the Dataform

Possible values are line bevel etch and none The default value is none


The Picker applet


248


These two optional parameters allow you to specify the foreground and background

colours of the Dataform panel using the standard HTML hexadecimal coding for colours

The dataform controls are not affected If these parameters are not set the applet uses the

default system colours

Note Sentences accepts the American spelling of these parameters (BackgroundColor and

ForegroundColor) as well as the British spelling shown above

As an alternative to using only the BackgroundColour and ForegroundColour

parameters you can specify colours for a number of system features

The Picker applet

You can display a Sentences picker as an individual Java applet This is known as the

Picker applet and is illustrated in Figure 5-39 You can embed the Picker applet in an

HTML page on a Web server to create a customised user interface for your Sentences

database

An example of the picker applet is distributed with Sentences and can be found in the


Enterprise Edition copy the file PickerApplethtml to your Sentences Web application



follows

httplocalhost8090SentencesPickerApplethtml

The Picker applet displays a list of instances of a specified entity type or association type

from a specified profile as defined in the appletrsquos parameters

When using any of the Sentences Applets you will be asked to log in (unless anonymous

access is enabled)

The Picker applet


249

Figure 5-39 Example of Picker applet in a browser page

The picker applet is controlled by an HTML page that supplies parameters to the applet

specifying the host and profile to use and the entity or association type to open a picker

on

When you double-click on an item from the Picker applet or highlight the item and click

the Edit or the View button Sentences opens a Dataform for the selected item The

Dataform opened is a standard client dataform and not a Dataform applet

If the picker applet cannot find the profile you specify or if you specify a LazyType for

the applet that does not exist or has a duplicate in the database the applet displays an

error in the Message Log and does not run

Picker applet code example

When you create an HTML page to launch a Sentences applet such as the Picker applet



In the example of the picker applet ltSentences_homegtExamplesHTML

PickerApplethtml the instances displayed in the picker are defined by these

parameters


EditOptiondata

FixedProfileno

LazyTypeEmployee

CreateButtonyes


Borderetch

The Picker applet


250

This means the picker displays instances of the Person entity type from the Human

resources profile A create button will be included and there will be an etched border

around the applet

Applet parameters for the Picker applet

In some cases the parameters used by the Picker applet are identical to those supported by

the Dataform applet (see ldquoApplet parameters for the Dataform appletrdquo ) In other cases

there are variations in the way the parameters are used and there are also some

parameters that are unique to the Picker applet

The following parameters are used by the Picker applet in addition to these and the

standard ldquoSentences applet parametersrdquo


All the parameters used by the Picker applet are case-insensitive for both the parameter

name and the parameter value except for the value of the LazyType parameter which is

case-sensitive

The following parameters are used by the Picker applet in exactly the same way as they

are used by the Dataform applet

bull ServletPort

bull ServletContext

bull Profile

bull ImageURLBase

bull LazyType

bull Dataform

bull DisplayStatus

bull Border



The following parameters are used by the Picker applet with variations from the way they

are used for the Dataform applet

bull EditOption


The possible values for the Picker applet are data and none

Parameter Value Editing Actions Allowed



If this parameter is set to none users may only view existing values from the Picker

applet The default setting for this parameter is none

The setting of this parameter affects the display of pickers in any Dataform opened from

the Picker applet and the display of buttons on the Picker applet If the EditOption

parameter is set to none the Picker applet displays a View button and the Create and

Edit buttons are not displayed

bull EnablePickers

The Query applet


251

This parameter determines the display of picker lists in any Dataform launched from the

Picker applet The possible values for this parameter are Yes which allows the display of

picker lists and No which disables the use of picker lists

The default value is Yes unless the EditOption parameter is set to none in which case

picker list use is disabled irrespective of the setting for this parameter

The following parameters used by the Dataform applet are not supported by the Picker

applet

bull LazyInstance

bull LazyId

bull SaveButtonText

The following parameters are unique to the Picker applet

bull Picker

This parameter defines the style of picker displayed It has a similar function to the

Picker options on the Format properties page The possible values for this parameter are

Tree and List The Calendar picker is not available If this parameter is not specified

the style of picker defined for the type is used

bull ShowTitle

This parameter defines whether or not there is a title embedded at the top of the applet

The possible values are yes or no If this parameter is not supplied the default value is

yes The title displayed is the name of the type on which the Picker applet is opened

bull CreateButton

This parameter determines whether a Create button is displayed in the Picker applet

which allows users to create new instances of the displayed type The possible values for

this parameter are Yes and No The default value is Yes The Create button is not

displayed if any of the following conditions are met irrespective of the setting of this

parameter

bull the Profile opened by the Picker applet does not allow data changes

bull the EditOption parameter is set to none

bull the Picker applet is used on an association type

bull the Picker applet is used on a type which has Prohibit New Instances set

bull the Picker applet is used on a type which is a subset

bull DeleteButton

This parameter determines whether a Delete button is displayed in the Picker applet

which allows users to delete existing instances of the displayed type The possible values

for this parameter are Yes and No The default value is No

The Delete button is not displayed if the Profile opened by the Picker applet does not

allow data changes

The Query applet

You can access query results using a Java applet known as the Query applet When you

use the Query applet with a query that makes use of query parameters the applet display

which is illustrated in Figure 5-41 resembles the Query parameters dialog (see

ldquoExecuting a query which has parametersrdquo ) If the query does not makes use of query

parameters Sentences displays a dialog similar to the Query parameters dialog which

does not have any fields

The Query applet cannot be used with Set Queries

The Query applet


252

An example of the Query applet is distributed with Sentences and can be found in the


Enterprise Edition copy the file QueryApplethtml to your Sentences Web application



follows

httplocalhost8090SentencesQueryApplethtml

Figure 5-41 Example of the Query applet display for a query with parameters

You can embed the Query applet in an HTML page on a Web server to create a

customised user interface for query results from your Sentences database

To run the query select the appropriate parameter values and click OK While Sentences

executes the query it displays a Cancel button This button may not be visible if the query

is executed very quickly

By default the query results are displayed in the same way as they are if you select the

View XML results option for the same query using the XML parameters attached to the

query You cannot specify different XML parameters when running the Query Applet

The resulting data may be either XML or HTML data depending on whether the XML

parameters specify a stylesheet to be used and which kind of data such a stylesheet

generates (see ldquoView query results as XMLrdquo )

Query applet code example

When you create an HTML page to launch a Sentences applet such as the Query applet



In the example of the query applet ltSentences_homegtExamplesHTML

QueryApplethtml the instances displayed in the query applet are defined by these

parameters


LazyQueryProject resources

Bordernone




253

ColourwindowFFFFEE

ColourmenuFFFFEE





ColourcontrolDDEEFF







This means the query applet displays parameters for the Project resourtces query from

the Human resources profile There will be no border around the applet Various

colours are also set (see ldquoUsing colours in Sentences appletsrdquo)

Applet parameters for the Query applet

The following parameters used by the Dataform and Picker applets are also used by the

Query applet For more details see ldquoApplet parameters for the Dataform appletrdquo

bull Profile

bull Border

bull ServletPort

bull ServletContext

bull DisplayStatus

The following parameter is unique to the query applet

bull LazyQuery

This parameter defines the name of the query to use This parameter is mandatory The

query referred to must not be a Set Query

bull Target

This optional parameter defines the name of the browser window in which to display the

query results This parameter supports the standard HTML values for the target attribute

which are _blank (which opens a new browser window) _self (which loads the results

window into the same frame or window as the applet was in) _parent (which loads the

results window into a window or frame one level above in a frame hierarchy) _top

(which loads the results window into the top level window) or ltnamegt for a named

window

In addition to these parameters the query applet also makes use of the colour parameters

described in ldquoUsing colours in Sentences appletsrdquo


When you create the HTML pages for use with Sentences applets you may use either a

simple colour scheme using the BackgroundColour and ForegroundColour parameters

only or an advanced colour scheme which allows you to specify colours for a number of

different system features There is an example of the use of the advanced colour scheme

in the partial HTML code listing for the Dataform applet example in Figure 5-40

You must use either the BackgroundColour and ForegroundColour parameters only or

the advanced colour scheme If Sentences detects the BackgroundColour and

ForegroundColour parameters all other colour parameters are ignored



254

In both schemes you need to define colours using standard HTML hexadecimal coding If

your Web page is going to be viewed by users who have only 256-colour monitors it is

recommended that you restrict your choice of colours to the 216 nondithering colours

which are common to all browsers (the so-called ldquoWeb-safe paletterdquo)

Sentences automatically maps the colours of certain system features to your

BackgroundColour and ForegroundColour settings Sentences also calculates values for

ldquodarkerrdquo and ldquobrighterrdquo versions of these colours which are used for the highlights that

create a three-dimensional effect

The system features mapped by Sentences are shown in the following table

System Colour Usage Mapped To

Window The interior of text fields and

lists BackgroundColour

Menu The backgrounds of menus BackgroundColour

MenuText The text in menus ForegroundColour

textText Text inside text fields and

lists ForegroundColour

textHighlight

The background of selected

text (for example in a text

field)

Brighter

BackgroundColour

textHighlightText The colour of selected text

(for example in a text field)

Darker

ForegroundColour

control

The backgrounds of controls

such as buttons labels

panels and sliders

BackgroundColour

controlText The text in controls such as

buttons and labels ForegroundColour

controlHighlight

The bright edge of controls


give 3D appearance)

Brighter Background

controlLtHighlight Even brighter edge of

controls

Even Brighter

Background

controlShadow

The dark edge of controls


give 3D appearance)

Darker Background

controlDkShadow Even darker edge of

controls

Even Darker

Background

scrollbar The background of a

scrollbar (outside the slider) Brighter Background

If you wish to implement an advanced colour scheme you can create individual

parameters for each of these features

The name of the parameter is the same as the entries in the Colour column with the

addition of the prefix ldquoColourrdquo in the pattern

ltPARAM name=Colourcontrol value=FFFFFFgt

Any colours not specified retain their default values The case of the parameter name is

not significant

If any of the highlight colours such as textHighlight are not specified then its value is

derived automatically as shown in the table above



255

The following are examples of colour specifications for individual features

ltPARAM name=Colourwindow value=33CCFFgt

ltPARAM name=Colourmenu value=CC3399gt

ltPARAM name=ColourtextText value=FFCC00gt

Note Sentences accepts American spellings for these parameters (such as Colorwindow and

Colormenu) as well as the British spellings shown above


Sentences provides extensive support for XML which is emerging as the new industry

standard for data exchange The procedures you must use to export data from a Sentences

database in XML format involve the Query Editor and details are given in ldquoThe Query

Editor and XMLrdquo

You can export a Sentences schema to XML For more information see ldquoExport

Sentences schema to XMLrdquo

Further details about the use of XML with Sentences are given in Chapter 8 ldquoSentences

and XMLrdquo For security reasons some XML features are only available when you have

enabled an appropriate servlet For more details see ldquoServlet access to Sentencesrdquo

You can also import comma separated value (CSV) files into a Sentences database and

export Sentences data to a CSV files CSV files are ldquoflatrdquo data files that can be created or

read by many applications Details of the CSV Import command are given in this section

and details of CSV Export are on page 2-103

Some examples of using CSV Import and CSV Export to integrate data from Sentences

with other applications are shown in ldquoIntegration with Microsoft Office applicationsrdquo

Using triggers when you import data

Trigger information is part of the Sentences schema which is read by the import

programs When you import XML data any triggers attached to any of the types for which

data is being imported are run This means that it is possible for a trigger to interrupt an

import operation When you import CSV files you can control whether or not triggers are

executed by specifying a command line switch

In order for the import program to use a trigger the JAR files containing the triggers must

be in the directory listed in the TriggerPath property in the Serverproperties file

and the triggers must be attached to types in your schema You can use switches with the

Import command to determine whether or not triggers are run

CSV Import

CSV Import is a command line program which is run on the Sentences server when

Sentences is not running

CSV Import allows you to add data derived from other systems to a Sentences database

You can also take data from one Sentences database and import it into a different

database using a combination of the Export to CSV command and CSV Import

CSV Import only deals with data and cannot be used to create or alter a database schema

You must have your database schema in place before importing data The schema must be

saved as named profile because you need to use the profile name when you run CSV

Import

If you want to import data into a complex database schema you may need to divide your

data into a number of CSV files which should each be imported separately In this case

the order in which the files are imported becomes significant

There is a detailed example of using CSV Import in Chapter 11 ldquoWorked examplesrdquo

CSV Import cannot distinguish between existing and new instances that have identical

names and treats the new instance as an update of an existing instance In cases where



256

new instances may have the same names as existing instances you should use Sentencesrsquo

XML Import procedure (see ldquoImporting XML datardquo )

CSV Import and supertypes and subsets

If your database uses supertypes and subtypes you must import the subtype instances

before you import the supertype instances to avoid the possibility of creating duplicates

This is because every subtype instance is also an instance of the corresponding supertype

You cannot import subset instances directly as the membership of a subset is always

determined by the result of a subset query All the relevant instances must be imported as

instances of the corresponding superset Those instances which meet the criteria for

membership of the subset are displayed when the subset type is selected

The problem of duplicate instances may occur when you import a CSV export file which

was based on a subset query If you create one CSV export file for a query which selects

all the instances of a superset entity type and a separate CSV export file which selects all

instances of the Subset entity type and then import both of these files into a new profile

you may create duplicates in your new database

This is because an instance of a Subset entity type is also an instance of the superset entity

type To avoid this problem you must import the CSV export file from the subset query

first

Structure of CSV files

When you import a CSV file Sentences treats the first line of the file as a series of

column headings and tries to match the column heading to an existing entity type

Column headings must match existing entity types and may optionally contain an

association verb to specify an association type The rules that Sentences uses a for this

matching are explained below

The order of the columns in the CSV file is also significant because of the way in which

CSV Import determines the association type to which column data corresponds CSV

Import can create association instances only where an instance of the source type for the

equivalent association type has been created as a result of a preceding column in the file

CSV Import rules

For each column in the CSV file Sentences identifies an entity type and looks for the

relevant association types according to the following rules

bull The association type can be sourced on any entity type or association type identified for

an earlier column or a subset or supertype of such a type

bull The association type can be targeted on another association type provided that the last

column which contributes to the identification of the target association type is preceded

by all columns which contribute to the identification of the source type

bull The target of the association type for a column can be a subset or supertype of the entity

type identified for that column

bull You can specify an association type by including its name as part of the column

heading delimited by a colon () The association type specified must still meet the other

criteria above

bull Because the colon () character is used as a delimiter between entity type names and

association type names you cannot use a colon character in an entity type name

bull If more than one association type is suitable and you do not specify which one to use

the program produces an error message and stops

bull If a line in a CSV file ends with one or more empty fields which are not marked

by a delimiter character Sentences assumes that these fields are empty



257

Cardinality rules and triggers with CSV import

The CSV Import program does by default implement Sentencesrsquo usual checks and

constraints on association type cardinality (see ldquoCardinalityrdquo ) and does run triggers

associated with types included in an import

However you can add the [-notriggers] switch to the CSV import command line to

force the import program to ignore triggers and cardinality checks If you choose to use

the [-notriggers]switch it is possible that after running CSV Import your Sentences

database may contain multiple associations for an association type defined as singular

Running CSV Import

To import a CSV file you need to run an external command while the Sentences server is

shut down You must run the command separately for each file you want to import

You must have write access to the chapter files to which you wish to add data in order to

run CSVImport

The command you run varies according to the platform you are working on In all cases

the command relates to the Java class that controls the import procedure

comsentencesexportImportCSV

To import a CSV file on Windows platforms

The Sentences installation directory on Windows platforms includes a batch file

CSVImportbat Use this batch file to run the CSV Import procedure

1 Shut down the Sentences server and open a command window (MS-DOS window)

2 Navigate to your Sentences installation directory

3 Type in the import procedure command in the format

CSVImport [-notriggers] [-nolog] ltprofilenamegt ltfilenamegt

where

ltprofilenamegt is the name of the profile you are importing into and ltfilenamegt is the

path and name of the CSV file you want to import

[-notriggers] is an optional switch to stop CSV Import from running any triggers that

are attached to types included in the import By default Sentences runs the triggers and if

you include the -notriggers switch Sentences ignores the triggers

[-nolog] is an optional switch which stops the creation of a recovery log file Using the -

nolog switch may speed up the import process An example of CSV Import is as follows


While CSV Import is running Sentences displays a row of asterisks Each asterisk

represents 100 lines of data If you know the number of lines of data in your CSV file the

row of asterisks can indicate the progress of the import

To import a CSV file on Unix Linux platforms

The Sentences installation directory on Unix Linux platforms includes a shell script

CSVImportsh Use this shell script to run the CSV Import procedure You can run the

CSV Import procedure either from the command line or from a script file using a

command for example







258

CSV Export





allows you to sort and select data from the Sentences database before you export it The

behaviour and procedures for exporting query results are different for queries and for set

queries For more information about using the Export to CSV filehellip command see

ldquoExporting query results as CSV datardquo


Sentences V40 introduces a scheduler that runs as part of the server Several processes

can be defined in a list and scheduled to run at a specific time and date or on a regular

basis The Personal Edition does not contain the Scheduler functionality

Only one scheduled process list can be executed at a time If a second list becomes due

then it is not queued till afterwards - it is ignored

Access to the Scheduler

A Sentences User has to be granted the Scheduler Role System Administrators

automatically have this privilege See the ldquoUser security referencerdquo for details of User

Roles

Scheduled Process Lists

The Scheduler enables you to create lists of Server Processes that will be run in sequence

at a specified time and date or at regular intervals A Scheduled Process List has a name a

list of Processes and a list of Schedule Plans Each Schedule Plan describes a date and

time or regular intervals that the list of processes will be run

Each list can be temporarily disabled and records the last time they were run and the

outcome for example whether the processes could not complete due to an error

If one process in the list fails then no further items in the list are attempted

To create a Scheduled Process List follow these steps

1 In the Sentences Explorer select Server Process Scheduler from the Tools

menu

Please wait while the list of available profiles queries entity types LazyView

chapters is read from the server

2 Select Create to open a New Scheduled Process List Dialog

3 You must give the list a name

4 You can optionally disable the list by selecting the Disabled checkbox

5 Create one or more Process (see below)

6 Create one or more Schedule Plan (see below)

7 Select OK to save the new list or Cancel to discard it

Server Processes

There are five types of process that can be scheduled to run Execute Query Set Entity

Type Name Creation Seed Update Static LazyView Data Replace Data Chapter Backup

Database



259

Execute Query Process

This process executes a query or an update query in a specific profile The output can

optionally be saved

To create an Execute Query Process follow these steps


the list of Processes and select Execute Queryhellip from the sub-menu

2 Select the profile that contains the query you wish to execute and then select the

query from the two drop down lists

3 You can optionally check the Output results to file checkbox if you wish the

results to be output to a file


The output from a query will be saved to a text file in XML format The location can be

specified in the Serverproperties file but defaults to a subdirectory of the Chapters

Directory named Output Sub-directories will be created for the profile and the query

name (with inapropriate characters changed to underscores for the operating system) The

name of the output file will be the date and time when the query finished executing in the

format YYYYMMDDHHMMSSxml

Set Entity Type Name Creation Seed Process

To compliment the Automated Entity Type naming functionality the ldquoseedrdquo starting ID

can be set for a specific Entity Type in a Profile

To create a Set ET Name Creation Seed Process follow these steps


the list of Processes and select Set ET Name Creation Seed hellip from the sub-

menu

2 Select the profile that contains the entity type you wish to change and then select

the entity type from the two drop down lists

3 Enter the new seed


Only entity types that are set to automatically generate names using an ID seeded with a

starting value will be included in the drop down lists Only profiles that contain such

entity types will be listed

If the entity type generation mode is subsequently changed to not be an incremental ID

then the seed will still be set but this will have no effect

Update Static LazyView Data Process

This process is used to get the latest snapshot data for a static LazyView Mapping The

specified Profile and LazyView Chapter are used to update or replace the relational data

To create an Update Static LazyView Data Process follow these steps


the list of Processes and select Update Static LazyView Datahellip from the sub-

menu

2 Select the profile that contains the LazyView you wish to update and then select

the LazyView chapter from the two drop down lists

3 Select which of the three updates you wish to make



260

Standard Update Update the existing data with the latest additions

changes and deletions from the relational database This annotates each

instance with a timestamp so that the update history can be viewed

Incremental Update Add new data and update changes from the

relational database but do not annotates each instance with a timestamp

and do not delete old data This is faster than a Standard Update

Replace Data Delete the existing mapped relational data and re-import

the latest data This process replaces the existing Data Chapter that has

been set as the target for data changes and deletes the old one as it is

assumed that the data is transient This is the fastest process You can

optionally specify a limit to the number of rows imported from each

table


If static data is to be regularly updated then the third option is the most efficient method

It will delete the previous data chapter so any other data should be stored in a separate

chapter

Replace Data Chapter Process

This process allows the user to replace the chapter that is the target for data changes for a

specific profile The old chapter can be kept or deleted

To create a Replace Data Chapter Process follow these steps


the list of Processes and select Replace Data Chapterhellip from the sub-menu

2 Select the profile that you wish to replace the target for data changes chapter

from the drop down list

3 Optionally uncheck the Delete old chapter file checkbox if you wish to keep the

old chapter file


If the old chapter file is kept then it can be restored in the profile definition This would

enable the database to be viewed at that point in time as a kind of archive

Backup Database Process

This process starts an online backup of the database See ldquoOnline Backuprdquo for details of

how an online backup works

Schedule Plans

There are several types of schedule plan that can be added to a Scheduled Process List to

determine when the list is executed

bull Specific date and time

This is the simplest of Schedule Plans specifying a single date and time

bull Daily Recurring Plan

This Schedule Plan allows you to specify that the list should be executed every weekday

or a fixed number of days apart For example every 10 days

bull Weekly Recurring Plan


of weeks apart For example every 2 weeks You must specify which days of the week

the list should be executed Monday through to Sunday You can select any number of

days of the week from all to just one



261

bull Monthly Recurring Plan


of months apart on a specific day of the month For example every 6 months on the 3rd

of the month



Weekday] For example every last Friday of each month

bull Yearly Recurring Plan

This Schedule Plan allows you to specify that the list should be executed on a specific day

of a specific month each year



Weekday] of a specific month For example every third Tuesday of April

You must specify a time of day for all Recurring Plans If you wish to execute a list at

more than one time a day you must enter two plans one for each time

All Recurring Plans allow you to specify a Start Scheduling from date and a Stop

Scheduling after date If you do not specify a Stop Scheduling after date then the list

will continue to be scheduled indefinitely

When calculating the next Due date the Start Scheduling from date is used as a starting

date when calculating say every third day

Managing Scheduled Process Lists

The Server Process Scheduler Dialog allows you to manage the Scheduled Process Lists

You can create new lists as mentioned above You can Edit Delete and Disable the lists

You can also refresh the Inputs (available profiles Chapters Queries and Entity Types)

and the Scheduled Process Lists themselves The table shows when each list is next due to

be executed when it last executed and the outcome By Editing a Scheduled Process List

that has run you can view more details of the outcome including the start and finis times

Manually running a Scheduled Process List

The Server Process Scheduler Dialog allows you to select a Scheduled Process List and

run it immediately ndash regardless of its Schedule Plans

You can also request that the currently running Scheduled Process List be cancelled In

most cases this means that once the current process has finished the next item in the

Scheduled Process List will not be run The list will be cancelled and the outcome is

recorded as such

Viewing Scheduled Process List Progress

The list will not automatically refresh when a process is started or cancelled You must

select the Refresh Lists button to update the status of all Scheduled Process Lists

The outcome of a Scheduled Process List is not updated until execution is completed or

cancelled You can view the progress of a List that shows when each item in the list has

completed through the Statistics applet See ldquo Scheduled process statusrdquo


Advanced techniques

263

Chapter 6

Advanced techniques

This chapter looks at techniques for getting the best out of Sentences and is

designed for more advanced users The topics described in this chapter are

bull Sentences and Java technology

bull transaction processing in Sentences

bull Dataform tabbed pages with subsets and supertypes

bull target parameters

bull creating database views using profiles and chapters


Sentences makes use of Java technology and the Java Virtual Machine to achieve

platform independent operability This section is a brief introduction to the architecture of

Java programs for users who may be unfamiliar with Java More information on Java can

be obtained from the Java website

httpwwwjavacomendownloadwhatis_javajsp

The Java Runtime Environment contains two components that allow Java applets to be

run on the client machine The first component is a browser plug-in for Web browsers

such as Microsoft Internet Explorer Firefox and Chrome The plug-in allows a Java

applet to run inside the browser The second component is called Java Web Start This is a

desktop application program that also allows a Java applet to run as if it were a desktop

application The Sentences Explorer application is one such Java applet

Java programs that run on the server are known as servlets Sentences has a number of

server servlets for different purposes More information about servlets can be obtained

from the Oracle website


Figure 6-1 shows a diagrammatic representation of how the Sentences applet and servlets

communicate in the Sentences Enterprise Edition The right-hand side of the diagram

represents a client machine running a Web browser with the Java plug-in running the

Java Virtual Machine It also shows the applet running in Java Web Start

The left-hand side of the diagram represents a server machine which is running an

Application Server (for example Oracle Glassfish or IBM WebSphere) A Java

Application Server contains a Web server which requires a servlet container to run Java

servlets Some Web server programs such as Tomcat already contain a servlet container

The servlet container browser plugin and Java Web Start all perform the same purpose to

allow access to the Java Virtual Machine


Advanced techniques

264

Figure 6-1 Diagram of client and server interaction in Sentences

The Sentences applet sends requests to the SentencesServer servlet running on the

server The servlet then sends a response to the applet The communication between

server and client uses the Internet communication protocol TCPIP

The setup described here applies to the Enterprise Edition even when it has been set up in

local mode with the client and server parts of the programme actually residing on the

same physical computer The Personal Edition of Sentences however does not use a

client-server configuration and the whole program is bundled as a single application


A database transaction is generally considered to be an action or series of actions that

changes one or more items of data stored in the database Sometimes a number of related

units of information need to be changed together

The method for updating data in Sentences is divided between the client and the server

All data resides on the server and the server handles data requests from the client

Sentences is designed to work over the Internet and therefore the communication between

client and server uses Web-based protocols This means there are no persistent

connections between server and client Each client request is handled and replied to and

the connection is then closed There is no record locking on the server side

Every time a user updates information to the database the new information must be

available immediately to all other users so as to support real time applications

Sentences does not use any of the data locking or file locking techniques commonly used

in relational databases to maintain data integrity Instead requests to change the database

include a copy of the unchanged data which is used to verify that no other changes have

been made since the data being changed was sent to the client

Sentences Explorer based updates

If you change data in the explorer for example adding or deleting an entity type your

change is sent to the server as soon as you click the Create button or the Delete button

When you rename any item your change is sent to the server as soon as you press the

Enter key

All changes received by the server are processed immediately If for any reason your

change cannot be updated to the database for example if the entity type you selected as


Advanced techniques

265

the target for a new association type has been deleted by another user Sentences displays

an error message

Dataform based updates

In order to display a Dataform the Sentences client sends a data request to the server The

server searches the database and returns the requested values to the client These values

represent the state of the data on the server at that moment in time

The data returned is displayed in the Dataform When you change data on the Dataform

the Sentences client stores your changes in an update package All the

changes in a Dataform and any related child Dataforms are stored in the same package

Child Dataforms are defined in the next section When you click the Save button all your

changes are passed to the server along with the original data request and the original set

of returned values

All changes in your package are processed by the server as soon as they are received The

first action taken by the server is to reprocess the original data request and to compare the

current returned values with the stored set of returned values from the original request

Messages from multiple users are queued and are processed by the server one at a time

Any difference between these two sets of values indicates that data has been changed by

another user after your original data request was made In this case your update package

is not processed and none of your changes are updated to the database

If for any reason any one change in your package cannot be updated to the database then

none of the changes in your package are updated and Sentences displays an error

message

Updates in parent and child Dataforms

The Dataform that relates to an object shows all the associations that have that object as

their source Each association is represented by a label based on the verb of the

association and a data entry field for entering or displaying the target Dataforms opened

from the Explorer are parent Dataforms

You can display a shortcut menu on the target field and then display another Dataform by

selecting one of the Viewhellip options from the shortcut menu Dataforms opened from

other Dataforms are almost always child Dataforms (see ldquoParent Dataforms and child

Dataformsrdquo )

Any changes made on a child Dataform are regarded as part of the same transaction to

which the original parent Dataform belongs This means that changes made in a child

Dataform are not saved to the Sentences server until the original Dataform is saved

You can check whether a Dataform is a child or a parent by looking at the text on the

command buttons A child Dataform has an Apply command button On a parent

Dataform the command buttons are Save amp Reset Save amp Edit or Save

If the Sentences server does not accept a change you want to make you must refresh your

view of the server before you try and save your changes again


This section describes the original Dataform Page Layout system for Dataforms and

Custom Dataforms This system has been replaced with the more versatile Dataform

Section Layout system See the section The Sentences Dataform under Chapter 5

Workind with Sentences for details

You can use the Sentences Query Editor to create custom Dataforms Custom Dataforms

may include tabbed pages based on Page nodes that you add to your query (see ldquoPage


Advanced techniques

266

Nodesrdquo )Sentences also adds a tabbed page for any instance-specific association types

(see ldquoInstance-specific association typesrdquo )

Sentences automatically displays Dataform tabbed pages for subset or supertype

associations in any base Dataform and in any custom Dataform you create in addition to

the tabbed pages you specify using Page Nodes If Schema Pages have been created then

these will be used to create default Page Nodes

The order in which these automatically created tabbed pages appear on the base Dataform

is the same as the order of the subsets in the entity typersquos has subsets folder in the

Sentences Explorer schema pane You can change the order of the subsets in this folder

by using drag-and-drop and this changes the order in which the Dataform subset tabs are

displayed

The following sections show some examples of how using subsets and supertypes affects

the appearance of your Dataform

Figure 6-2 The Fivestar Garage application Sentences Explorer view

Figure 6-2 shows the Sentences Explorer schema and data panes for a fictional garage

application The database for this application uses a number of examples of supertypes

and subsets The entity types Employee and Customer both use the entity type Person

as their supertype

Dataform appearance with Supertypes

In this fictional garage application the entity type Person is the source of a number of

association types The Prohibit new instances property has been set for Person so you

cannot create new instances of this type However all the instances of Employee and of

Customer are also instances of Person All the instances of Employee and of

Customer are displayed in the data pane when you select Person in the schema pane


Advanced techniques

267

Figure 6-3 Dataform on instance of customer showing Person page

Figure 6-4 Dataform on instance of employee showing Person page

Figure 6-3 shows a Dataform on an instance of Customer showing the Person page and

Figure 6-4 shows a Dataform on an instance of Employee also showing the Person

page The associations types displayed in each case are identical as both Dataforms are

showing the association types that have Person as their source

Figure 6-5 Dataform on instance of Customer showing Customer page


Advanced techniques

268

Figure 6-6 Dataform on instance of Employee showing Employee page

Figure 6-5 and Figure 6-6 are not the same as Figure 6-5 shows only the association

types that have Customer as their source and Figure 6-6 shows only the association

types that have Employee as their source

The Fivestar Garage application uses an entity type called Job This is the supertype for

Bodyshop and Workshop entity types Figure 6-7 and Figure 6-8 show the Dataform

tabs for Workshop and Bodyshop which reflect the different arrangements of data for

jobs 1001 and 1004 displayed in Figure 6-2

Figure 6-7 Dataform on instance of a Job showing Workshop page


Advanced techniques

269

Figure 6-8 Dataform on instance of a Job showing Bodyshop page

Dataform example with Subsets

One of the association types that is sourced on Job refers to the jobrsquos status The possible

values for this association are A = Waiting B = Started and C = Finished

The application includes three subset entity types named Waiting jobs Started jobs and

Finished jobs Subset entity types are shown with yellow icons in the schema pane

These types have been modelled as subsets of Job because they represent the status of a

particular job which changes from time to time The subset query for each subset checks

the value of the Status association In each query the association node is bound to the

appropriate instance

Figure 6-9 shows the subset query for the Waiting jobs subset For more information on

using queries see Chapter 7 ldquoSentences queriesrdquo

Figure 6-9 The subset query for the Waiting jobs subset

The Finished jobs entity type is the source of an association type invoice which only

applies to finished jobs As Finished jobs is the source of an association type the

Dataform creates a separate tabbed page with the subset name as its title which can be

seen in the Dataform for Job 1004

Target parameters

Advanced techniques

270

Figure 6-10 Dataform for job 1004 showing the Finished Job page

There are no tabs for Waiting jobs and Started jobs as neither of these is the source of

an association type However when you open a Dataform for a job with a different status

and which therefore belongs to a different subset the Finished jobs page is still present

on the Dataform This is because Waiting jobs and Started jobs are subsets of the same

entity type that Finished jobs is a subset of

Figure 6-11 Dataform for job 1001 showing the Finished Job page in background

Any mandatory associations that have a subset as their source are considered optional

when an entity is not a member of the subset

Target parameters

When you create an association in the Dataform you can select a target from a picker list

Generally the picker list displays all the available instances of the target association or

entity type The Target Parameters feature allows you to constrain the available targets

for a particular association to a subset of the target relative to the associationrsquos source If

the associationrsquos source is itself an association the constraining subset may be relative to

its source

Target parameters

Advanced techniques

271

Conference room example

The following conference room example uses a constraining parameter based on a subset

of an associationrsquos source It demonstrates how an events organiser who is planning a

number of conferences simultaneously might restrict the picker list for conference session

rooms to those rooms belonging to the conference hotel Rather than setting up individual

static queries for each conference or each hotel the Target Parameters feature allows

the creation of a single dynamic solution

Figure 6-12 Part of a conference planning application

Figure 6-12 shows part of conference planning application displaying associations

of the type Hotel has room Room for two hotels each with three rooms In order to

use the Target Parameters feature the database for this application also includes a

subset of Room called Hotel has room The association type that defines the room

allocation for each session uses the subset as its target Session name in room

Hotel has room

Target parameters

Advanced techniques

272

Figure 6-13 Subset query for Hotel has room

Figure 6-13 shows the subset query for Hotel has room The association (room of

Hotel) has been added and has been marked as Required (shown with an asterisk) Hotel

has been added to the Parameters folder so that it can be used to restrict the results of the

query to those rooms in a particular hotel

Note In Set queries there is an additional parameter which appears first in the parameters list

This parameter (in this example it would be named Room) is the automatically created subset

parameter query which must not be altered or removed

Figure 6-14 Hotel selected but unrestricted choices


before setting Target Parameters All six rooms are shown in the picker list even

though some of them are not in the Hotel that has been selected

Target parameters

Advanced techniques

273

Figure 6-15 Setting the Target parameter restrictions

To restrict the available targets for this association type open the Properties dialog and

select the Target Parameters tabbed page All the parameters of the subset query are

displayed Sentences looks for other association types that share the same source (in this

case Session name) and that have targets of the same type as the restricting parameter

already added to the subset query (in this case Hotel) In our example shown in Figure 6-

15 the association type Session name in hotel Hotel is displayed To enforce the

restriction select this association type in the Values taken from field To clear the

restriction select (not bound)

Figure 6-16 Hotel selected restricted choices


after setting Target Parameters Only the three rooms that belong to the hotel named in

the in hotel association are shown in the picker list

Target parameters

Advanced techniques

274

Allowed products example

You could construct a database schema that allowed you to select a constraining

parameter from an association that was a second or third level parent of the association

you wished to restrict The following allowed products example uses a constraining

parameter based on as subset of the source of the source of an association

In the allowed products schema shown in the diagram in Figure 6-17 represents a

situation in which a customer of a store may only buy products of a certain food type

This could be due for example to dietary restriction based on medical grounds

Figure 6-17 Allowed products schema

The constrained association is a nested one (Person customer of Store) buys

Allowed product) The constraint on the target is shown in the diagram by a thick arrow

and is based on an association with the source Person

Figure 6-18 Target parameters dialog for the buys Allowed product association

The Target parameters page of the Properties dialog for the buys Allowed product

association is shown in Figure 6-18

It would be possible to construct a schema in which the constraint is based on an

association source at a more distant level of nesting


Advanced techniques

275

Limitations of the Target Parameters mechanism

As illustrated by the above examples the Target Parameters mechanism can constrain the

allowed instances of an association type for a particular source This is achieved by

selecting a subset as the target type for the association type to be constrained and binding

a parameter for that subset to a schema node associated with the source

To be useful with the Target Parameters mechanism the subsets membership must be

defined by a query The query must have a parameter which when an instance is assigned

to it limits the results of the subset All parameters have a defined type To apply the

constraint the parameter must be associated with a schema node of the same type which

becomes the constraining node That node must be associated with the source of the

constrained association type by a single valued path through the schema This association

is the target parameter binding created on the Target Parameters page of the association

types properties

The following restrictions apply to the Target Parameters mechanism When attempting to

use the mechanism these restrictions may be manifested either by the desired constraining

node not being available in the Values taken from selection list or by the available

association targets being unconstrained

There are limitations on the possible paths through the schema which can link the source

of the constrained association type to the constraining node The potential constraining

nodes are defined as a set of source types contributing to the definition of the constrained

association types source and the set of targets of singular association types sourced from

those source types Specifically they are

bull the source itself

bull if the source is an association type then its source and iteratively all types along the

path of source types through the schema including but limited to when an entity type is

reached

bull the target of any association which has any of the above sources as its source provided

that the associations type is defined as singular

In addition

bull the subset parameter and the constraining node must have the same base type bull target

parameters do not work where the constrained association type uses the Combo

Checkbox or Radio button presentations

bull as queries are evaluated on the server when data has been changed on a Dataform but

not saved that change cannot affect the result of a subset evaluation including for a target

parameters constraint This is the case even where the changed data and constrained

association are on the same dataform


There are many situations in which it is useful to allow different groups of users access to

different parts of a database For example in a Human Resources application you might

want to enable all users on an Intranet to find the department phone number and physical

location of their co-workers while making sure that sensitive salary information was only

available to the small number of staff who dealt with payroll matters

In Sentences you can achieve this result by creating one profile for payroll staff and a

separate profile for all other staff These profiles would share some but not all their

chapters The following example illustrates how this is done

Database views example

A Sentences profile includes one or more chapter files which contain the schema query

and data information that make up a database However Sentences only displays entity


Advanced techniques

276

and association instances if their entity types and association types are present in the

profile

Two further rules about the use of profiles are important in this context

bull Users can only change those parts of the database for which a changes chapter is

defined in their profile (see ldquoUsing the Edit Profile dialogrdquo )

bull Users are unable to change their profiles and therefore unable to change what they can

view if the FixedProfile parameter is set to yes (see ldquoSentences Applet Parametersrdquo)

The following table shows the combination of chapters for the two profiles Staff list and

Staff Salaries

Profile Available Chapters Changes Chapter

Staff List

Staff Schema No



Staff Salaries

Staff salaries schema Yes - schema changes

Staff schema No



The Edit profile dialog for the Staff list profile is shown in Figure 6-19

Figure 6-19 The Edit profile dialog for the Staff list profile

Users of the Staff list profile may change data and change queries but they may not

change the schema as there is no Schema changes chapter defined in this profile

The Edit profile dialog for the Staff salaries profile is shown in Figure 6-20


Advanced techniques

277

Figure 6-20 The Edit profile dialog for the Staff Salaries profile

Users of the Staff salaries profile may make changes to schema data and queries as

there are three changes chapters defined in their profile One of the chapters in the Staff

salaries profile is staff salaries schema which includes the association type Person

salary Salary

Users of the Staff salaries profile see a Dataform that includes a Salary field

The file staff salaries schema is not present in the Staff list profile and as a result the

salary association type is not visible to users of Staff list profile

Users of the Staff List profile see a Dataform that does not include a Salary field


A Candidate List is a specialised kind of Dataform table that has been configured to allow

the user to select items from a pre-populated list of candidates There are two kinds of

Candidate list Item Candidates and Value Candidates

Item Candidates

Item candidate lists can be used to make the selection of a finite number of targets simple

for the end user In the Human resources example each Group Company can have

several locations In the example below a custom dataform has been created so that the

user can check the locations for a particular Group Company


Advanced techniques

278

Figure 6-22 Dataform showing an Item Candidate list

The query in Figure 6-22 has had the (Group company location Location) forward

request properties edited to change the Candidate list type to ldquoCreate Item Candidatesrdquo so

that the list of all locations is displayed and those already selected are checked This is

equivalent to changing the presentation to Checkbox but has the convenience of the Select

All checkbox

Value Candidates

With Value candidates the user can allocate amounts from one set of associations to

another within a set of constraints The example for which this functionality was created

was Cash Allocation a common requirement in many accounting applications

The Cash Allocation scenario can be modeled in several ways Here we demonstrate

schema created so that a Customer has a list of Receipts Invoices and Credit Notes

As they receive Reciepts they wish to allocate them to Invoices with an outstanding

balance The amounts can be wholly or partly allocated to one or more Invoice


Advanced techniques

279

Figure 6-23 Cash Allocation Schema

Once the Receipts amounts have been wholly allocated then they can be hidden

Similarly Invoices with no outstanding balance can also be hidden

For the schema shown in Figure 6-23 we create a Custom Dataform and edit the

properties of the (Customer this customer Invoice) forward association to change the

Candidate list type to ldquoCreate Value Candidatesrdquo The custom dataform query and

properties dialog are shown in figures 6-24 and 6-25 respectively


Advanced techniques

280

Figure 6-25 Cash Allocation custom dataform query

The custom dataform will show Receipts Invoices and Credit notes Figure 6-25 shows

how the child dataform for a Receipt will include the Receipt number the date the value

an ldquoallocated tordquo candidate list table the sum of allocated values to date the outstanding

balance and the status The Status is a derived field that either has the value ldquoFulfilledrdquo or

ldquoOutstandingrdquo to indicate whether the receiptrsquos value has all been allocated to invoices


Advanced techniques

281

Figure 6-26 Cash Allocation ldquoallocated tordquo properties

The Candidate list for Value candidates requires three properties to be set

bull The Association Type that holds the Input Value

bull The Association Type that holds the Outstanding Value

bull The Association Type to allocate values to

In Figure 6-26 the input value is the value of the receipt The outstanding value could

simply be each invoice value but in this case the invoice may be subject to a discount or

a credit note so we have created a derived type to calculate the outstanding value after

any such discount or credit has been subtracted The Allocation Value association type is

the allocated values association type Instances of this type will be created to fulfill the

invoice

Figure 6-27 Cash Allocation custom dataform


Advanced techniques

282

Figure 6-28 Cash Allocation custom dataform child

Figure 6-28 shows the child dataform containing the Candidate List for invoices The

invoices that appear in the list are determind by the query only those with an outstanding

value

Figure 6-29 Cash Allocation custom dataform child - allocated

Figure 6-29 shows after the Allocate button has been clicked The remaining pound10 has been

allocated to the first invoice on the list and the total balance and status of the receipt have

been updated

The button text ldquoAllocaterdquo on the candidate list button can be changed in the properties of

the candidate list See ldquoAssognment verbrdquo in Figure 6-26

If you manually change the allocated values then two errors may arise Firstly a value

greater than the candidates outstanding value is entered then the allocation will be

highlighted Secondly if the total allocated values are greater than the input value to be

allocated then an error message is shown Changes cannot be applied until this is

resolved


Advanced techniques

283


Whilst a Custom Dataform query allows you to limit the contents of lists and tables

sometimes you wish to dynamically change how the contents are limited rather than use a

different Custom Dataform for different contents

The Candidate List in the previous section is a good example where you only usually

desire to see outstanding Invoices and Receipts but sometimes you may wish to see all or

say the most recent for the last few months

Dataform Filters can be set on columns so that the user can choose one value More than

one filter can be used at the same time to limit the contents Usually a column with only a

few values is a good candidate for filtering a status or a type with a small number of

values such as ldquosmallrdquo ldquomediumrdquo ldquolargerdquo or 0-50 50-100 100-

A filtered column will display a filter symbol in the query definition The filter properties

also allow you to specify a default value or instance

As well as the possible values the filter list will contain Show All and Show Empty

options Show All will show all rows as if no filter is in place Show Empty will only

include rows where the value is blank or void

Limitations

Data is normally fetched in pages rather than all at once Filters are only intended to be

used on relatively small numbers of items (a few thousand) because every possible value

has to be obtained before displaying the table


LazyView functionality allows you to combine disparate data sources from Relational

Databases and Spreadsheets The Server Text Document functionality complements this

ability by allowing you to import plain text from plain text documents and Adobe

Portable Document Files (PDFs)

To facilitate this a directory on the server is used to store these text documents This is

specified in the Server properties with the property TextDocumentPath

To view Server Text Documents follow these steps


Advanced techniques

284

1 In the Sentences Explorer select Server Text Documentshellip from the Tools

menu

When the dialog opens the directory on the server will be scanned for any

changes to the contents See Figure 6-30

2 You can manually refresh the list by clicking on the Refreshhellip button

Figure 6-30 Server Text Documents Dialog

The table shows the file names the date they were last modified and their size The last

column shows the status when the file is being read and imported into Sentences The

tooltip shows additional information about PDF files such as the number of pages

You can open a Dataform to show the full details by clicking on the Open Dataformhellip

button

Figure 6-31 Server Text Document Dataform

To open the original text or PDF document click on the Open Documenthellip button

Configuration

As can be seen in Figure 3-31 the original document is stored on the Server and a context

has been added to the Tomcat webserver TextForSentences so that clients can access

the original documents This web context is set up differently for each kind of Web

server Sentences has another context for Images ImagesForSentences In the Tomcat

test server that is installed with Sentences by default these contexts are specified in the

serverxml file

The schema that stores this information is hidden by default A Specialist Schema folder

can be included that contains the schema so that it can be included in queries To make

the Specialist Schema folder visible follow these steps

1 In the Sentences Explorer select Preferences hellip from the View menu


Advanced techniques

285

2 Select the Schema Pane tab

3 Scroll down to the checkbox labelled ldquoInclude the specialist schema folderrdquo and

select it

4 Click OK to save the preferences

When the dialog closes an additional Specialist Schema folder will appear in the schema

pane This folder will also be present in the schema pane of each Query Editor


Sentences queries

287

Chapter 7

Sentences queries

This chapter describes how to work with the Sentences Query Editor which is based

on the associative model of data The user interface for the Query Editor is described

in Chapter 4 ldquoThe Sentences Quick Tourrdquo

Note The Query Editor used in Sentences Version 1 is now referred to as the Set

Query Editor If you need information about using set queries and the Set Query

Editor please contact supportsentencescom


bull creating database queries including the use of expressions

bull the Query Editor and Dataforms

bull the Query Editor and XML

bull exporting query results


Relational databases are based on tables and relational query processors such as SQL are

based on tables and operations on tables Associative databases such as Sentences use

trees rather than tables to display their schema and data as described in the section ldquoTree

displays in the Sentences Explorerrdquo The Sentences Query Editor is based on the

Associative Model of data and uses trees and operations on trees

The Sentences Query Editor can be used to interrogate the database and also allows you

to make calculations based on the data in your results Another use of the Query Editor is

to create customised dataforms from your queries The custom Dataform displays only

those associations that are present in the query (see ldquoThe Query Editor and Dataformsrdquo )

The Query Editor is also central to Sentencesrsquo XML strategy The structure of a Sentences

query can be saved as an XML document type definition (DTD) and the results of a

Sentences query can be exported as an XML document You can use the DTD you create

from a query to build XML structures that can be used to format data created by external

applications for import into Sentences (see ldquoThe Query Editor and XMLrdquo ) You can use

XSL Stylesheets to format XML output for presentation as HTML in a Web browser

Sentences can generate an XSL stylesheet from a query according to options you select

(see ldquoXSL Stylesheet optionsrdquo )

More information on the ways in which you can use XML including how to use XML to

import data into a Sentences database is given in Chapter 8 ldquoSentences and XMLrdquo

New in version 4

Version 40 introduces new functionality to the Request Queries There are specialised

versions of queries used in the new Business Rules functions and some extensions to the

functionality that have already been covered

bull Effector Queries

Effector Queries can now produce actions such as creating or deleting data and sending

simple emails See the section on Effector Queries for details

bull Update Queries

Update Queries are similar to Effector Queries but can be executed outside the context of

Business Rules See the section on Update Queries for details


Sentences queries

288

bull Predicate Queries

Predicate Queries are a special kind of query used to define the logic that determines

which State an instance is in for a given Domain See the section on Predicate Queries for

details

bull Display Name Queries

Display Name Queries are a new use for standard queries to produce a friendlier display

name for data in the Sentences Explorer and Dataforms See the section on Display Name

Queries for details

bull State Requests

The ability to request the current state of an instance in a query is covered in the section


bull Grouping Requests

An additional filtering node has been introduced that allows you to specify how to group

results This ability covered in the section Using states in regular queries and dataforms

The Request Editor now includes a Validate Expressions menu option under the Query

menu This validates all expressions in the query which may be useful when composing

Effector Queries that you cannot execute in the Query Editor

The next sections cover the other enhancements to Sentences Queries

bull Specific Derived Type Targets

The type of a Derived Types target can now be specified so that further request nodes can

be added to it

bull Additional Expression Capabilities

New functionality such as new logical constructs and new datatype functions have been

added Datatype Functions no longer have to be prefixed with the Datatype name unless

there is an ambiguity and you need to be more specific For example You do not need to

specify TextTrim(Name) and can simply use Trim(Name) but by default the function

Now() will return todayrsquos Date If you require a Timestamp then you would need to

qualify the function as TimestampNow()

bull The Expression and Function Editors

New editors to assist in the creation and editing of query expressions

Starting the Query Editor

You can start the Query Editor to create a new query or to edit an existing query

Availability of the Query Editor

You can edit an existing query or create a new query in any profile When you create a

query you can change any of the elements in it execute the query and view the results

and export the query and the query structure

Creating a new query

To create a new query select Create Query from the Query menu or highlight the

Queries folder and select Create Query from the shortcut menu

In the Create Query dialog type in a name for your query and click Create Sentences

displays the Query Editor


Sentences queries

289

Editing an existing query

To edit an existing query highlight the name of the query in the Queries folder in the

Sentences Explorer and select Edit Query from the shortcut menu or from the Query

menu or click the Properties button on the toolbar Sentences displays the Query Editor

If a profile is available to more than one user any user may edit a query It is possible that

two users may edit the same query independently and changes made by another user

might be overwritten when the query is saved

Saving a query

Sentences does not save queries automatically If you want to keep your query you must

save it before you close the Query Editor

You can save a query only if the current profile has a chapter defined as the Query

changes chapter in the Edit Profile dialog For more information see ldquoThe Edit Profile

dialogrdquo

The setting of the EditOption parameter also controls whether or not you may save a

query If this parameter is set to schema or query you may save queries but if it is set

to data or none you may not save queries

To save a query select Save Query from the Query menu or click the Save button on the

toolbar When you close the Query Editor Sentences prompts you to save any unsaved

changes in your query

The Query Editor window

The Query Editor window is shown in Figure 7-1 The Query Editor window has three

panes The right-hand pane is the schema pane and displays schema elements When you

start a new query the whole of the schema tree is displayed After you start building your

query the Query Editor schema pane displays only those types that could be used at the

currently selected query node

The top left-hand pane shows the nodes in the query data request tree and the lower left-

hand pane shows the query results

The Results Pane can display Inactive instance in the results if the checkbox is selected

For details of inactive instances see ldquoInactive instancesrdquo

Figure 7-1 The Query Editor


Sentences queries

290

General query properties dialog

The General query Properties dialog applies to the query as a whole This dialog shares

a display with the XML Properties dialog described in the section ldquoXML properties

dialogrdquo Values set for the XML Properties dialog are defaults for the query and can be

over-ridden when a query is executed

To view the dialog select Properties from the Query menu

Figure 7-2 The Query General properties dialog

Include query parameters in results

When the query is executed the query parameters that were chosen will be included in the

results They will be included whether run in Sentences or exported as XML

Automatically refresh custom dataform fields

Dataforms have an ldquoauto-refreshrdquo facility where calculations are updated whenever the

user changes any fields This property allows you to set whether ldquoauto-refreshrdquo is on or

off by default

Description

You can enter a text description for the query

Database queries

The Sentences Query Editor like the Sentences Explorer uses a tree-shaped structure A

Sentences query takes the form of a request tree made up of request nodes which

represent associations and entities you choose as well as sorting and selection nodes and

derived type nodes and derivations used for calculations

Building the request tree

When you create a new query Sentences displays a blank Query Editor You must select a

suitable starting point for your query which is known as the data request node You then

select other nodes one step at a time and build a ldquopathrdquo through the schema until you

have all the data needed for your query


Sentences queries

291

Figure 7-3 An empty Query Editor for a new query

Creating the data request node

When you create a new query Sentences displays an empty Query Editor as shown in

Figure 7-3 To create the data request node select an entity type or association type and

drag it over the ltEmpty Querygt placeholder to form the root of the request tree as

shown in Figure 7-4 Alternatively you may use Copy and Paste commands (with the

toolbar buttons or menu commands or standard shortcut keys)

Figure 7-4 Adding the data request node

The data request node is the starting point of the query and all the other information in the

query is relative to it The data request node can be an entity type or a forward or an

inverse association type The direction of the association type (forward or inverse) is

maintained in the data request node

Changing the data request node type

When prototyping you may create a new query based on one type and subsequently

realise that it should have been based on a related type a subtype supertype superset or

subset You can change the Data Request schema type to a related type by selecting the

Change Typehellip menu item from the edit menu or the popup menu


Sentences queries

292

Adding Forward and Inverse Nodes

You can add any number of forward and inverse nodes to the data request node as long as

the source (or target) of the association type is equivalent to the data request node You

can add associations that relate to the data request node or to subsets or supertypes of the

data request node or to equivalent types

You can add more forward or inverse nodes to the data request node or to any other node

and you are only limited by the available schema You may add child nodes based on

superset or subtype associations as if they were associations of the current parent node

If you add an inverse node where its source is itself an association type then all nodes

required for that association type are added to the request tree

To add a node drag the node from the schema pane and drop it on a node in the query If

the source or target of the new node matches the existing node then the new node is

added as a child of the existing node

To add multiple nodes highlight a node in the request tree and select Associations from

the Add submenu of the Edit menu or from the shortcut menu as shown in Figure 7-5

Figure 7-5 Using the shortcut menu to add associations

The following options are available for adding associations

bull Associations

displays the Add Associations dialog

bull Instance Specific Associations

adds all the instance specific associations This option is only enabled if the current

node is bound to an instance If no instance-specific associations exist for an

instance Sentences displays an error message if this option is selected

The Add Associations dialog shown in Figure 7-6 lists all the possible associations that

may be linked to the node selected in the Query Editor

You can control the associations displayed in this dialog by selecting one or both of the

Forward and Inverse check boxes

To select an association click on it with your mouse You can use Shift+click and

Ctrl+click to select multiple adjacent or non-adjacent associations

You may automatically add page nodes for the selected associations by selecting the Add

page nodes checkbox If this box is checked a page node is added whenever the

association to be added has a source type that is different from the selected node


Sentences queries

293

After selecting the associations you wish to add to the query node click Add To return to

the Query Editor without adding associations click Cancel

Figure 7-6 The Add Associations dialog

An illustration of the result of adding Associations is shown in Figure 7-7

Figure 7-7 A data request node with forward Associations added

The associations added in the example shown in Figure 7-7 are grouped into pages for

each supertype equivalent type and subset Associations from the data request node type

are not put on a page (see ldquoPage Nodesrdquo )

Using drag and drop and cut copy and paste in the Query Editor

You can use the standard drag and drop and copy and paste mechanisms in the Query

Editor to create forward and inverse nodes to create Parameters to copy or move nodes

to bind nodes and to place nodes for display purposes on defined page nodes

If you drag and drop a request node onto one of its siblings (another node in the query that

has the same parent node) the order of the siblings is changed to place the dragged node

before the node it was dropped onto This also applies when you drag a Page node and

drop it onto another Page node

If you drag a request node that is not a Page node and drop it onto a sibling Page node

the dragged node is placed on that Page

If you drag and drop an association type onto an existing request node Sentences creates

a forward or inverse request node if its source or target matches


Sentences queries

294

If you drag and drop an entity or association type onto the Parameters folder then a new

Parameter of that type is created with the type name If you drag and drop a data instance

onto the Parameters folder then it is used as the default value

You can use the standard drag and drop and copy and paste to reorder nodes at the same

level in the tree or to copy or move them to another part of the tree

If you drag and drop an existing request node onto another request node of a related type

(such as a superset or subtype) the branches of the request nodes are merged

This means that the child nodes of the dragged node are copied iteratively onto therequest

node onto which it was dropped Only one Sort node is allowed at any one level of the

data request tree If the merging of branches were to result in a duplication of Sort nodes

then the Sort node being dragged is ignored and not copied

Result Trees

The result of a Sentences query is a tree of entity and association instances When you

execute a query the Sentences query processor retrieves instances of the entity type or

association type corresponding to the data request and processes each one For each

instance it processes the query processor looks at the immediate child nodes of the data

request and uses each one to retrieve a set of association instances which it adds to the

growing result tree For each instance that it adds it looks at the children of the

corresponding request nodes and adds further sets of association instances This recursive

process is carried out to any depth required The result is a tree of data whose shape is

derived from but not identical to the request tree

The root node of the result tree is not shown in the query result tree Each request node

generates one or more sets of result nodes each result node is derived from one and only

one request node The result tree can be displayed in the Sentences Explorer or in the

Query Editor

Displaying query results

To display the results in the Query Editor click the Execute button on the toolbar or select

Execute Query from the Results menu When query results are displayed in the Query

Editor results pane the instances are shown with green icons rather than with the cyan

icons used for data instances in the Explorer

Figure 7-8 Results displayed in the Query Editor

In the example shown in Figure 7-8 the data request has the root node Employee and

the child nodes address home telephone and work telephone The results pane


Sentences queries

295

shows a list of employees and the corresponding association instances for address and

home telephone for each employee

If there are no results that match the query request Sentences displays the message No

results match your query

You can display a Dataform for a query result instance in the Query Editor Highlight the

instance and click the Default Dataform button on the tool bar or select Default

Dataform from the shortcut menu


When you execute a query you request data from the Sentences server and after

evaluating the query Sentences returns a number of data items up to the limit specified in

the RequestSize parameter (see ldquoAdditional optional parametersrdquo ) Occasionally this data

retrieval action may take a long time for example because the query is very complex or

because the RequestSize parameter is set to a high value




The Stop button is available in the Sentences Explorer and in the Query Editor You can

only stop a data retrieval action by using the Stop button in the same window that started

it You cannot for example use the Stop button in the Explorer to stop a data retrieval

action started in the Query Editor

Displaying query results in the Sentences Explorer

You can execute a query in the Sentences Explorer by highlighting the query name and

selecting Execute Query from the Query menu or from the shortcut menu The query

results are displayed in the data pane

You can also execute a selected query by selecting Reload Data from the File menu or

clicking the Reload Data button on the toolbar or by pressing F5

Although the top level of the displayed query results may resemble a list of entity or

association instances remember that the only nodes shown in the query result tree are

those that correspond to nodes in the data request tree The query may include conditions

that result in only certain instances being displayed in the query result This means that

the results tree of instances is likely to be different from the data tree of instances for the

same schema type

When query results are displayed in the Sentences Explorer data pane the instances are

shown with green icons rather than with the cyan icons used for data instances

You can display a Dataform for a query result instance in the Sentences Explorer

Highlight the instance and click the Default Dataform button on the tool bar or select

Default Dataform from the shortcut menu

The query results can include the query parameters that were chosen for this execution

To include parameters in the results check the box ldquoinclude query parameters in resultsrdquo

in the General tab of the Query Properties The parameters will be output to the Query

Editor Sentences Explorer and XML or CSV outputs

Expanding and Collapsing

The query result tree includes expand node and collapse node buttons which act in the

same way as the equivalent menu commands in the Sentences Explorer


Sentences queries

296

Binding Nodes

The Sentences Query processor returns all the instances of the type that the data request

node refers to and builds a branch of the result tree from each one

You can limit the amount of data returned by the query processor by defining a restriction

on a particular node The restriction you define limits the results returned for the node to

one specified instance and is known as binding a node

If you have a multiple association and bind the results to a particular instance Sentences

still regards the association as multiple for the purposes of calculations in expressions

There are three ways to bind a request node You can bind a node

bull to an entity or association instance

bull to another request node

bull to a parameter

Binding to an instance

You may bind any type node in your request tree to an instance which limits your results

to those that refer to that instance

If you bind the data request node Sentences builds a result tree with only a single main

branch based on the instance specified

If you bind any other request node the results for that node are limited to the specified

instance The results for the immediate parent node are also limited to that instance if the

bound request node is a source or target request

If you want to display only those nodes that are bound to the instance you specify define

the parent node of that instance as Required

If a source or target request node is bound to an instance its parent request may still

produce more than one result as there may be more than one association between the

same source and target

To bind a node to an instance

To bind a node to an instance highlight the node and select Bind to instance from the


select Bind to instance Sentences displays a picker list showing the available instances

Alternatively you may use drag and drop to bind a query node to an instance If you drag

an instance from the Query Editor results pane or from the Explorer data pane and drop it

onto a request node of the same type Sentences binds the request node to that instance

To cancel binding to an instance highlight the node and select Clear instance binding

from the Edit menu You can also open the shortcut menu select the Edit submenu and

then select Clear instance binding

The example shown in Figure 7-9 shows the node Hyperlink bound to the instance

johnatkinssleepysoftcom The parent node is also designated as a required node

(indicated by an asterisk) The results pane shows the only instance of employee that has

the specified Hyperlink


Sentences queries

297

Figure 7-9 Request node bound to an instance

Binding to a Request Node

In some queries a parent node may have a child or descendant node that is an inverse

association type that has a source that is of the same type as the parent node The result

tree for this query would have a separate branch for each instance of the parent node but

the inverse association type node would return instances relevant to all the instances of

the type not just those for the current instance of the parent node To prevent this from

happening you can bind the later occurrence of the type to the first occurrence in the

parent or ancestor node This ensures that the results in a specific branch are related only

to the defining instance of the parent node for that branch

To bind a node to a request node

To bind a node to a request node highlight the node and select Bind to node from the


select Bind to node Sentences displays a picker tree and only allows you to select one of

the appropriate nodes for the binding action

To cancel binding to a node highlight the node and select Clear node binding from the


select Clear node binding

Binding to a Parameter

If you create a parameter that has the same name as one of the nodes in your query

request tree the node is automatically bound to the parameter When you execute the

query the effect of binding to a parameter is the same as binding to an instance For more

details on using parameters in queries see ldquoQuery Parametersrdquo If two or more nodes

have the same name they are all bound to the parameter and therefore you may want to

rename one or more of the nodes before binding to a parameter

Selection Sort and Derived type nodes

You can modify the results returned by a query by adding additional nodes to the query

tree These nodes can

bull specify calculations to be carried out using the query results (a derived type node or a

derivation) These are discussed separately in the section ldquoDerived types and derivationsrdquo

bull restrict the results returned by another request node by applying a filter condition (a

selection node)

bull cause the results returned by another request node to be sorted (a sort node) Every

operator request has an expression associated with it which defines the calculation or


Sentences queries

298

filtering to be carried out An operator request affects the results generated by its

immediate parent

Figure 7-10 Query showing sort selection and derived type nodes

Selection nodes

A selection node acts as a filter on its parent node The selection node has an expression

associated with it which represents a condition that must be true for each instance to be

returned

As shown above you can also select data in a query by binding one or more nodes (see

ldquoBinding Nodesrdquo ) When using a large database if you expect the majority of instances

being filtered to match your selection criteria using a selection node should produce

faster results If you expect only a minority of instances to match your criteria then

binding to a node with the Required property set should produce faster results You may

need to experiment to find the best solution for your requirements

To create a selection node

1 Highlight the node and select Selection from the Add submenu of the Edit menu or the

shortcut menu

Sentences adds a Selection node with an attached expression node as shown in Figure 7-

10

2 The selection node is automatically selected and available for editing Add the the

expression for your selection criteria For more details about expressions see ldquoUsing

expressions in queriesrdquo

To edit the selection expression on other occasions select Edit Expression from the

shortcut menu for the expression node

Note Selection nodes do not appear in results and cannot be referenced and therefore

they do not have names and cannot be named or renamed

To delete a selection node

1 Highlight the node and select Delete from the Edit menu or click the Delete button on

the toolbar

An example of a Selection node is the ldquoSelectionDatelt=DateNow()rdquo node shown

in Figure 7-10 This is part of the Latest Salaries query in the Human resources

example application In this example salaries are selected by dates in the expression


Sentences queries

299

Datelt=DateNow() which uses a Date datatype method Now() There is more

information on expressions and datatype methods later in this chapter (see ldquoUsing

expressions in queriesrdquo ) This expression selects those salaries that are associated with

dates that are less than or equal to todayrsquos date

Sort nodes

By default a request node returns results in the order that they are returned by the

database Entity instances are sorted and association instances are either sorted or

sequenced depending on the properties of the association type You can override this

behaviour by adding a sort node to the request tree

Each node can have one sort node which acts on its parent node Sort nodes cannotbe

named

To create a sort node

1 Highlight the node that you wish to sort and select Sort from the Add submenu of the

Edit menu or the shortcut menu

You can specify the sort direction by adding an A (for ascending) or a D (for

descending) to the sort expression You must use a comma to separate the direction

indicator from the identifier in the expression

You can use multiple sort identifiers separated by semi-colons ()

An example of a Sort node is the ldquoSortDate Drdquo node shown in Figure 7-10 This is

part of the Latest Salaries query in the Human resources example application In this

example salaries are sorted in descending order (D) of date

To delete a sort node

1 To delete a sort node highlight the sort node and select Delete from the Edit menu or

click the Delete button on the toolbar

Derived types and derivations

You can add the results of calculations to your query results by adding calculated nodes

and targets Nodes that contain calculated results are known as derived types and targets

that contain calculated results are known as derivations



examplerdquo

Derived type nodes

At any node you can add one or more derived type nodes A derived type request causes

new values to be generated according to an expression that you define You can rename

the derived type to give it a meaningful name This name is used as the ldquoverbrdquo of the

association that is created to hold the result of the derived typesrsquo expression

You can add one or more derived type nodes to the query node itself These derived type

nodes apply to the whole query A derived type node is evaluated once for each result

instance that its parent node returns and just once if its parent is the query node

If a derived type added to the query node contains no references to the data request node

or any of its child nodes (the main data request tree) then it is called ldquoindependentrdquo and

can be calculated before the data request This means that it will be calculated before the

main data request tree and can be referenced in expressions in the main data request tree

without any circular reference problems

This kind of node allows us to have references to global ldquoSystem Parametersrdquo and use

them within the data request tree If the derived type is given a specific result type then


Sentences queries

300

that target can be bound to an instance in the database used to store globally referenced

constants or indices

If a derived type added to the query node is independent then by default it will be

calculated first before the main data request tree If you wish it to be calculated at the end

then you can specify for it to do so in the properties and from the context menu For

example if the derivation expression is ldquoTimeNow()rdquo and is used to note when the query

finishes executing you would wish to change when the derived type is calculated

To create a derived type node

1 Highlight the node and select Derived type from the Add submenu of the Edit

menu or the shortcut menu

Sentences adds a Derived type node with an attached expression node and opens

the properties dialog

2 Enter a name for the Derived type node

3 Click on the Edit button and use the Expression Editor to create your expression

For more details about expressions see ldquoUsing expressions in queriesrdquo

4 When you have finished creating your expression and return to the Properties

dialog the Resulting and Existing Datatypes will be displayed You can choose

to change the existing datatype to match the suggested one Note that it is not

always possible to determine the resulting datatype and so you may have to

manually choose an appropriate one

To edit an existing derived type expression select Edit Expression from the shortcut

menu for the expression node or double click the expression

An example of a derived type node is the latest salary node shown in Figure 7-10 This

is part of the Latest Salaries query in the Human resources example application

In this example salaries have been selected by date and sorted in descending date order

The derived type node uses the group function First() to select the first salary in the

ordered list of salaries produced by the selection and sort nodes

Derived type node properties dialog

The Properties dialog for a derived type node is shown in Figure 7-11 More information

about the Format page is in the section ldquoQuery node Format properties pagerdquo and full

details are in the section ldquoFormat properties pagerdquo For details of the settings on the

Presentation page see the section ldquoDatatype properties pagerdquo The User Help page allows

you to enter the help text to be displayed to the user of a dataform when they request help

for the field corresponding to this request

The Read-only on dataform property on the Format properties page is always checked

for derived types

You can use this Properties dialog to set a datatype and the corresponding format

options and these are saved with the query Data values returned by the derived type are

displayed using the datatype and format options that you define


Sentences queries

301

Figure 7-11 The derived type node Properties dialog

To view the derived type properties dialog highlight the derived type node and select the

Properties tab The resulting datatype and settings can also be set on the same property

page

Note Checking or clearing the Instances are values checkbox on the derived type node

Properties dialog has no effect on the output of the query

Default Targets and Derived Targets

A create dataform can populate a field using a default target or a derived target a

calculated field If an edit dataform is opened and such a field is empty it will also be

populated with the default target A calculated derivation replaces the original target of

the association on which it is set

Default Target and Derived Target functionality has been normalised into one property

page for requests There is an equivalent property page for Schema and those values will

be used as defaults in query request nodes

If the Association Type is used in an Inverse request then it is the source that is derived

rather than the target

A Derived Target can be either a specific instance or a derivation


Sentences queries

302

For a detailed example of the use of derived types and derivations and their affect on a

custom Dataform please see the ldquoDerivations examplerdquo

Recalculation rules for derivations

When you create a derivation you can define when its value is recalculated The

recalculation options are given in the section ldquoDerivation propertiesrdquo The available

options are determined by whether or not the association type to which the derivation is

attached is read-only and whether or not the derivation itself is editable or not

The Read-only property of the association type is set on the Format page of the parent

nodersquos Properties dialog The Editable property of the derivation is set on the

Derivations page of the Query node properties dialog If an association is Read-only it

cannot be Editable


Sentences queries

303

Derivation properties

A Properties dialog that includes a Derived Target properties page is available for

forward nodes in a query whose targets are calculated as derivations (see ldquoDefault Targets

and Derived Targetsrdquo) The properties dialog also includes the Dataform navigation page

as described in (see ldquoQuery node Dataform properties pagerdquo) and the Format page

To view the Derived Target properties page select Properties from the Edit menu or

from the shortcut menu on the node

Figure 7-12 The Derived Target properties dialog

bull If the association type is multiple the only available calculation option is Calculate

once In this case the derivation is effective only when no instances of the association

type exist for this source When one or more instances already exist the derivation does

not create new instances

bull If the association type is singular and read-only the derivation editable property is

always Not Editable In this case the calculation options are

bull Calculate once for example to set the date the invoice was created

bull Only calculate on ldquoSaverdquo for example to calculate an account balance or to set the

date last saved

bull Calculate always for example to calculate an invoice line total In all these cases the

derivation field cannot be edited by the user

bull A derivation with the recalculation option Only calculate on ldquoSaverdquo is only

recalculated if it appears on a parent Dataform or on a child Dataform whose parent is a

custom Dataform

bull If a derivation is shown on a child Dataform whose parent is a base Dataform do not

use the Only calculate on ldquoSaverdquo option Use Calculate once or Calculate always

bull If the association type is not defined as read-only the derivation Editable property can

be set to either Editable or Not Editable If it is set to Not Editable the calculation

options are identical to those given above However if the derivation property is Editable

the calculation setting is

bull Calculate once

In this case the derivation field is always editable by the user


Sentences queries

304

The following table summarises the permissible combinations for singular association

types (for multiple association types the only setting allowed is Calculate once)

Association type read-only

property

Derivation editable property Calculation setting

read-only=yes not editable Calculate once

read-only=yes not editable Calculate on ldquoSaverdquo

only

read-only=yes not editable Calculate always

read-only=no not editable Calculate once

read-only=no not editable Calculate on ldquoSaverdquo

only

read-only=no not editable Calculate always

read-only=no editable Calculate once

Editing a derivation expression

To edit a derivation highlight a node in the Query Editor and choose Edit Derived

Target from the Edit menu

To clear a derivation open the properties for derived target and select None

Specific derived type targets

Version 40 introduces the ability to define the type of a Derived Types target This means

that further request nodes can be added to the target

The derived type is singular so either a derivation or a bound instance must be specified

to determine the target instance This functionality is intended for use when needing to

associate with reference data that does not change frequently For example some global

parameters to an application that depend on region or business unit

Using expressions in queries

You can use expressions in derived types derivations and selection operator statements

in Sentences queries

The calculations in a derived type node can use identifiers based on node or parameter

names (the equivalent of variables) constants which may be a string or a numeric value

arithmetic operators comparison operators wildcards and logical connectives (all listed

in the tables below) Calculation expressions may also make use of Datatype methods and

type constructors In addition the derived type node can use a number of group

expressions and the selection operator can use the special conditional function

Exists()

Expressions are always evaluated from left to right so you should take care to place the

most specific datatype (such as Currency a specialised type of Number) on the left hand

side of any expression before any general datatype (such as Number)


Sentences queries

305

Expression syntax for queries

The following BNF grammar shows how expressions in Sentences queries are parsed

FilterExpression = ConditionalExpression ltEOFgt

RequestQueryExpression = ScalarExpression ltEOFgt

Assignment = Id = ScalarExpression

ConditionalExpression = ConditionalInclusiveOr

ConditionalInclusiveOr = ConditionalExculsiveOr ( ( | | ltORgt )

ConditionalExculsiveOr ) ConditionalExculsiveOr = ConditionalAnd ( ^ ConditionalAnd

)

ConditionalAnd = UnaryConditional ( ( amp | ltANDgt )

UnaryConditional )

UnaryConditional = ( | ltNOTgt ) (

ConditionalExpression )

| ConditionalPrimary

| ltEXISTSgt ( Id )

ConditionalPrimary = ( ConditionalExpression )

| ScalarExpression ComparisonCondition

ComparisonCondition = = ScalarExpression

| == ScalarExpression

| = ScalarExpression

| ltgt ScalarExpression

| lt ScalarExpression

| gt ScalarExpression

| lt= ScalarExpression

| gt= ScalarExpression

| LikePredicate

LikePredicate = ( ltNOTgt ) ltLIKEgt ScalarExpression

ScalarExpression = IfStatement

| ConcatPart ( ( || | ltCONCATgt )

Concat Part

IfStatement = ltIFgt ConditionalExpression ltTHENgt

ScalarExpression ltELSEgt ScalarExpression

ConcatPart = ScalarTerm ( + ScalarTerm | -

ScalarTerm )


Sentences queries

306

ScalarTerm = ScalarFactor ( ScalarFactor |

ScalarFactor )

ScalarFactor = - ScalarPrimary

| ScalarPrimary

ScalarPrimary =

| FunctionCall

| MethodCall

| Default

| Literal

| ID

| ltVOIDgt

| ( ScalarExpression )

FunctionCall = ltIDENTIFIERgt ( ( ScalarExpression )

)

MethodCall = ltIDENTIFIERgt ltIDENTIFIERgt ( (

ScalarExpression ( ScalarExpression

) ) )

Default = ltDEFAULT_VALUEgt ( ScalarExpression

DefaultLiteralValue )

DefaultLiteralValue = FunctionCall

| Literal

Id = ltIDENTIFIERgt ( ltIDENTIFIERgt )

= ( ltINTEGER_LITERALgt )

| ( ltFLOATING_POINT_LITERALgt )

| ( ltSTRING_LITERALgt )

In this BNF grammar listing FilterExpression is the starting point for Selection

expressions and RequestQueryExpression is the starting point for derived type and

derivation expressions

FunctionCall indicates either one of the group functions for example Sum(x) or a

datatype constructor for example MixedCurrency(ldquoGBP100rdquo) and MethodCall

indicates a Datatype method for example DateNow()

Arithmetic and Concatenation operators

The arithmetic and concatenation operators that are supported in derived type and

selection node expressions are

Precendence Operator Meaning

Highest - Unary Minus

Multiply

Divide

+ Add

- Subtract

Lowest || Concatenate

If either side of an add subtract multiply or divide operator has no value the operator

returns no value


Sentences queries

307

If either side of add or subtract operator has the zero token output from a Sum() method it

is treated as a zero with the datatype of the other side of the operator If both sides of the

operator have the zero token the operator returns the zero token

If either side of the multiply operator has the zero token the operator returns the zero

token With the divide operator any value divided by the zero token returns no value and

the zero token divide by any value returns the zero token

If the input to the singular negate operator (the unary minus) has no value the operator

returns no value If the input to the singular negate operator (the unary minus) is the zero

token the operator returns the zero token

If either side of the concatenate operator has no value the operator returns no value

bull Arithmetic operators example

The following example illustrates the precedence of the arithmetic operators An


-4 + 6 2

returns the result

-1

as the divide operation is evaluated before the add operation The use of parentheses can

change the order of evaluation An expression in the format

(-4 + 6) 2

returns the result

1

bull Concatenate operator example

In a schema with entity types FirstName and LastName and with entity instances Mary

and Jones respectively an expression in the format

FirstName || ldquo rdquo || LastName

returns results of the type

Mary Jones

The expression includes a blank space in inverted commas which appears between the

FirstName and LastName instances

Further operations on strings can be performed using the string methods on the Text

datatype (see ldquoDatatype methods examples Text datatype string methodsrdquo )

Comparison operators

The comparison operators that are supported in selection node expressions are

Operator Meaning

= Equals

== Equals

= Not equals

ltgt Not equals

lt Less than

lt= Less than or equal to

gt Greater than

gt= Greater than or equal to

LIKE Pattern Match

NOT LIKE Negative Pattern Match


Sentences queries

308

If either side of a comparison operator has no value then the comparison operator

expression returns no value If either side of a comparison operator is the zero token

output from a Sum() method the token it taken as being a zero (0) in the datatype on the

other side of the comparison operator If both sides of the comparison operator have the

zero token the values are assumed to be equal

bull Comparison operators example NOT LIKE

Given a schema with an entity type LastName and entity instances of various names an

expression in the format LastName NOT LIKE ldquoJonesrdquo returns results that include all

names that do not match Jones Used in this way the LIKE and NOT LIKE operators

return the same results as = (equals) and = (not equals) The LIKE and NOT LIKE

operators may also be used with wildcards as shown below

The LIKE and NOT LIKE operators are not case-sensitive

Wildcards

The wildcards that are supported in selection node expressions are

Wildcard Character Meaning



characters

If you want to use either of the wildcard characters as part of your pattern you need to

ldquoescaperdquo the character with a backslash as follows




characters

represents a literal character

a single backslash causes an error in query expressions

You can use these wildcards with comparison operators such as LIKE and NOT LIKE

and in the Sentences Explorer Filter tool

bull Wildcards example LIKE with

In a schema with an entity type LastName and entity instances of various names an


LastName LIKE ldquoJonsrdquo

returns results that include names such as Jonas Jones Jonsons and so on

bull Wildcards example using an escaped wildcard character

In a schema with an entity type Description and entity instances of text strings that may

end in a question mark () character an expression in the format

Description LIKE ldquordquo

returns any instance of Description that ends in a question mark () character


Sentences queries

309

Logical connectives

The logical connectives that are supported in selection node expressions are listed below

You can either use the special character shown or the English alternative for each

connective

Character Alternative Meaning

amp AND And

| OR or (inclusive)

^ XOR or (exclusive)

NOT not

|| CONCAT concatenate

bull Inclusive or

The inclusive or is represented by ldquo|rdquo The expression ldquoA|Brdquo means ldquoeither A or B or

bothrdquo

bull Exlusive or

The exclusive or is represented by ldquo^rdquo The expression ldquoA^Brdquo means ldquoeither A or B but

not bothrdquo

bull Logical connectives example amp

In a schema with entity types FirstName and LastName and with entity instances

David and Jones respectively an expression in the format

FirstName = ldquoDavidrdquo amp LastName = ldquoJonesrdquo

returns only those results for which both conditions apply that is where the FirstName is

David and the LastName is Jones

The operators AND OR and XOR are case-sensitive and must always be entered in

capitals The operators NOT and CONCAT are not case-sensitive

Logical connectives behaviour with missing values

The following list shows the output of the logical operators if one side of the operator has

no value


OR True True False or no value True

False True True

False False False


no value True True

no value False no value


AND True True True

True False False


False True False or no value False

no value True no value

no value False False


Sentences queries

310



XOR True True False

True False True


False True True

False False False



NOT True - False

False - True

no value - no value

Conditional operator

You can use a conditional operator in a derived type derivation or selection expression

The operator requires the three keywords IF THEN and ELSE The operator is not valid

unless all three keywords are present The syntax for a conditional operator expression is

as follows

IF Condition THEN trueValue ELSE falseValue

The condition can be any statement using a comparison operator

bull Conditional operator example

To return the name of an Employee except when that person is the manager use the

conditional operator in an expression in the following form

IF Employee=ldquoBarney Norrisrdquo THEN Employee ELSE ldquothe managerrdquo

For this expression if the Employee is not Barney Norris the expression returns the

Employee name otherwise it returns the string ldquothe managerrdquo

The three keywords IF THEN and ELSE are case sensitive and must always be entered

in capitals

The conditional operator cannot be used as the only term in a Selection expression as

Selection expressions require a Boolean result (true or false) which the conditional

operator does not return Selection conditions can be created using one of the comparison

operators

To create a Selection expression which is conditional use the conditional operator in a

derived type expression followed by a Selection expression that refers tot the derived

type for example

Derived Type(IF(Exists(Phrase)) THEN( || Phrase || ) ELSE())

Selection(Title LIKE Derived Type)

Using Void in an expression

You can instruct Sentences not to create an association in a query result if a particular

result is not found by using the token VOID in a conditional expression

bull Void example

If you only want to output an association that represents the number of employees when

that number is greater than 3 use the following expression


Sentences queries

311

IF Count(Employee)lt3 THEN VOID ELSE Count(Employee)

The VOID token is case-sensitive and must always be entered in capitals

Exists Conditional function

The Exists() conditional function can be used to restrict results of a parent request

based on whether a child request has any results This function is used to limit the display

of results in the results tree to those branches where an instance of the specified node

exists

The argument of the Exists() conditional function must be an identifier It may not be

a complex expression

You should compare the result of using this function result with the result of defining a

node as Required (see ldquoRequired nodesrdquo )

You can combine the Not operator ldquordquo with the Exists() conditional function in the

format (Exists()) to restrict results of a parent request based on whether a child

request does not have any results This is useful as there is no negative equivalent of the

Set Required function

bull Exists conditional function example

In a schema with the association type Person visits store adding a Selectionnode to

Person with an expression in the format

Exists (Store)

returns only those Person instances for which the Person visits Store association

exists

The Exists operator is not case-sensitive

Default value

You can set a default value for a type that you wish to use in an expression The default

value must be an instance of the selected type Setting a default is the equivalent of using

the Exists() conditional function in a conditional expression

bull Default value example

In a schema with the entity type Employee and a number of Employee instances you

can define Barney Norris as the default Employee with either of the following

expressions

IF Exists(Employee) THEN Employee ELSE ldquoBarney Norrisrdquo

or

DEFAULT(Employee ldquoBarney Norrisrdquo)

The DEFAULT operator is case-sensitive and must always be entered in capitals

Using parameters in query expressions

You can use a parameter in a query expression (see ldquoQuery Parametersrdquo )

In many cases you may use the parameter name directly in an expression However if you

use a parameter name and there is a query node with the same name the value returned is

the value of the query node and not that of the parameter

To make sure that you get the value of the parameter use the GetParameter function

This function takes the name of a parameter as its argument The parameter name must be

a string inside quotation marks

For example GetParameter(ldquoPersonrdquo) returns the value of the query parameter

Person


Sentences queries

312

Using user-defined parameters


for servlet access and refer to them in query expressions For details of how to use these

parameters see User-defined parameters

To refer to a user-defined parameter use the GetClientParameter method with the

name of the parameter in the query expression Optionally you may add a default value to

the query expression which is used if no value is defined for the parameter

bull User-defined parameters example


ltPARAM NAME=ClientParameter1 VALUE=CP1=Barney Norrisgt then a

query expression in the format GetClientParameter(CP1) returns the value

Barney Norris


ltPARAM NAME=ClientParameter2 VALUE=CP2=gt

then a query expression which includes a default value in the format

GetClientParameter(CP2Mary Venice) returns the value Mary Venice

The default value you specify in the query expression is returned whenever Sentences

cannot return the value from the user-defined parameter for example when the

specification is missing or incomplete

Using conditionals to check for parameter values

If either side of a comparison operator has no value the expression returns no value If

either side of one of these operators uses a parameter and that parameter has no value the

expression returns no value

You can use a conditional expression or use the Exists() conditional function to

check for the existence of parameter values and to substitute a value if none exists

Group functions

The group functions that are supported in derived type and selection node expressions are

Function Meaning

Count() Returns the number of values

CountDistinct() Returns the number of distinct values

Sum() Returns a sum of the values

Average() Returns the average of the values

Min() Returns the lowest value

Max() Returns the highest value

First() Returns the first value

Last() Returns the last value

StdDev() Returns the standard deviation of the values

StdDevSample() Returns the sample standard deviation of the values

Group functions can also take an expression as their argument

If the Sum() or Count() group function has no input values it returns a special zero

token (see ldquoExpressions that give the zero token as their resultrdquo) If the Average()

group function has no input values it returns no value

The CountDistinct() function is similar to the Count() function except that it

counts the number of distinct values rather than the number of values Repeated values

are counted many times by Count() but are counted only once by CountDistinct()

Note that CountDistinct() compares values by name not by their internal identifiers


Sentences queries

313

For example if you are counting instances of the entity type Person and there are two

Persons named John Smith they are counted as one instance

bull Group functions example Max()

In a schema with an association type ((Company orders Product) on Date) you

could construct a query to return the date of the latest order using a Derived type named

LastOrderDate with an expression in the format Max(Date)

Datatype methods

Datatype methods can be used in derived type and selection node expressions For a

complete list of functions see the section ldquoAdditional Expression Capabilitiesrdquo

bull Arithmetic operations with Date and Time datatypes

The following arithmetic operations are supported with the Date datatype

date + number

adds number of days to the date of date

date ndash number

subtracts number of days from the date of date

date1 - date2

computes the number of days that date2 is earlier or later than date1

The following arithmetic operations are supported with the Time datatype

time + number

adds number of seconds to the time of time

time ndash number

subtracts number of seconds from the time of time

The following arithmetic operations are supported with the Timestamp datatype

timestamp + number

adds number of seconds to the time of timestamp

timestamp ndash number

subtracts number of seconds from the time of timestamp

bull Datatype methods examples Date Time and Timestamp datatypes

The following expression is an example of the method GetDayofWeek(date) The

(date) part of this expression shown in the example is a type constructor for the Date

type (see ldquoType constructorsrdquo ) You may also use a variable of the type Date

DateGetDayofWeek(Date(ldquo150302rdquo) )

returns a numeric value representing the day of the week for 15th March 2002 (where

Monday=1 Tuesday=2 and so on) The value returned in this example is 5 representing

Friday

The other DateGet methods also return numeric values

DateGetYear(date) returns a numeric value equal to the year

DateGetMonth(date) returns a numeric value representing the month (where

January=1)

DateGetDay(date) returns a numeric value equal to the day of the month

The following examples of expressions use the Date datatype and may be applied equally

to expressions using the Time or Timestamp datatype as well

These examples use an entity type LastDate


Sentences queries

314

The following expression is an example of the method AddDays(date num) DateAddDays(LastDate 5)

returns a new date that is 5 days after LastDate without altering the value of LastDate

The following expression is an example of the method AddMonths(date num)

DateAddMonths(LastDate 5)

returns a new date that is 5 months after LastDate without altering the value of

LastDate

The following expression is an example of the method AddYears(date num)

DateAddYears(LastDate 5)

returns a new date that is 5 years after LastDate without altering the value of LastDate

The Now() method for the Date Time and Timestamp datatypes takes its value from

the time clock on the machine running the Sentences server

bull Datatype methods examples Currency and MixedCurrency datatypes

The following examples use an entity type MyCurrency which is a number with the

Currency datatype assigned


source cur factor target iso code) for Currency MixedCurrencyConvert(ldquoGBPrdquoMyCurrency161 ldquoEURrdquo)


rate 161 and the result has the Currency datatype

The following expression is an example of the method GetISOCode(value) CurrencyGetISOCode(MyCurrency)

returns the ISO code for MyCurrency

The following expression is an example of the method GetValue(value) CurrencyGetValue(MyCurrency)

returns the amount of MyCurrency as a number with the Number datatype


source cur factor target iso code) for MixedCurrency

CurrencyConvert(ldquoGBPrdquoMyCurrency161 ldquoEURrdquo)


rate 161 and the result has the MixedCurrency datatype

Note The Convert method for the MixedCurrency datatype does not currently

support conditional access to multiple conversion factors As a result this method can

only process input data in a single currency Input values with a currency other than that

specified as the source ISO code do not produce valid output (the output value is zero)

bull Datatype methods examples Text datatype string methods

The following string methods can be applied in query expressions to Text datatypes In

the following examples string represents the type name

IndexOf(string substring)

returns the index position of the first occurence of the substring

IndexOf(string substring fromIndex)

returns the index position of the first occurence of the substring after the specified

fromIndex index position

Length(string) returns the length of the string

Replace(string oldSubstring newSubstring) replaces the oldSubstring text

with the newSubstring text


Sentences queries

315

SubString(string beginIndex)


ending at the end of the string

SubString(string beginIndex endIndex)


ending at the specified endIndex index position

ToLowerCase(string)

returns the entire string in lower case characters

ToUpperCase(string)

returns the entire string in upper case characters

Type constructors

To create an instance of a Currency MixedCurrency Percentage Time Date or

Timestamp value in an expression you must use the appropriate constructor method for

the datatype You cannot use a string such as ldquo100rdquo on its own

Instances of Number and Text do not require type constructors

This type constructor consists of the name of a datatype followed by a value in

parentheses which is used to construct a suitable value

Note The date format used must match the date format supported by the version of Java

installed on the machine running your Sentences server

bull Type constructors examples

The following are examples of type constructors for their respective datatypes

Currency (ldquo100rdquo)

MixedCurrency (ldquoGBP100rdquo)

Percentage (ldquo10rdquo)

Time (ldquo2359rdquo)

Date (ldquo31121999rdquo)

Timestamp (ldquo1999-12-31 235900rdquo)

Identifiers in operator request node expressions

You can use a parameter name or any request node name as an identifier in a derived type

or selection expression

The following restrictions apply to the use of identifiers in expressions

bull node names used in expressions must be unique You may rename a node to make sure

its name is unique without affecting the nodes link to its original type

bull parameters used in expressions must be based on entity types not association types

bull request node names used in expressions must be those of entity types not association

types

bull if you want to use a node name which contains a character that is also an operator

character (such as - or +) you must rename the node before you can use it as these

characters would cause an error

You should take care to avoid circular references in your queries

Expression results

The number of possible results from a request node determines where the node may be

used in an expression If more than one result can be produced then that node name can

only be used is as part of an expression that is the argument to a group function The

result from an expression that is an argument to a group function can be multiple or

singular


Sentences queries

316

The rules that determine whether a particular request node can generate a singular result

or multiple results is as follows

bull Any request node that is a direct parent node of the expression or selection node is

singular

bull Any other request node whose results have been generated before this depends on the

singularity of any forward or inverse association type request nodes between the

expression or selection request node and request that the identifier comes from Any

forward or inverse requests that are direct parent requests are considered to be singular

Missing values in expressions

The way Sentences behaves when it finds missing values in expressions depends on the

operator being used The descriptions of each of the types of expression operator

elsewhere in this chapter give details of the way missing values are dealt with

Expressions that give the zero token as their result

If the Sum() or Count() group operator has no input values it generates a special zero

token that may be the input for other expressions

If the result of a complete expression for a derived type is the zero token Sentences

converts the result into a zero value for the datatype for the derived type request If

the datatype for the derived type request has not been set and this is the first value found

for this expression then the returned value is 0 with the Number datatype

Required nodes

You can restrict the results of a node by defining the node as Required If a node is

defined as required then the query results for the parent level of that node are restricted to

those instances for which the child node exists

If you need to restrict the returned instances of the node above the parent you must also

define the parent node as Required To restrict the instances of an ultimate parent node to

only those where a child instance exists all associations in the branch to the child must be

defined as Required

Figure 7-13 shows a simple query listing four garage customers By defining the (hellip

owns vehicle registration no) node as required only the three customers who own

vehicles are listed in the results as shown in Figure 7-14

Figure 7-13 Query results before setting the Required node property


Sentences queries

317

Figure 7-14 Query results after setting the Required node property

Another use of the Required node property is shown in the example of a node bound to

an instance (see Binding to an instance) When used with bound nodes the Required

node property may be used as an alternative to the Exists() conditional function as a

selection mechanism (see Exists Conditional function)

To set the Required node property highlight a node and select Set Required from the

Edit menu or the shortcut menu To clear the Required node property select Set

Optional from the Edit menu or the shortcut menu

Renaming request nodes

You can rename any request node in the query tree with the exception of Sort and

Selection nodes This allows you to make node names unique which simplifies references

between one node and another and can make your query easier to read

Sentences uses the new names you assign to query nodes when you display the query

results in the Query Editor or in the Explorer or when you export the query results using

XML or when you display a custom Dataform based on the query

The default name of any node in the request tree is the same as its association or entity

type name in the Sentences Explorer If you change the name of an association or entity

type in the Explorer the Query editor retains the original name and treats the node as if it

had been renamed The reference to the entity or association type remains intact

Except for node names used in derived type expressions which must be unique to prevent

ambiguity Sentences does not require you to use unique node names

Ambiguous names in expressions may cause the query to be executed incorrectly or not at

all

To rename a node

To rename a node follow these steps

1 Highlight the node you want to rename You can rename both association type and

entity type nodes If you want to rename the entity type that is the target of an association

make sure you expand the node and select the target

2 Select Rename from the Edit menu or the shortcut menu or press Ctrl+R or press F2

3 Type in the new name for the node Press Enter or click outside the text edit box or

use the up or down arrow cursor keys to complete the renaming You may wish to save

your query after renaming a node


Sentences queries

318

Hidden Nodes

The expression used by a derived type or a selection request can only use data that is

retrieved as part of the query This means that you may need to including certain data in

your query so that an expression can use it and you may not want to display the data You

can suppress the display of selected branches by marking them as Hidden

Hidden nodes are displayed in grey If you hide a node all its children are hidden as well

To hide a node

To hide a node highlight the node and select Hide Branch from the Edit menu You can

also open the shortcut menu select the Edit submenu and then select Hide Branch To

make a hidden node visible in the results tree select Show Branch

Figure 7-15 shows a query result (from the latest salaries query in the Human

Resources example application) which does not have any of its nodes hidden In the

result tree you can see details of all the Event associations that the query needed to select

from and sort in order to derive the latest salary These branches detract from the results

you want to display

Figure 7-15 Query results before hiding a branch

Figure 7-16 shows the same query and results after the Events branch has been hidden

The results pane only shows the relevant salary details and not the intervening nodes


Sentences queries

319

Figure 7-16 Query results after hiding nodes

Transitive closure and recursive closure

Some relationships between real-world entities are transitive and carry over from one

entity to another An example is ancestor of If Henry is an ancestor of Clare and Clare

is an ancestor of Edward then Henry is also an ancestor of Edward Database systems

use recursive mechanisms to find instances of this kind of relationship For example

instead of locating only a Person who is an ancestor of Clare the system also looks for

any Person who is an ancestor of an ancestor of Clare and so on

Sentences offers two query operations to deal with these kinds of relationships

Transitive closure and Recursive closure

Transitive closure

A transitive closure operation allows you to find all the instances of a transitive relation

such as the association type (Person parent of Person) The result of a transitive

closure operation is a simple list of instances all at the same level The node selected as

the target for transitive closure must be a child node of the selected node and it must be

of the same type or of an equivalent type (supertype subset type or equivalent type) as

the selected node

To define transitive closure for a node

Figure 7-17 Parents query before applying transitive closure


Sentences queries

320

Figure 7-17 shows a query before adding transitive closure

To define transitive closure for a node highlight the node and select Add transitive

closure from the Edit menu You can also open the shortcut menu select the Edit

submenu and then select Add transitive closure

Note To make a closure using transitive closure select the start of the chain of query

nodesTo make a closure using recursive closure select the end of the chain of query

nodes When you select Add transitive closure Sentences displays a special Picker that displays

the whole request tree but only allows you to select appropriate nodes as shown in Figure

7-18

Figure 7-18 The node picker for the add transitive closure operation

When you select a node for transitive closure Sentences adds a new node to the query as

shown in Figure 7-19 The original branch to the selected target node ishidden by default

This branch cannot be modified in any way except for renaming to avoid duplicate names

referred to in expressions

Figure 7-19 The transitive closure node ready to be renamed

The transitive closure node is created with the name Transitive Closure which changes

to the name of the selected target node This should be renamed to a unique name If you

do not rename it Sentences warns that there is a node with a duplicate name in your

query

Figure 7-20 shows the results of the same query shown in Figure 7-17 after adding a

transitive closure node and changing the name of the node to Ancestors


Sentences queries

321

Figure 7-20 Parents query after adding a transitive closure node

You may add further query nodes from the target of a transitive closure to define the

information shown for each result (in this case for each ancestor) A query that includes a

transitive closure node cannot be used for a custom Dataform If you associate a custom

Dataform with a query that includes a transitive closure node Sentences displays an error

message

To cancel recursive closure for a node select Remove transitive closure

Recursive closure

If your database contains associations which have the same entity or association type or a

related entity or association type as both the source and the target (for example Person

parent of Person) then you can use a recursive closure operation to find all the

instances in a chain (for example all the known ancestors of a given individual)

Recursive closure requires a linked chain of association instances (for example a is

parent of b b is parent of c c is parent of d and so on) and the result of a recursive

closure operation is always a linked tree of nodes Figure 7-21 shows an Ancestors query

without using recursive closure


Sentences queries

322

Figure 7-21 Ancestors query without recursive closure

The recursive closure operation creates a loop in the request tree by automatically adding

the child nodes of the parent to the child node This loop generates a new level of the

result tree with each turn However if there is a loop in the data (which may happen in a

case such as Person sibling of Person) then the recursion could repeat itself forever

To prevent this Sentences checks each entity to make sure that it has not already been

processed If it has then it is not processed again

Figure 7-22 shows the same query after recursive closure has been applied

Figure 7-22 Ancestors query with recursive closure

To define recursive closure for a node

To define recursive closure for a node highlight the node which must be a source or a

target Select Make recursive closure from the Edit menu Alternatively select the Edit

submenu and then select Make recursive closure

Note To make a closure using recursive closure select the end of the chain of query

nodes To make a closure using transitive closure select the start of the chain of query

nodes

Sentences displays a special Picker (shown in Figure 7-23) that displays the whole request

tree but only allows you to select appropriate nodes

Figure 7-23 Recursive closure target picker

The node you choose for recursive closure must be of a related type which includes the

same type a supertype a subtype or a subset The node chosen for recursive closure must

be higher up the tree than the selected node on the path between that node and the data

request node It may be a source a target or a data request


Sentences queries

323

A query that includes a recursive closure node cannot be used for a custom Dataform If

you start a custom Dataform on a query that includes a recursive closure node Sentences


You cannot add any further query nodes from the target of a recursive closure

To cancel recursive closure for a node highlight the node and select Break recursive

closure from the Edit menu Alternatively select the Edit submenu and then select

Break recursive closure

Query Parameters

You can use parameters in a query to restrict the results to a specific instance of a type

rather than all the instances You can use a parameter directly to replace an entity type or

indirectly in an expression (see ldquoUsing parameters in query expressionsrdquo ) An example of

a query with parameters is the Resource Data query which is part of the Human

Resources example application as shown in Figure 7-24

Figure 7-24 A query with parameters

Using a parameter makes running a query interactive Each time you execute the query

Sentences asks you to select the value for your parameter by displaying a parameters

dialog as shown in Figure 7-25 (below)

Naming parameters

If you want to create a parameter to bind an entity type request node in your query you

must give it exactly the same name as the request node Using the same name

automatically binds the node to the parameter (see ldquoBinding Nodesrdquo ) If you want to

create a parameter to be used in an expression you may give it any name you like

Try to use only alphabetic characters in parameter names You may use numerals and

spaces in parameter names as long as a space is followed by a character and not a

numeral You may not use special characters in parameter names Parameters may also be

renamed in the same way as a node (see ldquoTo rename a noderdquo )

Creating parameters

Every query includes a Parameters folder in the Query Editor To create a parameter

highlight the Parameters folder and select Create Parameter from the


Sentences queries

324

shortcut menu or select Create Parameter from the Parameters menu Type a name for

the parameter in the dialog box and click OK

To define a parameter highlight the parameter name and use the options on the shortcut

menu or the Parameters menu

Defining a parameterrsquos type

When you create a parameter you may specify the entity or association type that it

replaces To specify the parameterrsquos type highlight the parameterrsquos name and select Set

Type from the shortcut menu or the Parameters menu

Sentences displays a picker list of entity or association types from which you can select

the type

Defining a parameterrsquos value

When you create a parameter you may specify a default value for the parameter The

default value is used unless you specify a different value when you execute the query To

specify the parameterrsquos default value highlight the parameterrsquos name and select Set

Default Value from the shortcut menu or the Parameters menu You may clear the

default value by selecting Clear Default Value from the shortcut menu or the

Parameters menu

If the parameter is based on an association type or an entity type Sentences displays a

picker list of entity or association instances from which you can select the default value

If the parameter is based on an value type Sentences displays a Dataform from which you

can either select an existing value instance or create a new value instance to be used as the

default value

Making a parameter mandatory

All parameters are optional when you create them If a parameter is mandatory you must

supply a value for it when you execute the query To make a parameter mandatory

highlight the parameterrsquos name and select Set Mandatory from the shortcut menu or the

Parameters menu

To make a mandatory parameter optional highlight the parameterrsquos name and select Set

Optional from the shortcut menu or the Parameters menu

Executing a query which has parameters

When you execute a query that includes one or more parameters Sentences displays the

Parameters dialog which allows you to type in values or to select them from a picker

list


Sentences queries

325

Figure 7-25 The Parameters dialog

The example in Figure 7-25 shows the Parameters dialog

Showing parameters in the Explorer

When you hold your mouse pointer over the name of a query in the Explorer schema pane

Sentences displays a Tooltip message listing the parameters for that query and their

current settings

Attaching Subset Queries

You can attach a query to a subset using the entity type Properties dialog available from

the Sentences Explorer You need to initiate the attach action from the Properties dialog

or from the Explorer subsets shortcut menu not from the Query Editor (see ldquoSubsets


Using parameters in subset queries

You may use parameters in subset queries but you must make sure that the query can run

in all cases When you view the subset in the Sentences Explorer Sentences uses the

default value for the parameter to select instances for display If there is no default value

the parameter is not given a value

If the query parameter is used to bind a node to an instance and there is no value given for

the parameter Sentences runs the query as if there were no binding and returns all

possible instances

If the parameter is used in an expression and there is no value Sentences cannot run the

query In particular it is recommended that you set a default value for parameters used in

expressions in subset queries

Sentences query execution process

The order in which Sentences processes query nodes when it executes a query is not

necessarily the same as the sequence in which the nodes appear in the query structure

This is because Sentences first optimises the query based on the dependencies between

the nodes in order to enhance the execution speed

When there is a problem with query execution Sentences may report the following error

Error 10199 The order in which the execution of requests occurs cannot be

determined due to circular references

When this error is reported Sentences displays the node expression which caused the

error

When you construct a query you should bear in mind that all nodes in the query tree are

visible to all other nodes Therefore any node name that is used more than once must not

be used in an expression as it is not possible for Sentences to distinguish which

occurrence of the node name should be used to evaluate the expression

Additional expression capabilities

Version 40 introduces several new functions and syntax The flexibility of datatypes has

also been improved Rather than attempt to show changes this section includes a

complete list of functions available


Textual Functions that act on text or

hyperlink values


Sentences queries

326


Value1 | Value2 Returns the concatenation of the first

and second values as Text

Value to compare Like Text

pattern to compare likenessText

Returns whether the first value is

textually like the second value The

second value can contain wildcards

Char(Number to obtain unicode

character forNumber)

Returns the character represented by

the given number in unicode as text


specified Node

GetEmail(Hyperlink to obtain email

address forHyperlink)

Returns the email address of the


GetHostname(Hyperlink to obtain

hostname forHyperlink)

Returns the host name of the


GetPath(Hyperlink to obtain path

forHyperlink)

Returns the path of the Hyperlink as

text if one exists

GetPort(Hyperlink to obtain port

forHyperlink)

Returns the port number of the


GetProtocol(Hyperlink to obtain

protocol forHyperlink)

Returns the protocol of the Hyperlink

as text if one exists

GetQuery(Hyperlink to obtain query

string forHyperlink)

Returns the query string of the


GetUserinfo(Hyperlink to obtain

userinfo forHyperlink)

Returns the user information of the


GetWord(Text to split into words

Text Index of the word to extract

Number)

Returns the Nth word in the input text

If there are fewer words than index

then a null value will be returned

Hyperlink(Value) Construct a new Hyperlink value


find the index ofText)


the first value of the second value -1

indicates not found


find the index ofText Index to

start searching fromNumber)


the first value of the second value

starting a the index specified in the

third value -1 indicates not found


specified Node

Length(Text to get the length

ofText)

Returns the length of the value as a

number

MatchFirstRegexp(Text to be


Text)

Returns the first section of input text

matching the regular expression

MatchAllRegexp(Text to be


Text)

Returns all sections of input text

matching the regular expression -

separated by spaces


Metaphone forText Maximum


generateNumber)


the first value as text The second

value indicates how many characters

to generate


Sentences queries

327



Metaphone forText)


the first value as text




MetaphonesText Maximum


generateNumber)







commonality The third value

determines how many characters to

generate when encoding




MetaphonesText)







commonality

Replace(Input textText Subtext to

be replacedText Subtext to

replace withText)

Returns the text in the first value after

having any occurrences of the second

value text replaced with the third

value text

Sort(Text to be sortedText

Sorting order Text)






duplicates are retained Use

SortUnique() to remove duplicate

words

SortUnique(Text to be

sortedText Sorting orderText)






duplicates are removed



substringNumber Index of the

end of the substringNumber)



second value and ending at the index

specified in the third value



substringNumber)



second value until the end

Text(Value) Construct a new Text value

ToLowerCase(Text to convert to

lower caseText)


lowercase

ToUpperCase(Text to convert to

upper caseText)


uppercase

Trim(Text to trim leading and

trailing space fromText)

Returns the value trimmed of leading

and trailing spaces as text

Mathematical and Statistics Mathematical and Statistical

Functions


Sentences queries

328


Number(Value) Construct a new Number value


value ofNumber)


value as a number



byNumber)



number



zero)Number)



value









figures


ofNumber)


as a number

Percentage(Value) Construct a new Percentage value

Value1NumberText +

Value2NumberText

Returns the addition of the two values

appropriate to their datatypes

Value1Number - Value2Number Returns the subtraction of the two


Value1Number Value2Number Returns the multiplication of the two


Value1Number Value2Number Returns the division of the first value

by the second appropriate to their

datatypes

Value1Number ^ Value2Number Returns the first value raised to the

power of the second appropriate to

their datatypes

StdDev(NodeNumber) Returns the population standard



StdDevSample(NodeNumber) Returns the sample standard



Max(NodeNode) Returns the largest of the values


Min(NodeNode) Returns the smallest of the values


Median(NodeNode) Returns the median of the values


Modulo(Node Node) Returns the remainder of the first

value divided by the second value

Average(NodeNode) Returns the mean of the values


Count(NodeNode) Returns a count of the values



Sentences queries

329


CountDistinct(NodeNode) Returns a count of the distinct values


Sum(NodeNode) Returns the sum of the values


Currency Functions that operate on

currencies

Currency(Value) Construct a new Currency value


inputText Input

CurrencyCurrency Exchange

factorNumber Currency code of

outputText)

Returns a currency converted using

the given codes and factor

GetISOCode(Currency to get ISO

code

fromCurrencyMixedCurrency)

Returns the International Organization

for Standardization code for the

currency as text

GetValue(Currency to get value

ofCurrencyMixedCurrency)

Returns the value of the currency as a

number


value ofNumber)


value as a number



byNumber)



number



zero)Number)



value









figures


ofNumber)


as a number

MixedCurrency(Value) Construct a new MixedCurrency value


inputText Input

MixedCurrencyMixedCurrency

Exchange factorNumber

Currency code of outputText)

Returns a mixed currency converted

using the given codes and factor

Abs(Mixed Currency to get

absolute value ofMixedCurrency)


mixed currency as a number

Date and Time Functions that operate on dates

times and timestamps

Date(Value) Construct a new Date value

Now() Returns the date today

AddDays(Date or Timestamp to

add days toDateTimestamp

Number of days to addNumber)


with the number of days added The



Sentences queries

330


AddMonths(Date or Timestamp to

add months toDateTimestamp

Number of months to addNumber)


with the number of months added


AddYears(Date or Timestamp to

add years toDateTimestamp

Number of years to addNumber)


with the number of years added The


GetAgeInYears(Date or

Timestamp to get the age

ofDateTimestamp)

Returns the whole number of years

since the given date as a number

GetFiscalDay(Date or Timestamp

to get day of the fiscal year for




Returns the day of the fiscal year as a

number

GetFiscalWeek(Date or Timestamp

to get week of the fiscal year for




Returns the week of the fiscal year as

a number

GetFiscalMonth(Date or

Timestamp to get month of the





Returns the month of the fiscal year

as a number

GetFiscalQuarter(Date or

Timestamp to get quarter of the





Returns the quarter of the fiscal year

as a number

GetLastDayOfMonth(Date to get

last day of the month forDate)


number

GetSeconds(Time or Timestamp to

get seconds of the minute

forTimeTimestamp)

Returns the seconds of the minute as

a number

GetMinutes(Time or Timestamp to

get minutes of the hour

forTimeTimestamp)

Returns the minutes of the hour as a

number

GetHours(Time or Timestamp to

get hour of the day

forTimeTimestamp)

Returns the hour of the day as a

number

GetYear(Date or Timestamp to get

the year forDateTimestamp)

Returns the year of the date as a

number

GetMonth(Date or Timestamp to

get month of the year

forDateTimestamp)

Returns the month of the year as a

number

GetDay(Date or Timestamp to get

day of the month

forDateTimestamp)

Returns the day of the month as a

number


Sentences queries

331


GetDayOfWeek(Date or

Timestamp to get day of the week

forDateTimestamp)

Returns the day of the week as a

number

InFiscalYear(Node1

DateTimestamp Node2

DateTimestamp)

Returns whether or not the first date

parameter is in the fiscal year starting

with the second date parameter

Time(Value) Construct a new Time value

AddSeconds(Time or Timestamp

to add seconds

toTimeTimestamp Number of

seconds to addNumber)


with the number of seconds added


AddMinutes(Time or Timestamp to

add minutes toTimeTimestamp

Number of minutes to

addNumber)


with the number of minutes added


AddHours(Time or Timestamp to

add hours toTimeTimestamp

Number of hours to addNumber)


with the number of hours added The


Timestamp(Value) Construct a new Timestamp value

GetLastDayOfMonth(Timestamp

to get last day of the month

forTimestamp)


number

GetMilliseconds(Timestamp to get

milliseconds ofTimestamp)

Returns the milliseconds of the

timestamp as a number

Logical Functions that evaluate a logical

condition to determine their

answer

NOT(ValueBoolean) Returns the logical opposite of the

value

Value1 == Value2 Returns whether the first value equals

the second value

Value1 = Value2 Returns whether the first value does

not equal the second value

Value1 lt Value2 Returns whether the first value is less

than the second value

Value1 gt Value2 Returns whether the first value is

greater than the second value

Value1 lt= Value2 Returns whether the first value is less

than or equal to the second value

Value1 gt= Value2 Returns whether the first value is

greater than or equal to the second

value

Value1Boolean expression AND


Returns whether the first value and

the second value are both true

Value1Boolean expression OR


Returns whether either the first value

or the second value or both are true

Value1Boolean expression XOR


Returns whether one of the two

values is tru and the other false


Sentences queries

332


CaseStart (case expression)

When (when expression1) Then

(then expression1) When (when

expression2) Then (then


expression) CaseEnd

Evaluates whether each when

expression matches the case

expression in turn and returns the

appropriate then expression (or the

else expression if none match)

CaseStart When (when


expression1) When (when



expression) CaseEnd

Evaluates each when condition in

turn and returns the then value or the

else expression if none of the

conditions evaluate to true

Coalesce(Expression1

Expression2 )

Returns the value of the first

expression that does not evaluate to

null

Default(Expression Default

ValueLiteral TextLiteral Number)

Returns the default value if the first


Exists(expression) Returns whether or not the


IF (when condition Boolean)

THEN (then expression) ELSE

(else expression)

Returns the value of the then

expression if the when condition

evaluates to true or else returns the

value of the else expression

Reference Functions that use features

specific to Sentences

PriorResult(NodeNode) Returns the value of the specified

node that was the previous result in

this query data set

PriorResult(NodeNode

DepthNumber)


node that was a previous result in this

query data set The depth value

determines how many results prior to

this one

CurrentUserHasRole(Role) Returns whether or not the currently

logged on user has the specified role

The depth value determines how

many results prior to this one


Parameter)


Client Parameter


Parameter Default Value)


Client Parameter The second value

is returned if no such client parameter

has been set

GetCurrentUserID() Returns the user id of the currently

logged on user

GetCurrentUserName() Returns the name of the currently

logged on user

GetParameter(Query Parameter) Returns the value of the specified

Query Parameter


Sentences queries

333


GetState(Node DomainDomain) Returns the State of the specified

Node for the given Business Rules

Domain

HasState(Node

DomainDomain StateState)

Returns whether or not the specified

Node has the given Business Rules

Domain and State


specified Node


specified Node

TypeOf(Node) Returns the schema type of the

specified Node value

IsSubtypeOf(Node Node) Returns whether or not the value of

the first parameter is a subtype of the

second value The second parameter

can be either an instance a reference

to an Entity Type or the name of an

Entity Type

IsSupertypeOf(Node Node) Returns whether or not the value of

the first parameter is a supertype of

the second value The second

parameter can be either an instance

a reference to an Entity Type or the

name of an Entity Type

User Datatype Functions Functions defined on User

Datatypes

TelecomsNumber(Value) Construct a new TelecomsNumber

value

Valid(TelecomsNumber to

validateTelecoms)

Valid

Of particular note are the following areas

bull Metaphone and MetaphoneDifference

Metaphone is a phonetic algorithm an algorithm published in 1990 for indexing words by

their English pronunciation The algorithm produces variable length keys as its output as

opposed to Soundexs fixed-length keys Similar sounding words share the same keys

The Metaphone function built into Sentences Query Engine returns the encoded

metaphone of the input string There is an optional numeric parameter that indicates how

many characters to generate

The Metaphone Difference function returns the difference (as a floating point number

between zero and one) of the first and second values when encoded using the metaphone

algorithm Zero indicates no commonality One indicates maximum commonality The

third optional numeric value determines how many characters to generate when

performing the encoding on the two string values

bull Hyperlinks

Functions for Hyperlinks have been extended to extract key parts of the URI For

example if you wish to extract the email component from a mailto Hyperlink you can

use the function GetEmail(Hyperlink) to do so


Sentences queries

334

bull Mathematical and Statistical Functions

Numbers (which include Percentages and Currency datatypes) have additional functions

for calculating Random numbers Rounding to a number of decimal places or significant

figures obtaining the Absolute value raising one number to the power of another and

finding the square root of a number

Two new group functions have been added to obtain the Standard Deviation of a set of

numbers StdDev returns the population standard deviation whilst StdDevSample

returns the sample standard deviation Sample assumes a small subset of the total

population and adjusts the calculation to compensate

bull Date and Time functions

A Date or a Time can now be asked for the last day of the month A Timestamp can now

be asked for its milliseconds component

bull Case and Coalesce

Joining the IF THEN ELSE statement are two new logical constructs Case and Coalesce

The Case statement has two syntaxes

Syntax 1

Case (case expression)




This statement allows you to return a given value depending upon which of the when

expressions evaluates to be equal to the first case expression If none are equal then the

optional else expression is returned

Syntax 2

Case




The second syntax for case is the more general form and allows you to return a given

value depending upon which conditional expression evaluates to true This means that

you are not limited to equalities Again there is an optional else expression if none of the

conditional expressions evaluate to true

The Coalesce statement allows you to provide a list of expressions the first one that does

not evaluate to null will be returned There is no Else clause because the last item in the

list can be a ldquocatch-allrdquo value

bull PriorResult

The PriorResult function allows you to reference the result from a specified node from the

previous branch of data results There is an optional parameter to say how many results to

go back


Sentences queries

335

As an example suppose that whether or not it rains today depends on previous weather

conditions through the last two days Specifically suppose that if it has rained for the past

two days then it will rain tomorrow with probability 07 if it rained today but not

yesterday then it will rain tomorrow with probability 05 if it rained yesterday but not

today then it will rain tomorrow with probability 04 if it has not rained in the past two

days then it will rain tomorrow with probability 02

If an entry is made each day to record whether it rained or not we could create a query

that uses this hypothesis to predict the weather tomorrow based on the records for today

and yesterday We could also write a query to historically compare the actual outcome

with the predicted outcome

The Chance of Rain Tomorrow expression is

CASE

WHEN ((Exists(Rained Yesterday) AND Exists(Yes))) THEN

(07)

WHEN ((Exists(Rained Yesterday) AND Not(Exists(Yes)))) THEN

(05)

WHEN ((Not(Exists(Rained Yesterday)) AND Exists(Yes))) THEN

(04)

WHEN ((Not(Exists(Rained Yesterday)) AND Not(Exists(Yes))))

THEN (02)

END

Some results might be


Sentences queries

336

bull User Security

The CurrentUserHasRole() function allows you to adapt the application behaviour

depending upon which Roles the current user has

You may also obtain the users name and login id with GetCurrentUserName() and

GetCurrentUserID()

bull State Domains

The GetState() function allows you to get the current state of an instance for a

specified Domain

The HasState() function answers true if the specified instance has the specified state

Note that an instance may be in two states at once The first function will answer the first

state that evaluates to true according to the order of state definitions in the Predicate

Query The second function will answer true if that state evaluates to true regardless of

the other state definitions in the Predicate Query

See the Using states in regular queries and dataforms section for details

Entity type constructors

Sentences expressions include functions for creating instances of Datatypes to use in

expressions For example you can specify a percentage value using the expression

Percentage(ldquo12rdquo) This is useful if a particular function requires that one of itrsquos

parameters is a certain Datatype

Sentences Version 40 introduces General Entity Type Constructors as well as these

Datatype Constructors

You may enter an expression such as Person(ldquoBarry Squiresrdquo) in an expression and

the resulting value will be of the type Person In the case of Datatype constructors if a

value does not exist then one is created For Entity Types the constructor works

differently If Barry Squires exists then the entity is returned otherwise no value is

returned That is a new Person is not created if the name does not match an existing

entity

The expression and function editors

Expressions in requests prior to Version 40 were composed and edited by editing a text

field You needed to know the available functions and syntax in order to formulate your

expression The expression was not validated until you attempted to execute your query

Version 40 introduces new Expression and Function Editors to assist with the

composition of expressions in Request Queries

Expressions are used in Sentences Queries to derive values and to evaluate truefalse

conditions used to filter results Expressions exist

In a Derived Type to derive the Target

In a Forward Request or a Forward Action Request to derive the Target

In an Inverse Request or an Inverse Action Request to derive the Source

In Message Action Requests to derive the message

In Simple Email Requests to derive the To recipients the Cc recipients the

email subject and the email text

In Selection Nodes to filter the parent of the Selection


Sentences queries

337

In Predicate Queries to define when an instance is in a particular State

In the Default Target properties of an Association Type

In all cases except the Default Target properties of an Association Type the expressions

are part of a query and may reference other request nodes and parameters from that query

When you edit an expression rather than editing the text in a field the Expression Editor

is opened

The expression editor shows you the expression decomposed into its constituent parts and

allows you to select individual components to edit

When you select a component of the Expression a description of that Function or a field

to alter the parameter will be shown

Below this is a field where the entire expression can be edited

Finally there is a notification area at the bottom of the editor that will inform you of any

problems with the expression

You can either select a Function or a Function Parameter If you select a Function they

you may

Edit that function in a child Function Editor

Delete the function You can only do this if you have selected the top-level

function or one side of a binary operation

Wrap a function This opens a child Function Editor with the selected function

specified as the first parameter to the new function that you choose to wrap it in

Remove the outer Function (unwrap a function)

If you select a Function Parameter then you can directly edit that value or node

depending upon the type of parameter expected


Sentences queries

338

The Parent Function of the selected Parameter ldquoExistsrdquo takes one parameter that should

be either a Query Request Node or a Query Request Parameter

Creating a new expression

When a new expression is required a blank Expression Editor will be opened for you

You will have three options open to you

Insert a Function

Insert a Node (or Query Parameter)

Start to type an expression into the full expression field

If you select the Insert Node button the node and parameter picker will be opened for you

to select a node or parameter You may then wrap this node in another function to build

up a more complex expression

If you select the Insert button a blank Function Editor will be opened

This allows you to find the function you require by selecting a category and browsing

through the list of functions on the right When you select a particular function a

description the kind of value it returns and the parameters it requires are shown below

The notification area at the bottom of the editor will inform you of any problems with the

function

At any time in an expression editor or child editor you may select the Reset button to

reset the contents of the editor to the state in which it was opened


Sentences queries

339

Note that the available list of functions will be filtered depending upon the kind of value

that the parent editor expects In the above example any non-boolean value is acceptable

If you were creating a new expression for a Select Request Node then only boolean values

would be acceptable

If the parent function requires a particular datatype then only functions that return that

datatype will be included

Editing a function

If you select a Function and select the Edit button the Function Editor will open for that

Function with its parameters You can select a different function and the parameters will

be retained For example if you had a function to derive the minimum of a Monetary

Value and wished to change it to be the maximum you would select Edit change the

selected function from Min to Max and select OK


Sentences queries

340

Wrapping functions and parameters

When the function or parameter you have selected can itself be the parameter to another

function the Wrap button will be enabled

If you select Wrap then a blank Function Editor will open and when you select a

function the first parameter will be set If the function you select requires more

parameters then you will need to fill in these fields before you can select OK and wrap the

original function or parameter

Unwrapping functions and parameters

If the function you have selected has a single parameter that is a compatible type with the

functions parent then you will be able to unwrap (remove the outer function)

For example below you can remove the Not() function to leave

hellipAND Exists(Yes)hellip

Deleting the expression

If the function you have selected is the top level function then selecting Delete will

remove the entire expression


Sentences queries

341

Deleting a function or parameter

If the function or parameter you have selected is one parameter in its parent binary

function (for example either X or Y in the function X AND Y) then you will be able to

delete it The effect is to remove the parent function and leave behind the other parameter

so in this case deleting X would leave Y and deleting Y would leave X

Nested expressions and functions

When you edit or wrap part of an expression one of the parameters may itself be an

expression or function In this case the parameter field will not contain a simple node

name or literal value and you are able to edit or wrap the expression or function in a new

child editor

To Edit the expression or function select the Edit button To Wrap the expression or

function select the Wrap button If there is no existing parameter value then the Wrap

button will be an Insert button Select this to open a blank child Function Editor

Node and parameter pickers

Many functions take Request Nodes or Query Parameters as parameters If applicable

then Nodehellip and Parameterhellip buttons will appear Selecting one of these will open a

picker showing eligible Request Nodes and Query Parameters

By default only eligible nodes are shown By deselecting the Hide ineligible nodes

checkbox you will be able to see all available request nodes with the ineligible ones

greyed out If you select one then information at the base of the picker will tell you why

the node is ineligible


Sentences queries

342

The reasons why a node may not be eligible are

You cannot specify the node name of the node that this expression is attached to

unless the function is a PriorResult function

You cannot select a node that does not have a unique name

You cannot select a node that has an incompatible datatype

It is possible to rename a node from the list by selecting Rename Node when that node is

the selected item in the picker This allows you to continue defining the expression

without returning to the query editor

When you rename the node any references to it will also be renamed This is unlikely as

existing expressions should prevent a non-unique node name being used elsewhere

Other pickers

There are a few very specific Functions that require very specific parameters

bull GetParameter

The GetParameter() function requires a parameter name so the picker for this only

includes query parameters

bull GetClientParameter

The GetClientParameter() function requires a client parameter name so the picker

for this only includes client parameter names

bull GetState and HasState

These functions require a Domain so there is a picker that shows Domains applicable to

the Type of the node parameter The HasState function further requires a State name and

the picker for this only shows States applicable to the selected Domain


Sentences queries

343

Update Queries

Version 40 introduces the ability to create queries that change data rather than request

results Effector Queries have these abilities but are only executed within the context of a

Transaction and triggered by State Changes and Business Rules Generally an Effector

query will also be acting on a single instance and its associations

Update Queries are intended to update many instances at once Queries that contain

request nodes that may change data appear with a different red icon to identify them as

Update Queries Effector Queries also use the same icon For details of Effector Queries

see the ldquoEffector Queriesrdquo section

When you execute a standard query the results are not all returned at once but for an

Update Query the entire update is performed and you will be asked to confirm the

execution because it could potentially change many data If you press the stop button

whilst an Update Query is executing then the query will be stopped and the transaction

and all changes will be rolled back

There are five kinds of action that an Update Query can perform

Creating or deleting data

Firing a Sentences Trigger

Requesting a State change

Creating a message for the current user

Sending a simple email message

In addition to these five actions some Grouping Requests will act on the instances to

supersede delete duplicates or make the groups members equivalent to one another

Creating and deleting instances

When constructing regular queries you add forward and inverse requests and derived

type requests to existing query nodes starting with the Data Request If you add a forward

request for example then this instructs Sentences to fetch all matching instances from the

database and return them as results You can filter the results that return and you may

derive the results from expressions

With an Update Query you may also delete instances by specifying that a Data Request

deletes matching instances This is toggled on and off from the Data Request context

menu or the Edit menu of the Request Editor The icon ( ) has a minus sign similar to

the ForwardInverse Action Requests below and the query is classed as an Action Request

if the flag is set The LazyType cannot be a Value Type but can be either an ET or an AT

The instances that are deleted are limited in all the usual ways

bull Binding to an instance

bull Adding required child nodes

bull Adding a Selection node

With an Update Query you may also use Association Actions These can be added (either

forwards or inverse) to create or delete data rather than fetch existing data Again you are

able to filter the instances created or deleted

There are four variations on creating data and two variations for deleting When you add a

Forward Action Request or an Inverse Action Request you specify one of six actions

to take

bull Create Associations (duplicate targetssources)


Sentences queries

344


associations The target (or source) will also always be created even if this leads to

duplicates

bull Create Associations (reuse targetssources)


associations but will reuse any existing target (or source) or create them as needed

bull Set Association

This action creates an association if one is needed If there is already an existing

association then it replaces that instance If the Association Type is multiple then an error

is reported

bull Reuse Associations

This action creates an association unless it already exists If it does exist then the existing

association is reused

bull Delete Associations

This action deletes all associations that match the target (or source if inverse) Any targets

(or sources) that have no matches are silently ignored The targets (or sources) are not

deleted themselves

bull Delete SourcesTargets

This action deletes all matching targets (or sources if inverse) The associations

themselves are not directly deleted but will no longer be visible

To add an Association Action Request follow these steps

1 In the Query Editor select the node you wish to add an Association Action

Request to


3 Select Association Actions hellip A dialog showing the available association types

will open

4 Select the association type you wish to create one or more instances of

5 Select the type of action you wish to perform

6 Select the Add button


Sentences queries

345

7 The request is added You can then specify how the target should be determined

In the example shown we have derived the Date today but you could also bind

to an instance or another node in the same way that you may limit normal

forward requests

In the example shown it is then possible to add further Association Actions to the

existing one

The action to perform can be changed by opening the properties of the Action Request

Node

The Action Page allows you to change which action is performed

Firing triggers


were the only available mechanism to do so prior to Version 40 Update Queries are able

to fire Sentences Triggers to maintain this flexibility


Sentences queries

346


details of what was changed and why If a trigger is fired from an Update Query then this

information is included

It is also possible to directly request that a trigger is fired when an instance changes state

See the section Effector Triggers

To add a Trigger Request follow these steps

1 In the Query Editor select the node you wish to add a Trigger Request to


3 Select Trigger Actions hellip A dialog showing the available triggers will open



6 The Trigger Request will be added to the query node

Requesting a state change

You may desire to change the state of one or more instances related to a Request Node

When a state is mandated the desired effect is to change that instance to the given state

but it must be remembered that states are not set They are transient and are interpreted at

a moment in time by their Domains Predicate Query With an Effector Query what is

actually happening is the Effector Query attached to that State is being executed and it is

up to the designer whether the perceived state will actually change With a general Update

Query changing the state will trigger any Effector Query attached to that specified state

Again whether the state is actually changed depends on the designer

To add a Set State Request follow these steps

1 In the Query Editor select the node you wish to add a Set State Request to


3 Select Change State Action hellip A picker showing the available domains and

states will open

4 Select the desired state and the Set State Request will be added

Adding a message action

Update Queries can include Message Action Request nodes that are intended to inform

the current user of pertinent information The message can be classified as one of three

types Error Warning or Information If you specify a message type of Error then the

transaction will also be aborted


Sentences queries

347

The message can be sent to the existing Sentences Message Log a message dialog or

both Each message will produce a new row in the Message Log All messages will be

shown in one dialog together

To add a Message Action Request follow these steps

1 In the Query Editor select the node you wish to add a Message Action Request

to


3 Select Message Action hellip The new Message Request dialog will open

4 Select the desired type of message Error Warning or Information

5 Select the desired presentation Dialog Message Log or both

6 Enter an expression that will evaluate to the message This is a Sentences

expression and can use all the functionality available to existing Derived Type

nodes ndash for example referencing other nodes in the query

7 Select OK to add the request

There is a limit to the number of messages that can be sent to the current user in one

transaction See the Business Rules Reference section for details

Adding an email action

Update Queries can include Email Action Request nodes that are intended to send basic

textual emails The Sentences Server must be set up by a system administrator to use your

companyrsquos email service with one or more pre-defined From email addresses It will be

the application that is sending emails rather than an individual See the Business Rules

Reference section for details of how the email system should be set up

Once set up an Update Query can add an Email Action where the To cc Subject and

Message are derived by specifying query expressions This means that they can be

anything from a simple piece of literal text to a complex formula that evaluates to the

desired text


Sentences queries

348

The From field will be chosen from a predefined list set up by the system administrator

To add an Email Action Request follow these steps

1 In the Query Editor select the node you wish to add an Email Action Request to


3 Select Email Action hellip The New Simple Email Request dialog will open

4 Select the desired From email address

5 Enter expressions to define the To recipient(s) and the cc recipient(s)

6 Enter an expression that will evaluate to the subject

7 Enter an expression that will evaluate to the message body

These are all Sentences expressions and can use all the functionality available to

existing Derived Type nodes ndash for example referencing other nodes in the query

8 Select OK to add the email request

Grouping instances

Update Queries can include Group nodes In addition to simply grouping the results

additional actions can be performed on each group




For details of grouping actions see the ldquoGrouping resultsrdquo section below

Sandbox mode





details


Sentences queries

349

Grouping results

Version 40 introduces the ability to group results at different levels of the results tree By

adding a Grouping Node you specify an expression that is evaluated for every result and

those results with the same value are grouped together These are displayed in folders

To create a Grouping follow these steps

1 In the Request Query Editor select the

node that you wish to group the results

for This can be the Data Request Root

or any Forward or Inverse Request

2 From the context menu select Add and

from the cascaded menu select Group

3 A Grouping Request node will be

added to the query and the Expression

Editor will be opened for you to

compose an expression

In this example the expression evaluated for each event is the year of its date so events

are grouped by year

Grouping Requests also have the ability to act on those group members The default

behaviour is to list the group members but there are five actions that can be requested

The properties of a Grouping Request allow you to change the action

bull List group members

This default behaviour lists all the group members in a folder

bull List first group member only

This action only includes the first member of each group arbitrarily The other members

are not deleted they are ignored



Sentences queries

350

This action changes the instances in each group to be equivalent to one another and

displays all of them A query that contains a Grouping Request with this action will alter

data and becomes an Update Query


This action arbitrarily takes the first group member and uses it to supersede the other

group members Only this instance is included in the results A query that contains a



This action arbitrarily retains the first group member and deletes the other group

members Only the surviving instance is included in the results A query that contains a


bull Hide groups of one result

The Grouping Request hides any results that are groups of one by default If an action is

selected that results in a single item per group (list first supersede or delete duplicates)

then the checkbox is unchecked by default

If groups of one are not hidden then they appear as a direct child of the parent rather than

in a folder

The Human resources example profile that is shipped with Sentences contains a query

called Ages that demonstrates the use of a Grouping Request

Sandbox Mode





details

Reporting using SAP Crystal Reports

Version 40 introduces the ability to use the SAP Crystal Reports Software to connect to

Sentences as an XML Data Source

The exact method of connecting may differ between versions of SAP Crystal Reports but

the general outline is as follows

1 Start your copy of SAP Crystal Reports and start the Report Wizard or create a

new Data Source Connection

2 Select to create an XML Data Source

3 In the XML Data Source Connection properties elect to use an HTTP(S) Data

Source

This data source will be a URL to the Sentences XML Service in the Enterprise

Edition Installation It will be of the form

[http| https][serverport]SentencesXML[profile name] sect

[saved query]

eg

httplocalhost8090SentencesXMLAS Skills Register sect

Yearly Training Summary

4 Next specify an HTTP(S) schema This is the same as the XML URL except the

XML is replaced with the Schema URL

[http| https][serverport]SentencesSchema[profile name] sect

[saved query]


Sentences queries

351

5 By default the XML output from the Sentences XML Service is formatted into

HTML so you will also need to specify a query parameter ldquostylesheetrdquo with the

value ldquononerdquo

6 If the Saved Query requires any parameters then they must be defined here as

well

7 Once the connection is set up it can be used in SAP Crystal Reports in the same

way as other Data Sources to lay out reports


Sentences Version 40 introduced the concept of Display Name queries


Sentences interface A query can be used to define the ldquodisplay namerdquo of an entity or

association in place of the underlying data So for example rather than displaying

employees unique IDs imported from a Relational Database their first and last name can

be displayed

Creating a display name query

A display name query is no different from a standard query and can use all the available

functionality available to standard queries They cannot use functionality that is intended

for use in an Effector or Update Query as they do not execute in the context of a

transaction

In order to attach a query to a type that is to be used as a Display Name Query for that

type its data request type must be compatible with that type The first child of the data

request will be used as the display name This can be

The Target of a Forward Request

The Source of an Inverse Request or

The derived Target of a Derived Type Request

Any other supporting request nodes may be added to form the display name

For convenience the Query Editor provides the ability to add a Derived Type with the

name ldquoDisplay namerdquo as the first child and open the Expression Editor for you to create

the expression To do this select the Display name menu item from the Add menu

You can create a new Display Name query edit the existing query attach a different

query or detach the current query directly from the type in the schema pane

To create a new Display Name Query for a type follow these steps


2 Select the Schema menu and then select Createhellip from the Display Name


A new Display Name query will be created and attached to the type The Query editor

will be opened on the new Query for you to edit By default the Query will already

contain a Derived Type Request child for the type but you can amend the query as

normal


Sentences queries

352

To edit the existing Display Name Query for a type follow these steps


2 Select the Schema menu and then select Edithellip from the Display Name Query

cascading menu

The Query editor will be opened on the Query for you to edit

To attach a query to a type to be used as a display name query follow these steps


2 Select the Schema menu and then select Attachhellip from the Display Name


3 A dialog containing suitable queries will open Select the query you wish to

attach

To detach a display name query from a type follow these steps


2 Select the Schema menu and then select Detach from the Display Name Query

cascading menu

It must be borne in mind that the complexity of the calculation of a display name will

impact performance in the Sentences Explorer

Display names in Sentences

By default if a type has a Display Name Query then that display name will be used in the

Sentences Explorer and in Dataforms

When you open a Standard Dataform the title of the dataform and any fields for types

that have a Display Name Query will show the display name When you select the field to

edit then the underlying data will be shown When you exit that field the display name

will be shown again

When you create a Custom Dataform it is based on a standard Sentences query By

default nodes in a Sentences query do not use the Display Name Query attached to each

type

Custom Dataforms

Sentences queries

353

For each node in a query you may alter the properties to change the Display Name Query

to use

The properties allow you to select either ltDefaultgt ltNonegt or a suitable query

bull ltDefaultgt

This option will use the Display Name Query that is set for the Type

bull ltNonegt

This option will use no Display Name Query This is the default option for all query

nodes

Custom Dataforms

Custom Dataforms display a selection of associations defined by a query This is in

contrast to a base Dataform which automatically displays all the associations which have

the same source type You can use the Query Editor to define a query structure

specifically for use as the basis of a custom Dataform and you can display a custom

Dataform based on a query that you have created

To display the custom Dataform from the Query Editor select Custom Dataform from

the Dataform menu or click the Custom Dataform button on the Query Editor toolbar

To display custom Dataforms from the Sentences Explorer highlight an entity type and

select Dataforms from the shortcut menu and choose the specific Dataform you wish to

use from the sub-menu

To select or use a custom Dataform in the Explorer open the Properties dialog and select

the Custom Dataforms page For more information on selecting and using a custom

Dataform see ldquoCreating a custom Dataformrdquo Custom Dataforms can also be used with

the Dataform applet (see ldquoThe Dataform appletrdquo )



examplerdquo

Custom Dataforms

Sentences queries

354

You cannot use a query that includes a recursive or a transitive closure node for a custom

Dataform If you start a custom Dataform on a query that includes a recursive or a

transitive closure node Sentences displays an error message

Page Nodes

You can enhance the design of custom Dataforms by adding page nodes to your query

Page nodes do not have any effect on query results displayed in the Query Editor or the

Sentences Explorer or on CSV export You can define separate XSL Stylesheet options

for page nodes in a query which can effect the display of query results exported or viewed

as XML (see ldquoThe Query Editor and XMLrdquo )

Adding page nodes to your query allows you to group the query nodes When you display

a custom Dataform associations are displayed on tabbed pages according to the groups

you created in the query Page nodes can only display associations from the current level

of a query You cannot display a child association on a page node that is at a level above

that of its immediate parent unless it is part of a table display

Adding a page node

To add a page node highlight the data request node and select Add then Page from the

Edit menu You can type in a name for the page node when you create it You can also

rename a page node The name of the page node in the Query Editor becomes the name of

the tabbed page in the custom Dataform

Page nodes added automatically

The base dataform uses the following processes to create page nodes automatically

Associations that have the original selected type as their source are grouped beneath it and

not beneath a page node

When you use the Add Associations option on the Edit menu Sentences automatically

adds page nodes for any superset subset or equivalent types that are related to the

selected type and that are the source of one or more associations Sentences also adds a

page node for any instance specific associations All the associations which have one of

these related types as their source are grouped beneath the appropriate page node

Using page nodes

To ensure that a query node is displayed on a specific page drag the query node and drop

it onto the page node

Only page nodes that are immediately subsidiary to the data request node are used in the

Custom Dataform for the query Page nodes created at lower levels in the query are used

in child dataforms opened from the custom Dataform Child Dataforms opened on targets

or sources use the default Dataform for that type or the custom Dataform specified on the

Dataform page of the Query node properties dialog (see ldquoQuery node Dataform


Rules for page nodes display on the Dataform

The general rule for the display of page nodes in the dataform is that Sentences creates a

tabbed page in the dataform for each page node that has child nodes and displays the

tabbed pages in a left-to-right order that matches the top-to-bottom order of the page

nodes in the query

If the data request node of the query has any child nodes that are not allocated to page

nodes Sentences creates a tabbed page for the data request node This is known as the

default page The top-to-bottom order position of the first child node that is not allocated

to a page node in the Query Editor determines the left-to-right position of the default page

on the custom Dataform

Custom Dataforms

Sentences queries

355

If the data request node of the query does not have any child nodes that are not allocated

to page nodes then the default page displays only the name field for the type or the target

name if the data request is an association type If you do not add page nodes to your query

all the child nodes are displayed on the default page If there is a page node with the same

name as the data request node then the children of the page node and the unallocated

children of the data request node are displayed on the same page in the custom Dataform

This page is either a page created by the page node or a page created by the unallocated

child (or children) of the data request node depending on which comes first in the top-to-

bottom order of nodes in the Query Editor The order of associations on the Dataform

matches the top-tobottom order of nodes in the Query Editor

When a custom Dataform is displayed the tabbed page displayed to the user is known as

the active page On a create Dataform the active page is always the first page which

contains the instance name On an edit Dataform the active page is the one containing

data about the schema type selected in the schema pane On a child Dataform the active

page is the one with data about the instancersquos type

On a Dataform opened from the picker Applet the active page is the one containingdata

about the schema type specified in the LazyType=lttypegt parameter

Query node Properties dialog

You can display the query node Properties dialog for the root node of a query for other

data nodes and for page nodes Source and target data nodes do not have properties

To display the Properties dialog highlight the node and select Properties from the

shortcut menu or select Properties from the Edit menu or press Ctrl + p

bull Properties dialog for root nodes

The Properties dialog for the root node contains the Format properties page (see ldquoQuery

node Format properties pagerdquo ) and the XSL Stylesheet properties page (see ldquoQuery node

XSL Stylesheet properties pagerdquo ) If the root node is an association type the dialog also

includes the Dataform navigation properties page (see ldquoQuery node Dataform properties

pagerdquo )

bull Properties dialog for data nodes

The Properties dialog for data nodes contains the Format properties page and the

Dataform properties page If the node has a derivation set for it the Properties dialog

includes the Derivations properties page (see ldquoDerivation propertiesrdquo )

bull Properties dialog for page nodes

The Properties dialog for a page node contains the XSL Stylesheet properties page only

bull Properties dialog for derived type nodes

The properties dialog for a derived type node contains the Format properties page (see

ldquoQuery node Format properties pagerdquo ) and the Datatype properties page (see ldquoDerived

type node properties dialogrdquo ) The Read-only on Dataform property is always selected

on the Format page for a derived type and cannot be changed

bull Properties dialog for transitive closure nodes

The properties dialog for a transitive closure node contains the Format properties page

(see ldquoQuery node Format properties pagerdquo ) and the Transitive Closure properties page

(see ldquoTransitive Closure node properties pagerdquo )

Custom Dataforms

Sentences queries

356

Query node Format properties page

Figure 7-26 Query node properties dialog Format page

The Format page is available for the root node and other nodes in the query including

derived type nodes

This page is identical to the Format page which is available from the Sentences Explorer

for entity types and association types Format options chosen in the Query Editor apply to

the display of query results and to custom Dataforms based on queries The choices made

in the Query Editor override any choices made in the ExplorerIn the same way that you

can override the format properties of an entity type on an association type that targets the

entity type you can also override the format properties for a query node based on an

entity or association type

Sentences uses the formatting options you define for a node if the Output option chosen

for exporting or viewing XML results is Formatted If the Output option for XML

results is Unformatted the formatting options for the node are ignored For details of

each of the settings on the Format page see ldquoFormat properties pagerdquo

Effects of using the Restore Default Settings button

The effects of using the Restore Default Settings button vary according to the type of

node concerned

bull Entity type

Pressing the Restore Default Settings button for an entity type restores the format

properties to the defaults for the selected datatype (including the ltNonegt datatype)

bull Association type

Pressing the Restore Default Settings button for an association type restores the format

properties to the settings chosen for the target entity or association type If the target is an

association type the settings for its target are used (iteratively until there is a target which

is an entity type)

Custom Dataforms

Sentences queries

357

bull Query request node

Pressing the Restore Default Settings button for an query request node restores the

format properties to the settings chosen for the type that the request node is based on

bull Query derived type

Pressing the Restore Default Settings button for an query derived type restores the

format properties to the defaults for the datatype chosen on the Derived Type Datatype

Properties page

Query node XSL Stylesheet properties page

The XSL Stylesheet page on the properties dialog is available for the query root node and

for page nodes When you select View XML Results or Export XML Results and also

choose Generate as the XSL Stylesheet option Sentences uses the options defined on the

XSL Stylesheet properties page to create the stylesheet used for transforming the query

output (see ldquoXSL Stylesheet optionsrdquo )

The options selected for the query root node apply to the entire query output unless there

are page nodes which have their own XSL stylesheet properties defined

Where page nodes exist the settings defined for the page node only apply to the output of

the associations which are children of the page node and the settings for the query root

node apply to all the associations which are not children of page nodes

Figure 7-27 Query node properties dialog XSL stylesheet page

bull Layout

There are three options for the stylesheet layout

Horizontal layout (the default) gives a presentation in a simple table with multiple

associations shown as extra rows The first column of the table represents the root node or

page node with the node name as the column heading and the subsequent columns

represent the child associations of the root node or page node with the association names

(the verb names) used as the column headings Where the query results include multiple

associations each instance of the multiple association is shown on a separate row An

example of the Horizontal layout with the Show Grid option selected is given in Figure

7-28

Custom Dataforms

Sentences queries

358

Figure 7-28 Example of the Horizontal layout

Vertical (multiples in columns) gives a table presentation with multiple associations

instances shown as columns The first line of the table shows the name of the root node or

page node instance and subsequent lines show the child associations of the root node or

page node with separate columns for each instance of a multiple association An example

of the Vertical (multiples in columns) layout with the Show Grid option selected is

given in Figure 7-29 Please note that when you select Generate as the XSL Stylesheet



Custom Dataforms

Sentences queries

359

Figure 7-29 Example of the Vertical (multiples in columns) layout

Vertical (multiples in rows) gives a table presentation with multiple associations

instances shown as additional rows The first line of the table shows the name of the root

node or page node instance and subsequent lines show the child associations of the root

node or page node with additional rows for each instance of a multiple association An

example of the Vertical (multiples in rows) layout with the Show Grid option selected

is given in Figure 7-30 Please note that when you select Generate as the XSL Stylesheet



Custom Dataforms

Sentences queries

360

Figure 7-30 Example of the Vertical (multiples in rows) layout

When a query contains one or more page nodes you can define separate layout options for

each page node You may wish to experiment with the layout options to find the ideal

layout for your query results

bull Background colour

The background colour option allows you to select a background colour When you

choose the Select colour option the Choose colour button becomes active Click the

Choose colour button to select a colour from the colour palette

bull Show grid

Check the Show grid checkbox to display a table border around each table cell in the

query output

bull Show separator

Check the Show separator checkbox to display a separator line between each set of

results in the query output

bull Add printing page breaks

Check the Add printing page breaks checkbox to add a printing page break to the XSL

stylesheet When a results page based on a generated stylesheet is printed there is a page

break before each set of results produced by the node (except for the first set of results

produced by the data request node

Query node Dataform properties page

The Dataform properties page is available for nodes that are based on association types

and is used to define the behaviour of the associationrsquos target in a custom Dataform

Custom Dataforms

Sentences queries

361

To view the page select Properties from the Edit menu or from the shortcut menu on the

node

Figure 7-31 The Query node Dataform Properties dialog

The example shown in Figure 7-31 is for an association type node Next of kin that has

the target Person

You can set the following properties on this dialog



instances



Navigation





illustrated in Figure 7-31















Sentences queries

362

Transitive Closure node properties page

The Transitive Closure node properties page contains a single option to set the depth that

the closure should search to The default setting is unlimited

Figure 7-32 Transitive Closure node properties page


This section describes how you can use the Query Editor to create queries that generate

HTML containing graphical representations of data such as X-Y charts Pie Charts and

Distribution charts

If you have numerical data that you would like statistical information on such as

Averages Maximums and Minimums then the query editor has the ability to add these

top-level statistics

You can also amend queries with numerical data for graphical presentation This is done

using predefined XSL transformations and javascript libraries Sentences uses the jqPlot

javascript library For details see httpwwwjqplotcom The HTML and charts

generated by Sentences can be customised by creating a specific XSL transformation for

each chart that can take advantage of any of the jqPlot features and CSS styling available

Adding statistics to your query

You can add top level statistical results to an existing query by selecting the numerical

node that you wish to look at and which of the statistical group functions you would like

to apply

To add statistical functions to your query follow these steps


2 Select the Root query node and from the pop-up context menu select Create Top

Level Statisticshellip from the Chart cascading menu

The Create Top Level Statistics Dialog will open and a Node selection dialog will

appear

3 Select the Numerical node that you wish to perform the statistical functions on

and Click OK

4 When prompted choose whether or not you would like to create default node

names If so the selected node name and the function name will be used to

generate names for the top-level derived type nodes For example Amount


Sentences queries

363

Average would be generated from a Target node for the type Amount that is to be

averaged

5 Select or deselect each of the functions you wish to add

6 Optionally change the names of the top-level derived type nodes

7 Click OK to add the nodes

Figure 7-33 Adding statistical functions

Figure 7-33 shows selecting the second Value node to add statistical functions for The

first value node has already been added with the defaults

Making your query into an X-Y chart



that will output the data as an X-Y chart The only requirement is that there are two such

numeric child requests



2 Select the Root query node and from the pop-up context menu select Make X-Y



The query now specifies the XYChartxsl transformation


A Title

An X-axis label

A Y-axis label

Whether to show a trendline



Sentences queries

364


xaxis1Xaxis1

yaxis1Yaxis1





Note if the first two child requests are not numeric then the chart cannot be rendered If

you are using derived types remember to set the datatype to Number in the derived type

request properties

Figure 7-34 An example X-Y chart query with trendline

Making your query into a pie chart



that will output the data as a Pie chart It expects that the first request will produce the

labels and the second request will produce numeric values (they do not need to be

percentages) If the Data request represents the Labels then you can add a Derived Type

request that simply copies the value of each data result as in the example below



2 Select the Root query node and from the pop-up context menu select Make Pie



The query now specifies the PieChartxsl transformation

A top level derived type will be added so that the XSL can determine the chart

Title



xaxis1Xaxis1


Sentences queries

365

yaxis1Yaxis1





Figure 7-35 An example Pie chart query

Making your query into a distribution chart

Distribution charts work in two ways Either the data request itself contains the data that

are to be analysed or the first child (forward inverse or derived type) will be used It is

unlikely that the data request will contain duplicates and the purpose of this chart is to

count occurrences of individual items but it is still possible

It is much more likely that multiples of the first childrsquos target will occur If a forward or

inverse request is used then it can be singular or multiple

If a suitable child request is present then this will be used in favour of the data request

node

There is also a difference when the data are numeric or not If numeric then an interval

needs to be specified This is the width of the ldquobinsrdquo that will be created and several data

points will fit in each bin If the data are not numeric then each item will produce a ldquobinrdquo

and the value will be the number of occurrences

To change your query into a distribution chart follow these steps


2 Select the Root query node and from the pop-up context menu select Make

Distribution Charthellip from the Chart cascading menu


The query now specifies the DistributionChartxsl transformation


A Title

An X-axis label

A Y-axis label

Whether the x axis labels are numeric or not


Sentences queries

366

The data request is renamed ldquoDistributionChartrdquo

If there is a child request then it is renamed inputInput

Two derived type requests are created as children of the data request

DTIntervals

DTFrequency

The default value for the Title is the name of the query The default name for the X axis

label is ldquoDistributionChartrdquo or ldquoInputrdquo depending upon whether a child request is present

The default name for the Y axis label will be ldquoFrequencyrdquo Both labels can be changed to

something more meaningful The default value for ldquonumericrdquo is derived from the datatype

of the data request (or first request child) If the values are numeric but you wish them to

be treated as labels then you can modify this value to ldquordquo or remove the XLabels derived

type node altogether

The DTIntervals value is the ldquobinrdquo size when the data is numeric This defaults to 10 but

will need to be chosen to suit the data to show the desired level of granularity In the first

example with values in the 10000rsquos a DTInterval of 10000 or 5000 is appropriate In the

third example it has the value ldquoLabelsrdquo to indicate that each value will be a ldquobinrdquo

The DTFrequency does not need altering It is populated with the frequency when the

query is executed

When the query executes it is these two derived types that will contain the results of the

distribution analysis

Three examples are given

1 The Monetary value Entity Type as the Data Request to show the distribution of

all monetary amounts

2 The Monetary value Entity Type as the target of the association ((Employee

event Date) salary Monetary value) to show the distribution of salaries and

3 The Skill Entity Type as the target of (Resource skills skill Skill) to show the

frequency that each skill is associated with an Employee

Figure 7-36 Example 1 Data request distribution


Sentences queries

367

Figure 7-37 Example 2 Data request child distribution

Figure 7-38 Example 3 Non-numeric label distribution


Note Access to certain XML features is controlled by settings in the

Serverproperties file For information on how to check that the features you want

to use are enabled see ldquoServlet access to Sentencesrdquo

This section describes how you can use the Query Editor to create an XML document

which you can view or export to a file and to export an XML Document Type Definition

(DTD) More information on the ways in which you can use XML including how to use

XML to import data into a Sentences database is given in Chapter 8 ldquoSentences and

XMLrdquo You can also export a Sentences schema to XML (see ldquoExport Sentences schema

to XMLrdquo )

XML properties dialog

The XML properties dialog allows you to control the characteristics of XML output from

a query To set the XML properties for a query select Properties from the Query menu

and select the XML page The properties set in this way are the default for the query

The XML page shares the Properties dialog with the General properties page (see

ldquoGeneral query properties dialogrdquo )

Each time you select Export XML Results or View XML Results Sentences displays a

version of the XML properties page which allows you to modify the settings for current

execution of the query but does not change the defaults


Sentences queries

368

Figure 7-33 The Query Properties dialog XML page

Output options

You can use the Output options to control the way Sentences converts database entities

into character strings to be placed in XML elements

bull Format


bull Formatted output uses the formatting defined for each type in the database schema to

control the presentation of results data with each line of a multi-line presentation

represented as a _value element

bull Unformatted output does not apply any formatting and each type is shown in its input

format

For more details on these options see ldquoOutput Format parameterrdquo

bull Element identifiers

Some data request trees include references from one node to another for example when

you bind a node to another node or use recursive closure Select the Use element

identifiers property to ensure that each node has its own unique identifier (an ID

attribute) to make sure that links between nodes are properly referenced in your XML

output Elements with the ID attribute set can be referred to by other elements using the

IDREF attribute

Check the box to select this property By default this property is not selected For more

details about this parameter see ldquoElement IDs parameterrdquo

bull Include Sentences IDs

Every type or instance in a Sentences database has a unique internal identifier (surrogate)

that is usually hidden When you rename a type or instance the internal identifier remains

unchanged

Setting this property also allows an imported document to include lazyid attributes

where appropriate For more details see ldquoInclude Sentences IDsrdquo

Check the box to select this property By default this property is not selected

XSL Stylesheet options





Sentences queries

369




Sentences can automatically generate an XSL stylesheet for use with your query output

(see ldquoQuery node XSL Stylesheet properties pagerdquo )

Alternatively you can specify the URL of an existing stylesheet or use one of the

example stylesheets supplied with Sentences which can be found in the Stylesheets


You may choose one of the following options for XSL Stylesheets from the XML

Properties dialog

bull None

Choose None if you do not wish to apply an XSL stylesheet to your query results

DTD reference

You can use the DTD reference property to define the way your XML output is related to

a DTD For more information see ldquoDocument Type Declaration parameterrdquo

bull Generated

If you choose Generated Sentences automatically creates an XSL stylesheet for your

query output which takes account of any formatting rules you have defined and applies

the stylesheet to the query output before displaying the output on an HTML page This

option is not available if you select Unformatted as your Output option

Sentences takes account of the XSL stylesheet options defined for the query node and for

any page nodes when it generates a stylesheet For more details and for examples of

output see ldquoQuery node XSL Stylesheet properties pagerdquo

Cascading stylesheet

You can specify a full or relative URL for a cascading stylesheet (CSS file) A cascading

stylesheet applies formatting to HTML pages produced when query output is transformed

to HTML by an XSL stylesheet

Sentences provides a default CSS file in the

ltSentences_homegtTomcat4webappsSentencesCSS directory You may add

additional CSS files to this location

The default CSS file is named QueryResultsStylesheetcss This stylesheet is set

automatically for new queries but not for existing queries

You can reference the URL for cascading stylesheets in this location as shown in the

following example

CssQueryResultsStylesheetcss

bull Server







Sentences queries

370


You may select a stylesheet that you have previously exported from Sentences (see

ldquoExport XSL stylesheetrdquo ) if it is available in the Stylesheets directory location on the

server

bull URL



Node name considerations for XML output

The name of the XML document is based on the name of the data request node at the root

of the query tree The name of each element defined in the DTD and appearing in the

XML document is based on the name of one of the request nodes in the query tree By

default these names are based on the names of the entity and association types on which

they are based

By default both the name of the file containing your XML document and the name of the

root element of the XML document itself are based on the name of the query You can

name your query with this in mind

You can determine the name of any of the child elements in the XML document by

changing the name of the corresponding request node in your query

Element type names in XML must conform to restrictions not required in Sentences

queries XML element names may contain only letters numbers and periods Spaces in

Sentences query node names are converted to periods when they are used as XML

element names

Create an XML DTD from a query

To export a query definition as an XML DTD select Export XML DTD definition from

the Results menu Sentences displays the File dialog Select the directory and file name

for your Document Type Definition and click Save You can view the resulting DTD in a

text editor as shown in Figure 7-35

ltxml version=10 encoding=UTF-8gt

lt-- DTD generated by Sentences --gt

ltELEMENT Currentemployees (Person) gt

ltELEMENT Person (_value+ lastjoined) gt

ltATTLIST Person action (create | reuse | required | delete) reusegt

ltELEMENT lastjoined (PCDATA) gt

ltELEMENT _value (PCDATA) gt


Sentences queries

371

Figure 7-35 An XML DTD

Export query results as XML

To export the results of a query as XML select Export XML results from the Results

menu Sentences displays a Properties dialog similar to the one illustrated in Figure 7-33

Select the properties you want for your results and click OK

If the query includes any parameters Sentences displays the Parameters dialogSentences

then displays the File dialog Select the directory and file name for your XML file and

click Save You can view the resulting XML in a text editor as shown in Figure 7-36

Figure 7-36 XML results viewed in a text editor

Export XSL stylesheet

To generate an XSL stylesheet which matches the query definition without exporting the

results of the query select Export XSL stylesheet from the Results menu


Sentences queries

372

Sentences displays a file dialog which allows you to specify a location on your client

machine for saving an XSL stylesheet based on the query definition which Sentences

generates automatically

View query results as XML

To view the results of a query as XML select View XML results from the Results menu

Sentences displays the XML Properties dialog as shown in Figure 7-33

Select or modify the properties you want for your results and click OK If the query

includes any parameters Sentences displays the Parameters dialog

When Sentences processes the query it produces the results as a machine-readable XML

data stream You may choose to convert the XML data stream into a more readable

format using an XSL stylesheet as described in ldquoXSL Stylesheet optionsrdquo

If you do not wish to use an XSL stylesheet the display of the XML data depends on

which browser you are using and on how your browser is configured to handle XML data

streams Some Web browsers can automatically create a human-readable display of an

XML data stream For example some versions of Internet Explorer display XML data by

default as a colour-coded and indented display of both tags and data (as shown in Figure

7-37) while Netscape 62 displays XML data by default as an unformatted display of data

only

Figure 7-37 Example of unformatted XML results viewed in Microsoft Internet Explorer

You can greatly improve the readability of the XML output by specifying formatting

instructions You can do this by using either or both of the following methods

bull setting formatting properties on query nodes see the section ldquoQuery node Format

properties pagerdquo for more details

bull specifying an XSL stylesheet see the section ldquoXSL Stylesheet optionsrdquo for more details

Example stylesheets

Sentences supplies two example stylesheets in the ltSentences_homegtStylesheets

directory


Sentences queries

373

Masterxsl example stylesheet

The example shown in Figure 7-38 shows XML results formatted with the example

stylesheet masterxsl This stylesheet specifies HTML output

Figure 7-38 XML results formatted with the masterxsl example stylesheet

The example shown in Figure 7-39shows XML results formatted with the example

stylesheet tablexsl This stylesheet specifies HTML output


Sentences queries

374

Tablexsl example stylesheet

Figure 7-39 XML results formatted with the tablexsl example stylesheet






allows you to sort and select data from the Sentences database before you export it

Running CSV Export

The CSV Export mechanism for queries is based on the type structure of the data request

The same data structure is applied to all the results derived from the query and instances

where associations do not exist are represented in the CSV file by empty values (ldquonullsrdquo)

Derived type nodes may be included in the exported query result as long as they are not

at the top level of the data request If there is a top level derived type node Sentences

cannot complete the CSV export operation and displays an error message

Hidden nodes are not included in the data that is exported

Sentences creates column headings in the resulting CSV file which are based on the node

names in the query structure

To export the results of a query open the query in the Query Editor or select the query in

the Sentences Explorer Queries folder


Sentences queries

375

Select the Export to CSV filehellip command from the Results menu In the Sentences

Explorer this command is on the Resultshellip submenu of the Query menu and also on the

shortcut menu for the query

Sentences displays a standard Open File dialog for your operating system Navigate to

the file location you require type in a name for your CSV file and click Create

You can view the contents of your CSV file using a text editor or some

spreadsheetprograms

CSV Export and multiple associations

There is a limit on the way Sentences exports the results of queries that include multiple

associations Only one multiple association can be exported in any given query and it

must be the last node of the exported query If there are two or more multiple association

nodes that share the same parent node Sentences cannot complete the CSV export

operation and displays an error message Similarly if the multiple association node is

followed by any other node Sentences cannot complete the CSV export operation and


If the data you wish to export includes a number of multiple associations you must

construct a number of separate queries each containing only one multiple association For

information on how to import multiple CSV files into one Sentences database see ldquoCSV

Importrdquo

Introducing XML

Sentences and XML

377

Chapter 8

Sentences and XML

This chapter introduces XML and explains how Sentences and XML can be used

together The topics described in this chapter are

bull Introducing XML

bull XML Support in Sentences

bull XML input and output methods

bull Exporting a Sentences schema to XML

bull Sentences XML conventions

bull Setting XML options in the Query Editor

Introducing XML

XML is the Extensible Markup Language which is the universal format for structured

data and documents on the Web developed under the auspices of the World Wide Web

Consortium (W3C) More information about XML and the complete XML standard is

available from the W3C Web site

httpwwww3corg

XML Terminology

This section provides an introduction to some of the technical terms used when discussing

XML documents and XML processing

Well-formed XML

An XML document is well-formed if it meets the well-formedness constraints defined in

the XML 10 recommendation A document which is not well-formed cannot truly be said

to be an XML document at all The rules for XML documents include the requirement

that every start-tag must be matched by the corresponding end-tag and that any element

started between a pair of start and end tags must also finish between them

The DTD

A Document Type Definition (DTD) is a series of statements that define the structure of

an XML document The DTD can be part of the document (an internal DTD) or the

document can refer to an external DTD The DTD lists the elements that are permitted in

the document and the sequences in which elements may occur

The XMLSchema

XML Schema replaces Document Type Definitions with a way of defining the structure

of an XML document that is itself XML The XMLSchema cannot be part of the

document The XMLSchema lists the elements that are permitted in the document the

sequences in which elements may occur and additional datatype information amongst

other things far in advance of a DTD

Valid XML

To be valid an XML document must meet the validity constraints defined in the XML 10

recommendation It must not only conform to the rules of the XML grammar which make

it well formed but it must also conform to the document structure laid down in a DTD A


Sentences and XML

378

valid XML document must contain a document type declaration that refers to the DTD for

that document

Elements in XML

An XML document contains one or more elements where an element is either text

delimited by a start-tag and an end-tag or an empty-element tag by itself

Here is an example of a start-tag and an end-tag

ltEmployeegt ltEmployeegt

Start-tags and end-tags consist of a name enclosed in angle brackets (less-than and

greater-than signs) The name is the name of an element type and must be identical in

both tags

Everything between the start-tag and the end-tag is the content of the element which may

consist of a mixture of text and other elements Elements can be nested to any depth but

they must not overlap

Attributes in XML

A start-tag may also contain attributes in the form of name=value pairs as follows

ltimg src=imagesbarneyjpggt

where img is the element type src is the attribute name and

imagesbarneyjpg is the value of the attribute

You can create a well-formed XML document using any names you choose for elements

and attributes For your XML document to be valid the element and attribute names and

the arrangement of elements must conform to the declared DTD

Extensible Stylesheet Language (XSL)

The Extensible Stylesheet Language (XSL) is a language for expressing stylesheets It is

similar in its conception to the Cascading Style Sheets language (CSS) used in HTML

but it is far more powerful

The XSL language consists of two parts

bull XSL Transformations (XSLT) a language for transforming XML documents

bull An XML vocabulary for specifying formatting semantics (XSL Formatting Objects)

Sentences does not use XSL Formatting Objects All references to XML stylesheets in

Sentences and its documentation refer to stylesheets using the XSLT language to express

XSL Transformations


The support for XML in Sentences Version 40 allows you to

bull export a Sentences schema to XML

bull generate an XML Document Type Definition (DTD) from a query

bull generate XML documents from the Sentences database using the structure defined by

the DTD and either save them in files or send them to a browser

bull return a generated XML DTD or XML document in response to an HTTP request

bull read externally-generated XML documents whose structure matches the DTD and

import the data into Sentences





Sentences and XML

379




Sentences Version 40 does not currently support the proposed XML Schema standard








Sentences Version 40 does not currently support the XML Schema standard other than to

provide an XMLSchema servlet that can be used with SAP Crystal Reports

You can export a Sentences database schema to an XML file This file can be saved or

viewed in a browser window This process is similar to the export of query results to

XML (see ldquoThe Query Editor and XMLrdquo )

When you select Export Schema to XML or View Schema in XML from the Schema

menu Sentences displays the XML Properties page which allows you to define XML

properties

Figure 8-40 The XML properties dialog for schema export

Output options for XML export of schema

The Output options control the way Sentences converts database entities into character

strings to be placed in XML elements

bull Format


bull Formatted

Association type names are displayed as source verb and target


Sentences and XML

380

bull Unformatted

Association type names are displayed as verbs only

XSL Stylesheet options for XML export of schema







You can specify the URL of an existing stylesheet or use one of the example stylesheets

supplied with Sentences which can be found in the Stylesheets directory of your


The option to Generate an XSL stylesheet which is available when you export the results

of a Sentences query as XML is not available when you export a Sentences schema as

XML Choose one of the following options for XSL Stylesheets

bull None

Choose None if you do not wish to apply an XSL stylesheet to your query results You

cannot specify a DTD reference when you export a Sentences schema to XML

bull Server







bull URL




There are a number of methods for getting data from XML documents into and out of

Sentences as follows

bull using the Query Editor


Sentences and XML

381

bull using a servlet

bull using command-line tools

bull using the Sentences API

Note Only the command-line tools and the Query Editor are available in the Sentences

Personal Edition

Importing XML data

You can import data from an XML document into a Sentences database when the XML

document conforms to a DTD generated from a Sentences query You cannot import data

from arbitrary XML documents into a Sentences database

Using the Query Editor

The Sentences Query Editor is the principal tool for creating XML structures that can be

used for exchanging data between Sentences and XML documents To create an XML

document from Sentences you must first create a Sentences query

Sentences uses the data request structure of the query tree to produce a DTD Sentences

produces an XML document from the query which conforms to the DTD produced from

the queryrsquos structure The XML document contains the same data as the result of the

query

The Query Editor has commands to

bull retrieve the DTD corresponding to a query and save it to a file


save the resulting document to a file


display the results in the users browser

For details of how to use these commands in the Query Editor see ldquoThe Query Editor and

XMLrdquo

Note XML documents and DTDs cannot be created from Set Queries

Using Servlets





Using a servlet to access a generated DTD

Access to some XML features is available through the servlet mechanism Sentences

generates DTDs as they are required and does not store them The Sentences Enterprise

Edition includes a special DTD servlet for this purpose

Note In the Sentences Personal Edition you can only use the DTD servlet URL internally

with the XML Import command-line program


Sentences and XML

382

You can access a generated DTD by specifying a URL which defines the profile name

and the name of a stored query for which the DTD specification is required

The following is an example of a URL to access a DTD

httplazyws308090SentencesDTDHuman20resourcesEmployeeQuery

In this example






DTD indicates that a DTD is required and routes the

request to the Sentences DTD servlet



EmployeeQuery is the name of the stored query whose DTD is

required

When you retrieve a DTD using a servlet there is no provision for specifying parameter

values as they cannot affect the DTD

Using a servlet to access XML





The Sentences Enterprise Edition includes an XML Export servlet which accepts URLs to

generate XML documents from stored queries An example of this kind of URL is as

follows

httplazyws308090SentencesXMLHuman20resourcesEmployeeQuery

in which






XML indicates that XML output is required and routes

the request to the Sentences XML servlet



EmployeeQuery is the name of the stored query whose DTD and

XML results are required


Sentences and XML

383

You can use an HTTP GET request with this URL to execute the query without supplying

any parameter values This generates an XML document without a document type

declaration and without any stylesheet processing You can add parameter values to

generate a document type declaration or stylesheet processing or both

Adding parameter values to servlet requests

You can add parameters to servlet requests to supply values for the parameters used in the

query and to control the way the output document is generated

There are two ways of supplying parameter values to servlet requests You can extend an

HTTP GET request with a query string consisting of name=value pairs like this

httphellipEmployeeQueryProject=CRM+developmentampSkill=Java

Alternatively you can supply the name=value pairs using an HTTP POST request for

example from an HTML form

Parameter names are not case sensitive If parameter names or values contain spaces or

other special characters Sentences uses normal URL encoding In the example URL

shown above the space in the profile name CRM development is replaced by a ldquo+rdquo sign

as in CRM+development

Some specific parameter names are used to control the XML generation process and

should not be used for parameters within queries that are to be accessed with this XML

mechanism These parameters which are described in the following sections are

stylesheet doctype format elementids and lazyids

Each of these reserved parameters corresponds to an option that can be set and saved for a

Sentences query using the Query Properties dialog (see ldquoXML properties dialogrdquo ) If

you supply a parameter value with the HTTP request it overrides the parameter value

saved with the query

bull Stylesheet parameter

Sentences can produce results in XML HTML or text format according to the stylesheet

specified The stylesheet parameter specifies the stylesheet processing on the XML

results returned from a saved Sentences query

The format of the stylesheet parameter may be one of the following

stylesheet=ltstylesheetURLgt

where ltstylesheetURLgt

represents thefull or relative URL

from which thestylesheet can be

retrieved

stylesheet=generated

Sentences uses an XSL

Stylesheetgenerated automatically

from the query

stylesheet=none no XSL stylesheet is used

For more information see ldquoQuery node XSL Stylesheet properties pagerdquo and ldquoXSL

Stylesheet optionsrdquo )If you specify a stylesheet URL you may either specify an absolute

URL or use a URL that is relative to a fixed base which is defined by the

StylesheetURLBase parameter in the Serverproperties file

When the stylesheet parameter is used Sentences retrieves the stylesheet or

generates a stylesheet and uses it to process the query results which are then returned as

the response from the servlet


Sentences and XML

384

Note Stylesheet processing is handled by the Sentences XML servlet not by the browser

A specified stylesheet must conform to the XSL Transformations specification The

content type of the resulting document is applicationxml unless the stylesheet

includes an xsl-output element defining a method of html or text For example a

stylesheet used to generate an HTML page from an XML document should start like this

ltxml version=10gt

ltxslstylesheet xmlnsxsl=httpwwww3org1999XSLTransform

version=10gt

ltxsloutput method=html gt

You can set the content type of your processed XML document to texthtml by setting

the stylesheet output method to html You can set the content type of your processed

XML document to textplain by setting the stylesheet output method to text

The Xalan stylesheet processor supplied with Sentences automatically switches the output

mode to HTML if the first element generated is ltHTMLgt but by itself this does not

produce a document with a content type of texthtml

bull Document Type Declaration parameter

You can use the doctype parameter to specify the location of the Document Type

Declaration which is required for XML results returned from a saved Sentences query

There are three possible values for this parameter

doctype=external The XML file contains a reference to a DTD

located by an external URL for example

ltDOCTYPE root-element SYSTEM

httpgt

doctype=internal The DTD is embedded in the XML document

A simple example would be

ltDOCTYPE people [

ltELEMENT people (Person)gt

ltELEMENT Person (PCDATA)gt

]gt

doctype=none The XML file does not refer to a DTD at all

If you wish to export an XML document that you later wish to import into a Sentences

database you must set the doctype parameter to external

bull Output Format parameter

You can use the format parameter to specify the format of the text included in each

element This may have one of two possible values

formatted (default) Uses the formatting defined in the schema and

query Entities with multi-line presentation are

represented as a list of _value elements as

described in ldquoSplit multiple linesrdquo

This setting is recommended if you want to convert

the XML into HTML

unformatted Formatting is not applied and each entity is shown

in its input format Each entity maps to a single

element and new lines are included in the text Use

this setting when you want to import your XML

output into another application or database


Sentences and XML

385

bull Element IDs parameter

You can use the elementids parameter to specify whether Sentences includes an XML

ID attribute on every complex element (see ldquoUsing Element IDsrdquo 7) The possible values

for this parameter are elementids=true and elementids=false

bull Sentences IDs parameter

You can use the lazyids parameter to specify whether Sentences includes internal

identifiers with every complex element (see ldquoInclude Sentences IDsrdquo 6) The possible

values for this parameter are lazyids=true and lazyids=false

bull htmlerror parameter

You can use the htmlerror parameter to specify whether Sentences displays any error

(for example the query doesnrsquot exist or you didnrsquot enter a mandatory parameter) in html

for a more user friendly response The detailed error is hidden and can be expanded but

the message is usually self-explanitory

XML import using a servlet

You can import data from an XML document into Sentences if that document references

and conforms to the DTD that would be generated from a saved Sentences query

You can then configure the Enterprise Edition of Sentences to accept an XML document

using an HTTP POST request The URL for the XML import is fixed for each Sentences

installation for example

httplazyws308090SentencesImportXML

where

http indicates the protocol being used


Sentences identifies the servlet context defined for the


ImportXML routes the request to the Sentences

ImportXML servlet

Note The host name port number and servlet context may vary from one Sentences

installation to another

The DTD that the imported document refers to must be specified as the URL of the DTD

generated from the required Sentences query This URL must refer to exactly the same

host name port number and servlet contexts that are used in the URL for the XML

Import Sentences re-generates the DTD and uses it to validate the incoming document If

the query has changed since the DTD used as a template for the import was exported the

import fails

If the incoming document specifies a stylesheet to be applied before the incoming data is

parsed the stylesheet must specify the appropriate URL for the DTD The nature of the

imported data and where it is stored are determined by the DTD referenced by the

imported document which specifies the Sentences profile and query name which are

used

Importing XML does not use parameter values as they cannot affect the import process

Stylesheet Processing

An XML document that is imported into Sentences may contain a processing instruction

to specify a stylesheet to be applied to the incoming data before it is parsed For example

it may refer to a stylesheet as follows

ltxml-stylesheet type=textxsl href=emplistxslgt


Sentences and XML

386

The stylesheet name is a URL which is either absolute or relative to the location defined

for StylesheetURLBase property in the Serverproperties file

XML Import and triggers

Whenever you use the ImportXML command Sentences checks whether there are any

triggers in the schema that are attached to the entity types affected by the import Any

triggers found are run on the data that is being imported This may affect the data that is

imported or may cause the import procedure to stop before it is completed

You can define an entity type in Sentences to have its instances named by a trigger (see

ldquoInstance name created by triggerrdquo ) When you are using XML Import with data that

includes this kind of entity type you must allow for the creation of the entity name by

including an empty value string in the format

ltvaluegtltvaluegt

If this value string is not empty the trigger produces an error message and the import

fails

XML Import in multi-user environments

Sentences does not check for the possibility of parallel updates when a database is

updated using XML Import It is possible that in multi-user environments updates may

have been made to the database between the time that an XML Export was performed and

the time that a corresponding XML Import was performed

XML Import and derivations

Using XML Import has the same effect as selecting an instance and opening a custom

Dataform for it and then updating association targets Amongst other things this means

that any Calculate once derivations that would be shown on a custom Dataform are

updated when you use XML Import If the derivation is part of the target of a multiple

association type then the derivation for each existing target instance is calculated as well

as the derivation for any instance created or updated by XML Import

Mapping XML Data

Every element in an imported XML document is mapped to an instance in the Sentences

database By default Sentences uses an existing instance where one exists If no suitable

instance exists Sentences creates a new instance

The following mappings are used

entity instance an existing entity instance with the same name

association instance an existing association instance linking the same

source and target

Action attributes

You can force the XML Import process either to create a new instance or to reuse an

existing instance by including an action attribute on the XML element as follows

ltPerson action=creategt

The default value for the action attribute is reuse The possible values for the action

attribute are as follows

action=create Creates a new instance for this element regardless

of whether a suitable instance already exists This

can create duplicates which are not permitted with

singular association types resulting in an error

To avoid this error use set rather than create

with singular association types


Sentences and XML

387

action=set If no instance exists set creates an instance If an

instance exists set overwrites it Set may only be

used with singular association types

action=reuse Refers to an existing suitable instance if there is

one and create a new instance otherwise This is

the default

action=required Refers to an existing instance If a suitable instance

does not exist then the import process fails You can

refer to an instance created earlier in the same

import process

action=rdquodeleterdquo Deletes an existing instance If a suitable instance

does not exist then the import process fails

You can use the action attribute on an element representing an entity which is not a

value or on an element representing an association You cannot use the action attribute

on elements representing values

If the XML document being imported is based on a query that uses Sentences IDs you

can require the use of a particular instance or delete a particular instance by including its

Sentences ID as a lazyid attribute as follows

ltPerson lazyid=223478gt

See ldquoInclude Sentences IDsrdquo for more information on using Sentences IDs

Do not use the action=required attribute with the lazyid attribute If the type

identified by the given Sentences ID cannot be found or if it is not an occurrence of the

correct Sentences type then the import fails

You can use the lazyid attribute on an element representing an entity which is not a

value or on an element representing an association You cannot use the lazyid

attribute on elements representing values

If the XML document being imported is based on a query that uses Element IDs then any

complex element in the imported document can be replaced by a reference element

referring to an earlier element of the same type See ldquoUsing Element IDsrdquo for details

Using command line tools

You can use a command line program to perform an XML export or an XML Import with

the Sentences Enterprise Edition or the Sentences Personal Edition Like the other

Sentences command-line tools these programs require exclusive access to the Sentences

database This means that the Sentences server or the Sentences Personal Edition

application must be closed down before you can use this command line procedure

XML Export using the command line

The command line for XML export looks like this

ExportXML [options] ltprofile namegt ltquery namegt

where ltprofile namegt is the name of a Sentences profile and ltquery namegt is the

name of a saved query in that profile and[options] includes any of the following

optional settings

-file ltoutput file namegt Specifies an output file By default the results

are written to standard output

-stylesheet ltstylesheet file namegt Specifies stylesheet processing (see

ldquoStylesheet parameterrdquo )

-parameter name=value Supplies a value for a query parameter (see

ldquoAdding parameter values to servlet

requestsrdquo ) This option can be repeated as

many times as necessary


Sentences and XML

388

-doctype[external|internal|none] Specifies the type of document type

declaration required (see ldquoDocument Type

Declaration parameterrdquo 5)

-format [formatted|unformatted] Specifies a format mode(see ldquoOutput Format

parameterrdquo )

-elementids [true|false] Defines the use of element IDs (see ldquoElement

IDs parameterrdquo 6)

-lazyids [true|false] Defines the inclusion of Sentences IDs (see

ldquoSentences IDs parameterrdquo )

Note that option names and parameter names are not case sensitive If a parameter name

or value includes spaces or an equals sign the whole name=value pair should be

enclosed in quotation marks for example

-parameter Customer name=John Smith

XML import using the command line

The XML Import command-line procedure can be used for importing data into the

Enterprise Edition in batch mode without the need to configure the XML Import servlet

or to set up security for it The command-line procedure can also be used with the


The command line for Import XML looks like this

ImportXML -file ltinput file namegt

where ltinput file namegt specifies the input file name

Any document that you import must include a reference to a DTD It may also have a

reference to a stylesheet The DTD reference should refer to a saved Sentences query and

should have the following format

httplocalhostSentencesDTDHuman20resourcesEmployeeQuery

where

httplocalhostSentencesDTD is fixed and must appear exactly as shown

(except that any port number present is ignored) and

Human20resourcesEmployeeQuery is an example of a profile name and a stored

query name Note that this URL may differ from that in the XML which would be

exported from the same query using an external DTD

When you use the command line XML import procedure Sentences generates the DTD

from the specified query and passes it to the XML parser to validate the document There

is no actual network access involved

Online importing

When you are using the Enterprise Edition you may wish to make occasional data imports

from XML documents without stopping the server If the XML Import servlet is running

you can import data from XML documents by making HTTP POST requests using any

suitable client tool For more details about the HTTP POST request seeldquoXML import

using a servletrdquo

Using the Sentences API

You can use the Sentences API for a number of XML related tasks including

bull defining a query

bull executing a query to return Java objects for use in the program

bull sending the corresponding DTD to a supplied output stream


Sentences and XML

389

bull executing the query and sending the results as an XML document to a supplied output

stream

bull executing the query to generate an XML document applying a stylesheet to it and

returning a URL which can be used to retrieve the resulting document

You cannot use the Sentences API for XML import tasks For more details about using

the Sentences API see Chapter 10 ldquoCustomising Sentencesrdquo

Using alternative parsers and stylesheet processors

Sentences is built with the Xerces XML parser and the Xalan XSL transformation engine

both of which have been developed by the Apache Software Foundation Sentences

accesses the transformation and parsing capabilities by using the Java API for XML

Processing (JAXP) standard published by Oracle

You can use an alternative parser or transformation engine by including the appropriate

JAR files on the servlet containers classpath in place of the JAR files supplied

When using the current version of Xerces with Sentences you must specify the class

name for XML parsing in the XmlParserClass property in the Serverproperties

file for example

XmlParserClass= orgapachexercesparsersSAXParser


Sentences uses a number of simple rules to generate XML and XML documents to be

imported into Sentences must follow the same rules If you wish to import data from an

XML document that does not conform to these rules you must create your own stylesheets

to map data using other conventions

The rules are described in the following sections

Use content not attributes

All data is held as content not attributes For example a persons telephone number must

appear as content like this

lthometelephonegt(210) 182 0932lthometelephonegt

It must not appear as an attribute like this

ltPerson hometelephone=(210) 182 0932gt

Using content results in a slightly longer representation than using attributes but it allows

for the possibility that each data value can have its own attributes

Associations appear as child elements

Associations linked to an entity or association appear as child elements of the element

corresponding to that entity or association The sample of XML output in Figure 8-1 is an

extract of employee data from the example Human resources example application and

shows associations linked as child elements


Sentences and XML

390

Figure 8-1 Example of XML output

The employees e-mail address is held in Sentences as an association and so it appears as

a child element Similarly employment events are held as associations of type

(Employee event Date) which have associations of their own in turn The event

element has a child called Date to hold its target alongside other child elements such as

event1 and jobtitle representing associations sourced on the association (Harold

Ferny event 1197)

Mixed content is not allowed

All element types are declared to have either element content or character data but not

both This ensures that the validation of imported XML documents provides a useful

check against the structure that Sentences is expecting

This rule means that where a Sentences entity has both its name and associations

included in the XML document then a new element must be created to hold the name

This element is always called _value The Employee entity in the Figure 8-1 shows

this

Derived element type names

Element type names in an XML document must follow the rules laid down in the XML

recommendation Only a restricted set of characters are allowed and names must be

unique within a document type Sentences derives element type names from query node

names which are not restricted in this way Sentences uses a simple mapping algorithm to

do this

bull if the name does not start with a letter an X is inserted at the beginning

bull any characters other than numbers letters or spaces are removed

bull all spaces are replaced by period (ldquordquo) characters

bull if the resulting name clashes with a name already used in this document type a number

is appended to make it unique

The effects of these rules can be seen in the Figure 8-1 for example event1 which is

distinguished from event and jobtitle which has a period separating the words

instead of a space

Split multiple lines

Multiple lines of data may appear as multiple elements If the format mode (see ldquoOutput

Format parameterrdquo ) is set to formatted then any entity type whose presentation is

multi-line text box has its values split into lines and each line appears as a separate

_value element as shown in Figure 8-2

ltEmployeegt

lt_valuegtHarold Fernylt_valuegt

ltemailaddressgtmailto fernyhsleepysoftcomltemailaddressgt

lteventgt

ltDategt01011997ltDategt

ltevent1gt

ltEventgtJoinedltEventgt

ltevent1gt

ltjobtitlegt

ltJobtitlegtJunior Systems AdministratorltJobtitlegt

ltjobtitlegt

ltsalarygt$35000ltsalarygt

lteventgt

ltEmployeegt


Sentences and XML

391

Figure 8-2 Example of _value elements in XML output

This format makes it possible to display the data in an HTML page with line breaks in

appropriate places which would not be possible just by including line breaks in the data

since these are not significant in HTML

If the data is not intended for mapping into HTML you may want the address text as a

single element If the format mode is set to unformatted the same data appears as

follows

ltaddressgt116 South Alfred Streetampx0aBrooklynampx0aNY 11217ltaddressgt

Line breaks in the data are shown as ampx0a which is the XML representation of a line-

feed character

Allow the action attribute

When you import data you may want to specify whether an element should cause a new

Sentences instance to be created or not See ldquoMapping XML Datardquo 8 for a description of

the use of the action attribute to control this The DTD generated for a Sentences query

always allows for the inclusion of an action attribute on every element where it applies

except for those corresponding to value types

Include Sentences IDs

You may want to configure an application program to use XML Export to retrieve data

from Sentences and then to use XML Import to make changes to Sentences For this to

work successfully you must make sure that the import process uses the same specific

instances referred to in the exported data You can do this by including Sentences IDs in

the XML document See ldquoSentences IDs parameterrdquo 6 and ldquoMapping XML Datardquo for

details of how achieve this

The lazyid attribute is optional for importing data

Combining simple elements

Sentences combines simple elements that is elements with no child elements with their

parent elements where appropriate This happens in two types of situation

bull If an entity type has no associations included in this query and it is not being split into

multiple lines Sentences does not use the _value element The name of each instance

appears as the content of the corresponding element For an example see the Date entity

type which appears as the target of (Employee event Date) in the Employee example

shown in Figure 8-1

bull If an association type has no associations included in this query and its target is a value

then the target is combined with the association The emailaddress element in the

example in Figure 8-1 shows this The full association type is

(Employee email address Hyperlink) but as there are no dependent association types

Sentences does not use the Hyperlink element

Using Element IDs

A deeply-nested query may include information about the same instance more than once

and the XML standard provides a way to avoid repeated data by allowing an element to

ltaddressgt

ltAddressgt

lt_valuegt116 South Alfred Streetlt_valuegt

lt_valuegtBrooklynlt_valuegt

lt_valuegtNY 11217lt_valuegt

ltAddressgt

ltaddressgt


Sentences and XML

392

have an attribute of the type id which identifies it uniquely within the document and

other elements to refer to it by means of attributes of the type idref

You can ask Sentences to include element IDs and to refer to them where appropriate by

setting the Use Element IDs option on the query (see ldquoElement IDs parameterrdquo ) This

option applies to all complex element types but not to simple element types (see

ldquoCombining simple elementsrdquo )

Including Element IDs has two effects as follows

bull Every element containing data has an id attribute which is a label generated by

Sentences for example

ltEmployee id=N1gt

lt_valuegtBarney Norrislt_valuegt

bull Wherever this element type can appear it may be replaced by a reference element

which contains no data but uses a ref attribute to refer to an earlier node for example

ltreferencetoEmployee ref=N1gt

In most cases this just serves to reduce the size of the document but sometimes it is

essential to prevent an infinite loop Whenever an indirect query node occurs both it and

the node it refers to always use element IDs to avoid the possibility of an infinite loop

occurring

When the Include Element IDs option is set on a Sentences query an XML document to

be imported can also include ID attributes and use reference elements to refer to the

earlier elements


You can use the Query Properties dialog in the Query Editor to set a number of default

properties for XML output including

bull setting a default stylesheet

bull setting the default DTD reference (external internal or none)

bull setting the output format

bull including XML Element IDs

bull including Sentences IDs

These settings apply for XML import and export operations which use the query unless

they include their own settings which would override these For detailed instructions for

these settings see ldquoXML properties dialogrdquo You can also rename request nodes in the

Query Editor to determine the name for your XML output document and the names of the

XML elements in the document For more details see ldquoNode name considerations for

XML outputrdquo

The Diagram Editor

Sentences diagrams

393

Chapter 9

Sentences diagrams

This chapter describes how to work with the Sentences Diagram Editor


bull creating diagrams

bull printing diagrams

bull exporting and importing diagrams

The Diagram Editor

The Sentences Diagram Editor displays entity and association types and other schema and

data elements in a graphical layout For example an association typersquos source and target

are displayed as graphical objects with a line connecting them to represent the association

type structure This connecting line is labelled with the association type verb

The Diagram Editor can be used to explore and clarify an existing schema It is not a tool

for editing a schema or for creating new schema elements

Starting the Diagram Editor

To start the Diagram Editor select Diagram Editor from the View Menu

Figure 9-1 The Diagram Editor

The Diagram Editor is shown in Figure 9-1 There can only be one Diagram Editor open

at any time While the Diagram Editor is open you cannot change the profile

If you close the Diagram Editor and reopen it without changing your profile Sentences

displays the last diagram you worked on If you close the Diagram Editor and change

your profile and then reopen the Diagram Editor Sentences displays a blank diagram

although your Preferences settings are retained

Diagram Editor components

The editor is made up of three components the toolbar a schema tree and the canvas

The Diagram Editor

Sentences diagrams

394

Toolbar

The toolbar gives quick access to frequently used actions All the actions are available on

the Diagram Editor File Edit or View menus or the from the Diagram Editor

Preferences dialog The toolbar buttons are described in the following table

Button Description

Export - export the diagram

Import - import an exported diagram

Stops execution of queries

Print

Delete - deletes selected diagram elements

Default Dataform - can be opened on diagram elements that

represent instances

Preferences - opens the Preferences Dialog

Diagram quality - toggles between outline quality and

presentation quality

Increase and Decrease font size

Zoom in and Zoom out

Help

Schema tree

The schema tree displays the same items as the schema tree in the Sentences Explorer

Canvas

The canvas is where diagram elements are displayed You can move elements freely on

the canvas by dragging them with a mouse or by using the Shift key and an arrow key on

the keyboard For more details see ldquoDiagram elementsrdquo 4

Diagram Editor preferences

You can control the appearance of the canvas and the Diagram Editor in general by

changing settings in the Preferences dialog These settings are not retained from one

session to another

The Diagram Editor

Sentences diagrams

395

Figure 9-2 The Diagram Editor Preferences dialog

To view the preferences dialog select Preferences from the View menu or click the

Preferences button on the toolbar The following options can be adjusted on the

Preferences dialog

bull Font

You can specify a font and adjust the size and style The Preferences dialog displays a

sample of the selected font

bull Association type and association labels

You can specify how association types and associations are labelled in the diagram The

labels may include the association verb or association verb and target or association

source verb and target

bull Zoom factor

You can set the zoom factor for your drawing The available values are from 10 25

50 75 100 and 200 You can also adjust the zoom factor directly by selecting the

magnifying glass buttons on the toolbar The zoom factor controls the

presentation of the diagram on the screen and does not affect the printed output

which is scaled automatically

bull Diagram quality

You can select either Outline Quality or Presentation Quality for the diagram

The Diagram Quality on the toolbar toggles between these two settings

bull Results limit

You can adjust the limit for the number of query results that can be placed on the

diagram The default value is 100 The Diagram Editorrsquos response time starts to slow

down if there are too many elements on the canvas and the readability of printed output is

also affected

The Diagram Editor

Sentences diagrams

396

Diagram elements

You can display Sentences schema and data items on the canvas These include entity and

association types custom Dataforms and queries You can also display query results

Only one instance of any Sentences element can be displayed on the canvas

Diagram element types

There are six types of diagram element that can be shown on the canvas All diagram

elements have their own shortcut menus for adding other relevant diagram elements

bull Entity type diagram element

An entity type is shown as a purple rectangle Subset types are shown as yellow

rectangles Value types are shown as ovals

bull Association type diagram element

Association type diagram elements are lines that join the source and target with the verb

text displayed at a point along the line In a normal diagram straight lines are used and

curved lines are shown in high quality diagrams Lines for association types are purple

except for subset association types which are yellow

You can move the point at which the verb text is displayed by moving the verb text The

direction of the association is shown by an arrow The verb text can have one of four

formats which can be selected on the Preferences dialog (see ldquoDiagram Editor

preferencesrdquo )

bull Query diagram element

The Query diagram element is a blue rectangle There is a tool tip display to indicate what

kind of query it is You can add query results to a diagram See ldquoAdding Query Resultsrdquo

bull Custom Dataform diagram element

The Custom Dataform Query diagram element is a dark grey rectangle

bull Entity diagram element

An entity diagram element is a cyan rectangle A value entity is shown as a cyan oval

bull Association diagram element

Association diagram elements are lines that join the source and target with the verb text

displayed at a point along the line In a normal diagram straight lines are used and curved

lines are shown in high quality diagrams Lines for association diagram elements are

cyan

Adding diagram elements

To add a Sentences element to the Diagram Editor canvas you can drag it from the

schema or data pane of the Sentences Explorer or from the schema pane of the Diagram

Editor or the Query Editor or from the Query Editor results pane

Sentences places the new element wherever you drop it by releasing the mouse button If

the object you are adding to the canvas is an association type or association and either the

source or the target is already present on the canvas Sentences creates a visual link to the

source or target

You can also use the Edit menu or the canvas shortcut menu and select either Add Core

Entity Types or Add All Entity Types to add elements to the canvas

Adding annotations titles and legends

You can add annotations titles and legends to the diagram on the canvas

bull Annotations

The Diagram Editor

Sentences diagrams

397

An annotation is a resizeable text box You can freely edit the text The font is the same

size and style as defined for diagram elements Annotation text boxes have a border and a

light yellow background

To add an annotation select Add Annotation from the Edit Menu or from the canvas

shortcut menu After you have created an annotation you can edit it by selecting it and

pressing F2 or by selecting Edit text from the shortcut menu

bull Titles

A title is a resizeable text box You can freely edit the text The font is the same style as

defined for diagram elements but 25 larger Title text boxes have no border and no

background

To add a title select Add Title from the Edit Menu or from the canvas shortcut menu

After you have created a title you can edit it by selecting it and pressing F2 or by

selecting Edit text from the shortcut menu

bull Chapter Legends

Chapter Legends are read-only They show the name of the profile and a list of the

chapters in it If the Chapter Number option is set then the chapter numbers are included

in the Legend You can resize a Chapter Legend box

The font used for Chapter Legends is the same style as defined for diagram elements but

15 smaller Chapter Legend text boxes have a light blue background and a border

Selecting diagram elements

You can select a diagram element by clicking on it To select more than one diagram

element hold the Ctrl key and click on the elements

You can also select elements by dragging the mouse over them The Diagram Editor

displays a selection area and all the elements inside the area or intersected by the

selection boundary are selected

To select all the elements on the canvas select Select All from the Edit menu or from the

canvas shortcut menu or press Ctrl+A

Deleting diagram elements

To delete a diagram element select Remove from the Edit menu or from the canvas

shortcut menu

To remove all elements select Remove All from the Edit menu or from the canvas

shortcut menu

Moving diagram elements

To move a diagram element with the mouse click on it and hold the mouse button while

dragging it to a different position To move a number of selected elements at the same

time press and hold the Ctrl key

You can use the keyboard to move diagram elements Select an element and hold down

the Shift key and use the up down left and right arrow keys to move the element

Consistency with Sentences Explorer

Some of the settings in the Sentences Explorer are automatically used in the Diagram

Editor

bull If Chapter numbers or Lazy IDs are displayed in the Sentences Explorer they are added

to the names of the diagram elements on the canvas

bull If you delete a schema or data element in the Sentences Explorer then any diagram

element representing or depending on that schema or data element is removed


Sentences diagrams

398

bull If you rename a schema or data element in the Sentences Explorer then any diagram

element representing or depending on that schema or data element is renamed

Adding Query Results

You can display queries and their results on the diagram

To add query results to a selected query on the canvas select Add query resultshellip from

the Edit menu or from the shortcut menu

If you select Add query resultshellip from the Edit menu when no query is selected

Sentences displays a picker showing the available queries

The Diagram Editor cursor changes to a precise cursor so that you can select the part of

the canvas where the results should be displayed To cancel placing the query results

press Esc

There is a limit to the number of results that can be placed on the diagram This limit can

be set using the Preferences dialog (see ldquoDiagram Editor preferencesrdquo )


Sentences currently does not store diagrams in the database However you can export a

diagram as a file and then import it later The export file includes all the diagram elements

currently on the canvas and all your current preferences

The export file contains data in a format that is relative to the current profile You cannot

export a diagram using one profile and import it using a different profile The export file

is also dependent on the current state of schema and data in the profile If a diagram

export file includes references to schema or data elements that have been deleted it cannot

be imported into the Diagram Editor

When you import a diagram export file that includes temporary data such as query results

based on derived types only the persistent items are displayed and the temporary items

are not displayed

Export

To export a diagram select Export diagram from the File menu Sentences displays the

file dialog for your system Select a location and enter a file name and click Export to

export the diagram or select Cancel to return to the Diagram Editor

We recommend using the file extension lzd to identify diagram export files

Import

To import an exported diagram select Import diagram from the File menu Sentences

displays the file dialog for your system Select a location and select a file name Click

Import diagram to import the diagram or select Cancel to return to the Diagram Editor

Saving as a GIF file

You may also save the current diagram as a GIF file You can then work with the GIF file

in any suitable graphics editing program or import the GIF file into any suitable word

processing program

To save a diagram as a GIF file select Save as GIF from the File menu Sentences

displays the file dialog for your system Select a location and enter a file name and click

Save to export the diagram or select Cancel to return to the Diagram Editor

Printing

You can print a diagram to a printer attached to your system Printing is only currently

supported for Microsoft Windows systems Printing on Linux and Mac OS X platforms

depends on the printing setup

Printing

Sentences diagrams

399

The Diagram Editor automatically includes all the diagram elements that are on the

canvas in the printed output The entire diagram is scaled to fit onto a single page for

printing This means that the greater the number of diagram elements present on your

canvas the smaller the size of each element when you print your diagram

The Diagram Editor displays two paper edge guide lines to showing the right-hand and

lower edge of the printed area You may not place any diagram elements outside the

printed area

You can choose either Portrait or Landscape orientation for printing The position of the

paper edge guide lines changes to match your selection To change the paper orientation

select Page Setup from the File menu

To print your diagram select Print from the File menu Sentences displays the standard

printing dialog for your system



401

Chapter 10


This chapter looks at some of the techniques you can use to customise Sentences

bull you can use the Sentences API

bull you can create database triggers

bull you can create custom datatypes

As all these techniques involve writing your own Java classes and methods and using

parts of the Sentences API the information in this chapter is written for experienced

programmers with knowledge of Java

Your Sentences installation includes some code examples that demonstrate the

implementation of custom datatypes and triggers and the client API These examples

are explained in Chapter 11 ldquoWorked examplesrdquo

This chapter also describes how to create customised Help pages for your Sentences

application and includes notes on translation and localisation


Note When you install Sentences some API features are disabled You are recommended

to implement security settings on your web server before you these features For more

information see ldquoServlet access to Sentencesrdquo

The Sentences Application Program Interface (API) is a programmatic interface to the

Sentences database It is a collection of Java classes which can be used to extend the

functionality of Sentences Using the Sentences API programmers can write their own

Java programs to customise and extend the functionality of Sentences

To use the Sentences API effectively you should have some understanding of the

associative model of data and of Sentences as well as experience in software

development and thorough knowledge of the Java programming language Instructions on

how to write Java code are not given in this book

This section provides an overview only of the Sentences API and is designed as an

introduction to the more detailed information given in the online documentation

Sentences API





Sentences Version 40 introduces a User Security model which requires the authentication

of a user when connecting to the Sentences Server

For the Server API exclusive access to the Sentences database is required and so the

current user in a Server API session is automatically the System Administrator

For the Client API a client programme must authenticate its user to set the current user

and gain their privileges



402

The comsentencesapiClientApi class allows the programmer to create a Client

Session The comsentencesapisessionClientSession in turn provides the

method authenticate(String username String password) to facilitate this

Once authenticated the current user is available through the method

public User getCurrentUser()

which the ClientSession inherits from the DatabaseSession interface

A LazyException is thrown if the user is unknown or the password is incorrect

Comparing the Sentences Client API and Server API





The Sentences Client API allows Java programs to access the Sentences database

alongside other clients such as the Sentences applet You must make sure that your server

is configured to allow Client API access by verifying the settings in the

Serverproperties file (see ldquoServlet access to Sentencesrdquo ) An example of a client

API program is given in the section ldquoClient API examplerdquo The Client API can execute

queries With regard to updates the Client API like the Sentences applet packages

transactions and only writes updates to the database when a transaction is committed (this

is analogous to a user clicking the Save button on a parent Dataform)

The Client API is not available with Sentences Personal Edition

The Sentences Server API is used by standalone Java programs which are executed on the

server machine The Server API cannot execute queries Java programs that use the

gateway class ServerApi require exclusive access to the database Triggers are also

written with the Server API but they do not use the gateway class ServerAPI

With regard to updates the Server API writes updates to the database immediatelyEven

though these updates are not made permanent until the transaction is committed they are

immediately available to the Server API program that made them This makes the Server

API useful for writing programs which must make very large updates to the database



ltSentences_homegtDocapihtml The Javadoc files for the Sentences API can be

found in ltSentences_homegtDocjavadoc

Example code and online documentation

This Userrsquos Guide does not include code examples but examples are included in the

Sentences distribution

These items of example code can be found at

ltSentences_homegtExamplescomsentencesexamples

The publicly-available classes and methods of the Sentences API are described in

a series of online documents for programmers which can be found at

ltSentences_homegtDocapihtml

Program build and execution

All Sentences API programs must be written in the Java programming language All the

tools and components necessary to build and run Java programs with Sentences are



403

contained either in the standard Sentences Enterprise Edition delivery or in the Java

Software Development Kit which is available from Oracle

The current version of the Java Software Development Kit can be downloaded from the

Java website

httpwwworaclecomtechnetworkjavajavaeedownloadsindexhtml

Sentences API programs can be built and run using the standard Java compilation

(javac) and execution (java) utilities

API packages

The Sentences API is divided into nine packages as follows

Package name Area

comsentencesapi factory and helper classes for the API

comsentencesapievent interfaces for observing things stored in the

Sentences database

comsentencesapiexceptions exception classes used in the API

comsentencesapiobject classes and interfaces for Sentences

datatypes

comsentencesapiobjectui panels for changing the property values of a

particular datatype

comsentencesapirequest interfaces for creating and executing

queries

comsentencesapisession interfaces for accessing the database

comsentencesapithings interfaces for manipulating things in the

database

comsentencesapitrigger classes and interfaces for triggers

Class hierarchy

The database class hierarchy as used by the Sentences API is shown in Figure 10-1

below

Figure 10-1 Class hierarchy for API Session view of database structure

The terms entity association entity type and association type used in Figure 10-1 have

the same meaning for the API as they have for any user of a Sentences schema or of

Sentences data Within the database they may also refer to and serve to store system

defined properties schema definition components and other components used by

Sentences for internal purposes

Anything that is stored in a Sentences database is represented as an object of one of the

LazyThing subclasses shown above The source or target of any association is a

Triggers


404

LazyThing This class includes methods that apply to all database items including

deleting the item retrieving associations involving the item and many others

The subclasses of LazyInstance represent instance data rather than schema data A

LazyEntity corresponds to an entity instance A LazyAssociation corresponds to

an association with a defined source and target

A LazyType is part of the schema It represents anything that can have instances The

LazyType class includes methods relating to instances and methods relating to

supertypes and subsets

LazyEntityType and LazyAssociationType represent entity types and association

types respectively

Triggers

Triggers in Sentences are similar to ldquostored proceduresrdquo in some other databases To use a

trigger you first create your own Java code for the trigger using the Sentences API To



the Serverproperties file Trigger code is assigned to an entity or association type

in Sentences using the Triggers page of the Properties dialog

You can create generic trigger code that can be attached to more than one Sentences type

For example you could create a trigger that would reject a delete request and attach it to

one or more entity or association types Whenever a user tried to delete an instance of a

type that had this trigger attached the delete action would not be allowed

Note It is possible to prevent the deletion of instances in Sentences by selecting the

Instances cannot be deleted property in the Properties dialog for the entity type or

association type

When you design triggers remember that one trigger may be used with more than one

type and make sure your trigger can handle not only relevant notifications but also any

non-relevant notification it may receive Give your trigger a meaningful name and make

the triggerrsquos package and class names clear as well This helps ensure that your trigger is

assigned to appropriate cases

Server-side triggers

Triggers are instances of Java classes which implement the LazyServerTrigger

interface You can associate a server side trigger with types through the Properties dialog

(see ldquoTriggers properties pagerdquo )

Sentences triggers on relevant entity and association types can be invoked for the

following database update events

Event When Fired

Create an instance is created

Delete an instance is deleted

Rename an instance is renamed (only available for entity

types)

Association Moved a sequenced association is reordered (only


Triggers


405

Event When Fired

Attribute Changed

an instance of the type has become or has

ceased to be the source of an association

when an association is re-sequenced deleted

added or superseded an Attribute Changed

event is fired for the source of that association

type

Supersedes Added an instance is superseded

Target Changed the target of an association is changed (only


Set Equivalent an instance has an equivalent assigned

Remove Equivalents an equivalent instance is removed

When invoked a trigger can retrieve information related to the update event which has

triggered it

Trigger code usually has dependencies on the Sentences schema it has been designed to

work with If the schema is changed triggers may not operate correctly until the

Sentences server has been stopped and restarted following the changes The trigger code

itself may need to be changed

Trigger examples

For examples of how triggers may be used see Chapter 11 ldquoWorked examplesrdquo Java

source code and a JAR file for some example triggers can be found in the Examples


Triggers and the Sentences API

The Sentences API is described in a series of HTML files in the Doc directory of your

Sentences installation There is an overview of the Sentences API in Docapihtml

This document contains links to sections on different aspects of using the Sentences API

including how to create triggers and custom datatypes

Installing a trigger

To use a trigger you must write your own Java code compile the code into a Java archive


the Serverproperties file You can then use the Triggers properties page to assign

the trigger to a particular entity or association type The detailed steps for attaching a

trigger to an entity or association type and how to edit trigger assignments are given in

the next section

Attaching a trigger

To view the list of triggers available on the Sentences server select Triggers from the

View menu Sentences displays the Available Triggers list

Triggers


406

Figure 10-2 The Available Triggers list

You can expand a trigger node in the Available Trigger list to show the Java class name

for the trigger a brief description of the trigger and a folder listing all the types currently

using the trigger

To attach a trigger to an entity or association type follow these steps

1 Open the Properties dialog for the type and then open the Triggers page shown

in Figure 10-3

Figure 10-3 The Triggers page before triggers are assigned

2 Click the Add button Sentences displays the Add Trigger Assignment dialog shown

in Figure 10-4 This shows a list of all available triggers in the left hand list box and the

set of possible trigger events shown on the right-hand side Only the trigger events that

Triggers


407

are relevant to the type selected (entity or association) are available Choose All to

activate the trigger for all update events

If there are no server triggers available Sentences displays an error message

Figure 10-4 The Add Trigger Assignment dialog

3 Select a trigger from the triggers list and select a trigger event or All trigger events

and click OK

4 The Triggers page now lists the assigned triggers and trigger events as shown in Figure

10-5

Figure 10-5 The Triggers page showing assigned triggers

If you have more than one trigger for the same event you can change the order in which

they are activated by highlighting a trigger event row and using the Move Up and Move

Down buttons

To remove one or all triggers use the Remove or Remove All button

You can change the trigger event assignment for a trigger by highlighting a trigger event

row and clicking the Edit button Sentences displays the Edit Trigger Assignment

dialog This is similar to the Add Trigger Assignment dialog shown in Figure 10-4

except that the All option is not available

Triggers


408

Trigger threading issues

The Sentences server ensures that all transactions against a profile and all updates within

each transaction are processed in series As chapters may be shared between multiple

profiles all chapters in a profile are locked during the processing of a transaction Trigger

code execution is completed within transaction processing and hence trigger code

execution is always single-threaded

A single trigger class may be used by multiple profiles if appropriate A new instance of

the trigger is created for each profile This means that when you write a Sentences trigger

you only need to be concerned with threading issues with regard to class variables in your

trigger classes and any shared instances of non-Sentences classes which their trigger code

may make use of

Trigger invocation

The notify()method of one or more triggers may be invoked one or more times when a

given update is applied to the database It is possible for a given trigger to be invoked

more than once for what might appear to the end-user to be a single update

Triggers are only invoked as a result of updates being made to the database using the

Sentences user interface the Sentences API by other triggers or by the trigger itself

while the trigger is active Triggers are not invoked on instances of entity or association

types which existed prior to the trigger being registered

Details of the update events for which triggers notify() methods are invoked can be

found in the Javadoc for the LazyServerTriggernotify() method

The notify() method is invoked before the transaction is confirmed as being

committed to the database Transactions may be aborted if any update within it is vetoed

either by data validation rules built in to Sentences or by a trigger or if some unexpected

failure occurs For all events other than Delete events the trigger code in the notify()

method sees the content of the database as if the entire transaction had been committed

even though the database has not yet been updated For Delete events the trigger code in

the notify() method sees the content of the database before the update has been made

and so a delete trigger can inspect the database before any changes are made

In general a trigger needs to inspect the event type that invoked it the instance which was

updated and possibly also other instances in the Sentences database in order to determine

what kind of update caused its invocation and what action should be taken


are invoked as normal when you click the Save button (see ldquoCustom Dataform

restrictionsrdquo )

Trigger actions

When the notify() method of a trigger is invoked it can either veto the triggering

update by throwing a LazyRuleViolation exception or perform some other action

which is appropriate when that update occurs

Trigger code and system validation rules that test for cardinality violations occur together

for each distinct update in a transaction For each update action in the transaction any

notify() methods which exist for the affected types are called followed by the

application of the system checks The updates are processed in series in the order in which

they occur in the transaction

Customised validation (rules)

A trigger can veto its triggering update by throwing a LazyRuleViolation exception if

it considers that the update would be invalid and this results in the update being aborted



409

If the aborted update is part of a transaction containing other updates then all the updates

in the transaction are aborted

If a trigger throws a LazyRuleViolation exception Sentences alerts the user that

unacceptable data has been entered The trigger writer has a choice of constructors for the

LazyRuleViolation and this choice affects how Sentences communicates the error to

the user

When an update initiated by a user is vetoed by a trigger an error message is displayed in

the Sentences Message Log This is either the message returned by the triggerrsquos

getDescription() method or the message encapsulated in the LazyRuleViolation

depending on which LazyRuleViolation constructor was used

In addition in cases in which the trigger has provided the information Sentences

highlights the data which is invalid This may not be possible in all cases for example

where that data was entered on a child Dataform which has already been closed

Customised actions

You can design a trigger that can take any action in response to a given update eventFor

instance the trigger might make further updates to the Sentences database

To do this the trigger creates a new child transaction of the transaction whichcontained

the triggering update so that the further updates are either committed or aborted along

with the triggering update A trigger should not attempt to add further updates to the

transaction which contains the triggering update

When you write a trigger you must make sure that any new child transactions the trigger

creates are either committed or aborted prior to the return from the notify() method

because otherwise the parent transaction containing the triggering update and possibly

containing other updates too is aborted After a trigger has committed a child transaction

system validation rules and trigger code notify() methods invoked on any following

updates see the contents of the database as modified by that child transaction The

notify() method can also take account of Client Parameter settings for determining

trigger actions

You can write a trigger that may take some action outside the Sentences database such as

sending an email message External actions are taken without reference to the success or

failure of the triggerrsquos actions inside the Sentences database For example if you write a

trigger that sends an email message the message would be sent even if the triggering

update itself was aborted

For more information please refer to the online documentation for the Sentences API in

the Doc directory of your Sentences installation

Using triggers with import and export

Trigger code is not invoked when you import or export a Profile (see ldquoExporting and

importing databasesrdquo )

Triggers are optionally applied to data from CSV files (see ldquoCSV Importrdquo ) and to data

from XML files (see ldquoImporting XML datardquo 0)


The Sentences datatype mechanism controls the format in which entity names are entered

by or presented to users and also controls some aspects of entity behaviour such as

whether an entity can participate in arithmetic or not Several datatype classes are

provided as part of Sentences including Number Timestamp and Text When you

assign any one of the datatypes provided with Sentences to an entity type you may

convert it to a value type The behaviour of value types is described in ldquoValue types and

datatypesrdquo



410

A Java programmer can also create tailored datatypes known as custom datatypes by

writing Java classes which implement the LazyDatatype interface It is possible to

create a custom datatype that controls the formatting of an entity type but does not make

the entity type behave as a value type There is a detailed example of a custom datatype in

Chapter 11 ldquoWorked examplesrdquo

Custom datatypes behave in virtually the same way as the Sentences-supplied datatypes

and both can control the behaviour of an entity type Details of the behaviour which can

be controlled and how such a class can be programmed can be found in the online

documentation for the custom datatypes in the Doc directory of your Sentences

installation (see the document datatypeshtml) and also in the Sentences Javadoc

documentation (see the section on the comsentencesapiobjectLazyDatatype

interface)

A custom datatype class may be produced either by implementing the LazyDatatype

interface from scratch by subclassing LazyAbstractDatatype or by subclassing

another Sentences-supplied datatype To assist with the subclassing options the source

code of the Sentences-supplied datatypes is supplied in

ltSentences_homegtExamplesExistingDatatypesjava

Datatype capabilities are programmed into the Java class which provides the datatype

and cannot be changed by the Sentences end-user When correctly configured a custom

datatype appears as an available choice in the Datatype page of the Properties dialog for

entity types A schema designer or administrator can set the datatype of any entity type as

required and can choose a suitable output format from those offered by the datatype

When an entity type is created which has the same name (case-sensitive) as a custom

datatype then the datatype of that entity type is by default set to the custom datatype

The Java source code and JAR file for an example custom datatype can be found in the

ltSentences_homegtExamplescomsentencesexamplesdatatypes

subdirectory


Sentences Version 40 extends the existing Custom Datatype API

Two new methods allow you to override the default field width for your custom datatype

and to override the default format pattern if applicable

Answer the default field length used for the format when

creating a new EntityType

Override to change the default of ltVariablegt

return int

since 40

public int getDefaultFieldWidth()

Answer the default field format pattern (Style) used for

the format when creating a new EntityType

Override to change the default of ltDefaultgt

return String

since 40

public String getDefaultFormatPattern()

Installing a custom datatype

To install a custom datatype you must write your own Java code compile the code into a

Java archive (JAR) file and place the JAR file in the directory listed in the

DatatypePath property in the Serverproperties file By default this directory is



411

ltSentences_homegtDataypes The custom datatype appears in the list of datatypes

available in the Datatype properties page

The Java class for the custom datatype must implement the LazyDatatype interface

which is part of the Sentences API

Custom datatypes and import and export

Any custom datatype that is installed according to the instructions in the previous section

is available for use with the Sentences serverrsquos import and export routines

Removing custom datatypes

To unload a custom datatype remove its JAR file from the directory referenced in the

DatatypePath parameter of the Serverproperties file When you have done this

the custom datatype is no longer available for assignment to any types











datatype


You can add custom Help for any Sentences Dataform To do this you need to create Help

topic pages and a Help topic mapping file

The Help pages you create are displayed as HTML pages in a Web browser when a user

clicks a Help button on a Dataform

Help button display

The Dataform Help button is created automatically by Sentences for any Dataform that

has a Help page listed for it in the mapping file An example of a Dataform with a Help

button is shown in Figure 10-6

The Dataform can display only one Help button The Help page called by clicking the

Help button is the page mapped to the source type of the Dataform or in the case of

custom Dataforms the page mapped to the custom Dataform name



412

Figure 10-6 Example of a Help Button on a Datatform

Precedence of Help pages

If a Help page has been mapped for a custom Dataformrsquos name that page is displayed

when the Help button is selected For all other Dataforms and for custom Dataforms for

which there is not a specific mapping the page displayed when the Help button is

selected is the page mapped to the Dataformrsquos source type

Updating Help topic mappings

Help topic mappings are only read by Sentences when the Sentences applet is loaded by

the Java Plug-in and therefore any changes made to the mapping file are only effective

after the applet is restarted

Creating Help topic pages

You can use any suitable HTML editor or text editor to create your Help topic pages The

pages must be formatted as HTML files that can be opened in a Web browser The Help

pages may contain any combination of text graphics and hyperlinks that is supported by

the HTML standard

The Help topic pages should be saved in a format that can be served by a Web server and

displayed in a Web browser for example as HTML pages with the suffix html or

htm

You may choose to create a separate file for each Help topic page you create or to create

one file containing a number of topics each identified by an HTML anchor tag

ltA NAME=rdquoanchor namerdquogtanchor nameltAgt

Creating a Help topic mapping file

The Help topic mapping file is a plain text file which contains a list of name=value

pairs These pairs map the Sentences elements (entity or association types or custom

Dataforms) to their associated Help topic pages



413

Name and location of the Help mapping file

The name of the Help mapping file must have the following name

DataformHelpTopicsproperties

This file must be located in the Web application directory for Sentences The full path for

this directory is


In Sentences Personal Edition this file is in the ltSentences_homegt directory

Mapping Sentences elements to a Help topic

To map a Sentences element to a Help topic create a line in the help mapping file with

the Sentences element as the name and the URL for the Help topic file as the value in a

name=value pair

When you create a mapping line you must follow these guidelines

bull For all the Sentences elements use the same capitalisation as is used in the schema

bull Replace any spaces with underscore characters

bull Enclose all association type names in parentheses characters ( ldquo(rdquo and ldquo)rdquo ) using nested

parentheses for nested associations

bull Separate the source verb and target of association types with commas

bull Do not use a space after a comma or before or after a parenthesis character

The URL for a Help topic file can be relative in which case the Web application directory

for Sentences is the reference base for the URL For more information about using

relative URLs see the sections ldquoFile system permissionsrdquo and ldquoVirtual directoriesrdquo

bull Entity type mapping example

To map the entity type Employee to a Help topic page named Employee_helphtml

located in the Web application directory for Sentences use the following line in the

mapping file

Employee=Employee_helphtml

If you use HTML anchor tags in your Help topics file you can append anchor names to

the Help topic file URL for example

Employee=Employee_helphtmlanchor

bull Association type mapping example

To map the association type (Employee next of kin Person) to a Help topic page

named Next_of_kin_person_helphtml located in the

ltSentences_homegtTomcat4WebappsSentences directory use the

following line in the mapping file

(Employeenext_of_kinPerson)=Next_of_kin_person_helphtml

To map the nested association type ( (Employee next of kin Person) lives in Town)

to a Help topic page named Lives_in_Town_helphtml in the


in the mapping file

((Employeenext_of_kinPerson)lives_inTown) sect

=Lives_in_Town_helphtml

bull Custom Dataform mapping example

To map the custom Dataform EmployeeDataform to a Help topic page named


Localisation notes


414

ltSentences_homegtTomcat4WebappsSentencesCustomHelp directory

use the following line in the mapping file

EmployeeDataform=CustomHelpEmployeeDataformhtml

You can map child Dataforms opened from the custom Dataform to specific Help files or

to named anchors in specific Help files

To map the child Dataform Person opened from the custom Dataform

EmployeeDataform to the named anchor Person on a Help topic page named



in the mapping file

EmployeeDataformPerson=EmployeeDataformhtmlPerson

Child Dataforms other than those opened from custom Dataforms use the Help mapping

for their default type if any exists

Localisation notes

Sentences includes native methods for localising both system text and application text

which are described in this section Sentences does not provide an automatic capability

for translating texts You must prepare the translated text independently

Localising Sentences system text

Sentences system text includes all menus buttons messages system folder names and

system dialog labels but not type and instance names or Dataform field labels All the

system text is included in one message file Messagesproperties which is compiled

into the Sentencesjar file Sentences system text can be localised using a customised

message file distinguished by a Java Locale identifier

The Java programming language uses the Locale object to define a userrsquos language and

geographical location using standard ISO codes For example the Locale identifier

en_US represents United States English and the identifier fr_CA represents Canadian

French The Locale object is used to make sure that culturedependent items such as

language numbers and dates and times are presented to the user in an understandable

way

The Java plug-in that runs the Sentences applets can recognise a client machinersquos Locale

setting and select messages from the appropriate message file for that Locale if one

exists You can create multiple versions of the messages file each for a different Locale

to allow different clients in different Locales to use the same server

All Sentences system text is identified by numeric codes If a localised text for a specific

code is not found the English language text is used More information on the way Java

uses the Locale object can be found on the Oracle website


Extracting the Messagesproperties file

Translations of Sentences system text should usually be based on the original English

messages file Messagesproperties This is contained in both the client and server

Java archive files for Sentences (JAR files) You can extract a copy of the

Messagesproperties file using any software that can manipulate JAR files for

example the jar program that is part of the Java SDK

To extract the Messagesproperties file first make sure that the jar program is on

your path for program files and then open a command prompt and navigate to the

Localisation notes


415

directory that contains the file SentencesServerjar Then run the following

command

jar xvf SentencesServerjar Messagesproperties

This extracts the file to the current directory

Naming the translated messages file

The name of the translated messages file must conform to the following pattern

Messages_ltLocalegtproperties

where ltLocalegt is the Java Locale identifier for example

Messages_fr_CAproperties

where fr_CA represents Canadian French

Example translated messages file

The Sentences installation includes an example translated messages file

Messages_de_CHproperties with message texts translated into Swiss German

Directory location for the translated messages file

In Sentences Enterprise Edition the translated messages file must be placed in two

directories as it is used by both the server and the client These directories are the Web

application directory for Sentences and the classes sub-directory for the Sentences

Web application The full paths for these directories are


ltSentences_homegtTomcat4WebappsSentencesWEB-INFclasses

In Sentences Personal Edition place the translated message file in the


There is no need for the translated files to be compiled into the SentencesServerjar

or Sentencesjar archive files

Translating Sentences application text

Sentences application text includes the names of entity types and association types You

can use Sentencesrsquo Profile and Chapter features to create localised versions of

application text

Sentences allows the creation of separate profiles for different users and groups of users

(see ldquoUsing multiple profilesrdquo and ldquoCreating database views using profiles and chaptersrdquo

)

You can localise your application text by applying the Rename command to each entity

type or association type for which you wish to have a translated name using a separate

schema changes target chapter for each language and then making that chapter available

only in the profile accessed by users of that language

A suggested procedure would be as follows

1 Create a new chapter and add it to your profile

2 Designate the new chapter as the target chapter for schema changes

3 In your Sentences application apply the Rename command to each entity type or

association type for which you wish to have a translated name

4 To view the application text in the original language remove the chapter used as target

for the Rename actions from the profile To view the application text in the translated

language include the chapter used as target for the Rename actions from the profile


Worked examples

416

Chapter 11

Worked examples

This chapter contains an introduction to the Human resources example application

and step-by-step worked examples of a number of Sentences features as follows

bull CSV Import example

bull Derivations example

bull Trigger examples

bull Custom datatype example

bull Client API example

bull Integration with Microsoft Office applications

The examples in this chapter refer in general to the Sentences Enterprise Edition but

most of them can also be run with the Sentences Personal Edition Where this is not

possible it is noted in the text

Throughout this chapter the symbol sect indicates that a line in a file has been split to

allow display in this book only You should type in the text as one line


The Human resources example application supplied with Sentences is intended as an

uncomplicated introduction to the core features of Sentences and is used to illustrate

Sentences features throughout this Users Guide The example application is designed to

illustrate a range of features in Sentences and it is not intended to be a prototype of a

genuine human resources application Some of the choices made in developing the

database for this application might not be appropriate in other circumstances For

example the Human resources example application uses an Employee entity type In

some situations it might well be preferable to model employment as an association type

between a Person and an Organisation

This section is an overview of the example application including notes on some of the

features illustrated More information can be found in the relevant feature specific

sections of this guide You may find it useful to have the Human resources example

application available to you as you read this section

The application domain for the example application is human resources management for

the Sleepy Software group of companies Sleepy Software is a fictional global corporation

with multiple subsidiary companies These companies share resources and projects The

main uses of the application are illustrated by the entries in the Core types folder

Current employee Employee Group company and Project

The Employee entity type

People are clearly central to any human resources application The Human resources

example application includes a number of related entity types that represent people

Person Employee and Current employee

The Person entity type is used to record personal details about any person not just

employees An Employee is a Person who is or has been an employee of one of the

Sleepy Software group of companies and is defined as a subtype of Person

CSV Import example

Worked examples

417

Using Person as a supertype of Employee allows for the personal details of employees

and of their next-of-kin to be stored using the same schema elements while maintaining

the important distinction between employees and other persons

A Current employee is a Person who is an employee of one of the Sleepy Software

group of companies Current employee is implemented as a subset of the type

Employee The other subsets of Employee are Resource skills and Project Resource

Only Resource skills is the source of any association types

Dataforms automatically display tabbed pages for any supertypes or subsets of a given

type that are the sources of associations (see ldquoDataform tabbed pages with subsets and

supertypesrdquo ) Therefore the dataform for an Employee has three tabs Person (which is

the supertype of Employee) Employee and Resource skill (the only subset of

Employee that has association types sourced on it) These three tabs present associations

showing general personal details employee information and skill data respectively

Some Employees are also classified as Project resources who maybe assigned to

Projects based on the Project resource association

The Event table in the Dataform records employment history including when employees

join and leave This data is used by the query for the Current employee subset as well

as for the Latest Salaries query

The details of an employees next of kin can be accessed by viewing the Next of Kin

target instance Double-click the next of kin name or use the Viewhellip options on the

Dataform shortcut menu The Dataform for the Next of Kin selected is either a simple

Person Dataform (where the next of kin is not an employee such as Harold Ferny) or a

full Employee Dataform information (where the next of kin is an employee such as

Mary Venice)

The Group company entity type

All the fictional companies in the Sleepy group are represented using the Group

Company entity type The association types that are sourced on this entity type relate to

the companyrsquos location phone number and so on The subsidiary of association type is

an illustration of an association type that has the same type as both its source and its

target

The Project entity type

The Project entity type represents corporate projects The allocation of people (ldquohuman

resourcesrdquo) to projects is recorded using the Resources association type which has the

subset Company Resource as its target The query for the Company Resource subset

uses the association type Project resource defined on Employee to determine

whether an Employee is currently a valid resource or not

This means that you must define an employee as a Company Resource before you can

assign him or her to a Project

The query for the Company Resource subset also takes a Group company as an

optional parameter This allows use of the Target Parameters mechanism to restrict the

resources available for assignment to a project to those recorded as employed by the

single Group company selected as the Private to company For more information on

using the Target Parameters mechanism see ldquoTarget parametersrdquo

CSV Import example

CSV Import is a server-side procedure and needs to be run from the command line when

the Sentences server is not running To complete the steps in the example you also need

access to the file system to move image files to a new location

CSV Import example

Worked examples

418

The following example uses the CSV Import procedure to import information about five

new employees into the Human Resources example application The example uses a

series of example files located in the Sentences installation under the directory

ExamplesCSVImport

You can find both CSV (Comma Separated Value csv) files and jpg image files in

this location

The CSV Import procedure can only be used for adding data to an existing database and

it cannot be used to alter or create a database schema

When you use the CSV Import procedure the order in which you import data is very

important particularly if you use supertypes and subtypes in your database You must

always import subtype instances before you import supertype instances to avoid creating

duplicates

The Human Resources example application uses supertypes for example Person is a

supertype of Employee This means that when you want to add data that relates to a

Person who is also an Employee you must create the individual as an Employee first

and then add their associations as a Person In order to do this you must import the CSV

files for this example in the specific order given later in this chapter

Preparing a profile for the example CSV Import

Before you import the sample CSV files create a new profile based on the Human

resources profile This means that the original Human resources profile is not

modified and allows you to switch between the original profile and the new profile to see

the changes that you make The new profile has an additional data chapter which you

must add before importing data as CSV Import files cannot be used to make changes to a

database schema

To set up a profile for the example CSV Import procedure follow these steps

1 Open the Human resources profile

2 Open the Edit Profile dialog Type in a new profile name HR CSV Example Create a

new chapter HR CSV data and add it to the profile Do not remove either of the existing

chapters Make the new chapter HR CSV data the Data changes chapter Set the

Schema changes and Query changes chapters to (none) The Edit Profile dialog

should look like Figure 11-1 Save the profile

Figure 11-1 The Edit Profile dialog for the CSV import example

CSV Import example

Worked examples

419

3 Close Sentences and shut down the Sentences server If you are running the Sentences

Personal Edition you do not have a separate server process and so you only need to close

the program

Importing the example CSV files

To see the effect of importing CSV files you must import a number of sample files using

the CSV Import procedure for your platform Details of this procedure are given in ldquoCSV

Importrdquo You need to run the procedure separately for each file you want to import The

sample files are located in the directory

ExamplesCSVImport

The order in which the sample files should be imported is as follows

1 Employeescsv

2 Personscsv

3 Next of Kincsv

4 Resourcescsv

5 Employmentcsv

After each file is imported Sentences displays a message on the command line display as

follows

ltngt lines read

Committing changeshellip

Although you may import any of the sample CSV files more than once without affecting

the resulting data you must take care to import the files the first time in the specific

sequence given above because the HR CSV example application uses subtypes and

supertypes and therefore you must import the subtype data first to avoid duplication

Employeescsv or Employmentcsv must be imported before Personscsv or

Next of Kincsv This is because Employee is a subtype of Person Employee

instances must be created before any use is made of them as Persons

Importing data for associations targeted on associations

If you are interested in seeing how to import associations targeted on associations using

CSV import you can look at the Group company and Location columns of

Employmentcsv file using a spreadsheet program or text editor

For each line for which data exists in these columns in the Employmentcsv file

Sentences creates an association of the type Group company location Location These

associations are used as the targets for the association type employed by (Group

company location Location)

Viewing the imported data

After you have imported all the example CSV Import files start your Sentences server

and start or refresh your Sentences client Open the profile HR CSV Example and select

Employee in the schema pane as shown in Figure 11-2

CSV Import example

Worked examples

420

Figure 11-2 New Employee instances displayed

You can see that the five new employees created by the CSV import procedure are listed

in the data pane Margaret Pattison Cynthia James Tam Dreisbach Keith

Dreisbach and Nancy Williams

Figure 11-3 Dataform for Cynthia James

Highlight the name of Cynthia James and open a Dataform Look at the values for the

associations on the Employee Person and Resource tabs as shown in Figure 11-3

Adding image data

Look at the value for the Photograph association in the Dataform for Cynthia James

shown in Figure 11-3 You can see file path data and not the image itself This path

information was part of the data in the CSV file but the image file is not yet in the correct

location To view the Photograph images for the new Employees you must copy the

image files to your default image location

You can check what the default image location is for your system by checking the value

of the ImageURLbase parameter in the Applicationproperties file in the Personal

Edition or in the jnlp or javascript definition in the Enterprise Edition For more details

see ldquoAbout the ImageURLBase parameterrdquo

When you know your default image location copy the image files which all have the

suffix jpg from their delivered location ExamplesCSVImport to the LazyImages

subdirectory of the default image location

CSV Import example

Worked examples

421

After you copy the image files re-open the Dataform for Cynthia James The

Photograph association now displays the correct image as shown in Figure 11-4

Figure 11-4 Dataform showing Photograph image

Viewing additional data

The files you imported have also added three new Person entities to the application

These represent people who are not Employees but are used in the application as the

targets for Next of kin associations

To see some of this imported data select the Person entity type and open a Dataform on

either David Webb or Eddie Williams or Michael James Data related to these

individuals comes from the files Personcsv and Next of Kincsv

The files you imported have also added additional employment history data for the

existing employee Mark Goldstone You can use the Open Profile command on the File

menu to switch between the original Human resources profile shown in Figure 11-5

and in the HR CSV example application shown in Figure 11-6 to compare the contents

of the Employee event Date associations table for this employee before and after the

import

Figure 11-5 Original data for Mark Goldstone

Derivations example

Worked examples

422

Figure 11-6 Data for Mark Goldstone after importing sample CSV files


As you imported the CSV file data to a new profile the original Human Resources

profile was unaffected To restore the original Human Resources profile choose Open

Profile from the File menu and select the profile name

Repeating the CSV Import example

If you want to repeat this demonstration of CSV data import remove the HR CSV data

chapter from the HR CSV example application in the Edit profile dialog and then

create a new chapter with a different name and add it to the profile as the Data Changes

target

Derivations example

The Order Entry example application demonstrates the use of derivations in the Query

Editor and the resulting appearance and functionality of the custom Dataform It also

demonstrates the use of a trigger to create entity instance names when the Instance name

created by trigger option has been selected for an entity type (see ldquoInstance optionsrdquo )

The example application includes the following features

bull a custom Dataform

bull page nodes

bull derived types

bull derivations

bull derivation calculation properties

bull custom Dataform navigation properties

bull the Picker applet

bull the use of a trigger to generate instance names

Note The example application uses a simplified schema that is constructed to highlight

these features It is not intended to represent the way to implementing a real order entry

system

You can view all of the features of the Order Entry example application except the

demonstration of the Picker applet with either the Enterprise Edition or the Personal

Derivations example

Worked examples

423

Edition of Sentences Version 40 You must have the Enterprise Edition in order to view

the demonstration of the Picker applet

Setting up the Order Entry example application

Before you can start the Order Entry example application you must import the

application and make the RenameInstance trigger available to Sentences The

Sentences server must be closed down before you perform both of these actions

Importing the Order Entry example application

To view the Order Entry example application you must import the profile file

OrderEntrylze into Sentences This file is located in the ExamplesDerivations

sub-directory of your Sentences installation Follow the procedure for importing profiles

described in ldquoExporting and importing databasesrdquo An example command line is given

below

Remember that the Sentences server must be closed down before you run the Import

procedure Use the -renumber option when you import this file to create a profile

automatically

Open a command prompt and navigate to the ltSentences_homegt directory and enter

the following command line

ltSentences_homegtimport ndashrenumber sect

ExamplesDerivationsOrderEntrylze

Making the RenameInstance trigger available

The Order Entry example application uses a trigger named RenameInstance which

is included in the ExampleTriggersjar file Make sure that this JAR file is located in

the SentencesTriggers directory so that it is available to Sentences If necessary

copy the JAR file from the ExamplesJars directory

Starting the Order Entry example application

After running the Import procedure and making sure that the RenameInstance trigger

is available start the Sentences server and run Sentences You can now select the Order

Entry example application from the Open Profile dialog box

In the Order Entry example application the entity type Order has the property Instance

name created by trigger defined for it This means that when you create an instance of

the Order entity type you do not need to enter an instance name The name is created

automatically by a trigger The name field on the create Dataform is disabled

The RenameInstance trigger is attached to the Create event for the Order entity type

When this trigger is invoked it renames the instance on which it has been

invoked to a numeric value based on the current time In the Order Entry example

application this is used to assign a unique order number to each order as it is created

The Order Entry example application uses a simple schema based on four main entity

types Customer Order Stock item and Tax Type as shown in Figure 11-7

Derivations example

Worked examples

424

Figure 11-7 The Order Entry example application

Order Entry base Dataform and custom Dataform

The Order Entry example application illustrates the use of Query Editor features to

create a powerful custom Dataform alongside the automatically generated base Dataform

In the following steps you can examine the differences for yourself

1 Highlight the order 1000000001235 in the data pane and right-click to display the

shortcut menu

2 Select ltOrdergt from the Dataform sub-menu This displays the base Dataform for the

Order entity type as shown in Figure 11-8

Figure 11-8 The Order Entry base Dataform

3 Close the Dataform

Derivations example

Worked examples

425

4 Now select Order Entry from the Dataform sub-menu This displays the custom

Dataform for the Order entity type as shown in Figure 11-9 and Figure 11-10

Figure 11-9 Order Entry custom Dataform Order page

Figure 11-10 Order Entry custom Dataform Order details page

The custom Dataform was designed using a query The query includes derivation fields

which are used to calculate values Although these fields can be seen in the base Dataform

they cannot be used

Base Dataform behaviour

The following steps demonstrate the behaviour of the base Dataform for the Order entity

type

1 In the Sentences Explorer highlight the Order entity type and right-click to display the

shortcut menu

2 Select Order ltdefaultgt from the Dataform sub-menu This displays the a blank base

Dataform

3 Type in the following data


4 The custom Dataform displays the Delivery address for an order and not the

Customer address When you create a new customer in this example system you must

create the customer address in a child dataform Right-click the customer name you have

Derivations example

Worked examples

426

just entered (Barney Norris) and select View ldquoBarney Norrisrdquo from the shortcut menu

Type in the following data


Click Apply and then Close

5 The address information is not transferred automatically to the base Dataform and you

need to enter it again manually in the Delivery address field


Create ( order lines stock item) which opens a child Dataform



Quantity 1

Price 2375

The child dataform is shown in Figure 11-11

Figure 11-11 Order line details on the child Dataform

8 Click Apply then Close to return to the Order Dataform

9 In the Tax type field use the drop-down button to select National rate


Sentences does not accept this update Some Dataform fields are highlighted in red and

Sentences displays the Message Log with the message Error 1682 At least one

instance is required of the association type (Order Tax amount

Currency)

The Tax Amount association has been defined in the schema as Mandatory and so the

Dataform update is not accepted However you cannot edit the Tax Amount field

directly as it is an example of a field calculated using a derivation which has also been

defined in the Explorer as Read-only To verify this highlight the Tax Amount

currency association in the Explorer schema pane and open the Format page of the

Properties dialog The Read-only checkbox has been selected

The Order field is also highlighted in red This is because the instance name for a new

order is created by a trigger and the trigger is not activated until all the required data has

been validated

11Close the Dataform without saving the data you entered

Custom Dataform behaviour

The following steps demonstrate the behaviour of the custom Dataform

1 Highlight the Order entity type and right-click to display the shortcut menu

2 Select Order entry from the Dataform sub-menu This displays the a blank custom

Dataform with two tabbed pages

Notice that the Placed on and Last updated fields have been filled automatically

Derivations example

Worked examples

427

3 On the Order page of the Dataform type in the following data as before


4 Remember that the custom Dataform displays the Delivery address for an order and

not the Customer address When you create a new customer in this example system you

must create the customer address in a child dataform Right-click the customer name you

have just entered (Barney Norris) and select View ldquoBarney Norrisrdquo from the shortcut

menu Type in the following data


Click Apply and then Close Sentences copies the customer address details to the

Delivery address field You may change the delivery address in the custom Dataform

5 Click the page tab to display the Order details page and use the picker button to select

National rate for the Tax type field


Create ( order lines stock item) to open a child Dataform



Quantity 1

8 Click Apply Note that the Price and Line total have been calculated automatically

Close the child Dataform

9 In the custom Dataform you can see that the Tax Amount and Gross Total fields have

been calculated as shown in Figure 11-12

Figure 11-12 Calculated values on the Order Entry custom Dataform


11On the Order page the Order field has now been completed with a new order number

as shown in XYZ This number was generated by the RenameInstance trigger which

was invoked when the Dataform was saved

Derivations example

Worked examples

428

Figure 11-13 Completed Dataform with Order number generated by the trigger

12Close the Dataform

The Order Entry query

This section looks in greater detail at the Order Entry query that was used to create the

custom Dataform

The Order Entry profile includes a query which is used to build a custom Dataform The

root of the query is the Order entity type To view the query highlight the query named

Order custom Dataform in the Explorer schema pane and select Edit query from the

shortcut menu The query is shown in Figure 11-14

Figure 11-14 The Order custom Dataform query

The query includes request nodes for the associations directly sourced from Order and

Order lines and the additional information needed for Customers Stock items and

Tax rate which allows the order to be linked to the corresponding address current price

and current Tax rate

The order details section of the query has been placed after the query nodes for the total

and the tax amount This demonstrates that you can place derivations anywhere in a

query In particular the variables used within the derivation expression can refer to nodes

anywhere else within the query

Derivations example

Worked examples

429

The query includes derivations that have been added to delivery address price and Tax

Rate to copy to corresponding value from the targetrsquos association to the order

association

Page Nodes

In the Dataform for Order (Figure 11-8) all the associations sourced from Order appear

on a single page In the custom Dataform there is a division between the details of the

customer and the actual items ordered and their cost To do this two Page nodes have

been added to the query and given suitable names The request nodes corresponding to the

associations sourced from Order have then been moved into the appropriate page The

custom Dataform (Figure 11-9 and Figure 11-10) has two pages with names

corresponding to the page node names and each tabbed page contains the associations as

specified in the query

Derivations

The Order custom Dataform query uses a large number of derivations In order to

differentiate between different associations with the same target types (such as Currency

or Percentage) a number of target nodes in the query have been renamed

Renaming nodes makes them uniquely identifiable but has no other effect

The query contains the following derivations

bull delivery address

This is calculated by copying the address of the customer This derivation is set to

Calculate once and the Editable property is also set which means it can be changed by

the user On the custom Dataform if the field is blank the customers current address is

copied into this field when the Dataform is saved or refreshed Anything that the user

types into this field is retained - a recalculation does not replace it

bull placed on


enter values into this field The Editable property is disabled because of this The

derivation expression uses TimestampNow() which obtains the current date and time

whenever the expression is evaluated The request node in the query is set to Calculate

once which means that it is only calculated when an Order instance is first created

bull last updated

This is similar to the placed on node except that the derivation is set to Calculate on

Save This causes the value to be recalculated when an order is first created and whenever

it is subsequently updated

bull price

This is similar to the delivery address This derivation calculates the ordered itemsrsquo

current price by copying it from the current price association for the item Users may

modify this value

bull line total


enter values into this field on the Dataform The Editable property is disabled because of

this The target is calculated by the derivation expression that multiplies the item price by

the quantity ordered This derivation is set to Calculate always so that if any of the

details on the order line are edited the new total is recalculated

bull Net Total

In this Order Entry example system there is no requirement to store the net total for an

order Therefore this derivation is attached to a derived type which is only displayed in

Derivations example

Worked examples

430

the query results or on a custom Dataform The derived type expression sums all the line

totals and always recalculates which is the standard behaviour for derived types The

properties of the derived type have been set to the Currency datatype with a display style

C000C-000 so that the custom Dataform displays this value as a formatted

currency

bull Tax Rate

This is similar to the delivery address This derivation calculates the Tax percentage to

be applied by copying it from the current rate for the selected Tax type

bull Tax amount


enter values into this field on the Dataform The target is calculated by the derivation

expression that multiplies the result of the Net Total derivation by the result of the Tax

rate derivation to give the amount of tax to be added to the order

This derivation is set to Calculate always so that if any of the details on the order are

edited the Tax amount is recalculated

bull Gross Total


enter values into this field on the Dataform This derivation is set to Calculate always

and is the sum of the Net Total and Tax Amount derivations

Dataform Navigation

Using a custom Dataform gives application designers control of which fields target

dataforms can be accessed by users and so limits the data that users have access to and

can change In the Order Entry example application the custom Dataform allows users to

create new customers or to update customer details when they enter or amend orders It

prevents users from creating or changing Stock items and Tax types

Figure 11-15 Properties dialog for the Customer node

Derivations example

Worked examples

431

Figure 11-15 shows the Properties dialog for the Customer node in the query This

illustrates settings that allow users to select Customer values (can select Customer) to

follow links to child Dataforms (Navigation Default Dataform for Customer) and to

create Customer values (can create Customer)

Figure 11-16 Properties dialog for the Tax Type node

In contrast Figure 11-16 shows the Properties dialog for the Tax type node in the query

This illustrates settings that only allow users to select Tax type values (can select Tax

type) but not to follow links to child Dataforms or to create Tax type values

(Navigation Prohibited)

Figure 11-17 Tree style picker for Customer

In the profile schema the Picker property for the Customer association is set to Tree

This means that items listed in the Picker for this association appear in a tree format

which enables users to identify customers with similar names by checking their addresses

Derivations example

Worked examples

432

The Picker applet for the Order Entry example

An additional way of restricting access to Sentences data is to use an applet embedded in

an HTML page such as the Picker applet based on the Picker available on the Sentences

Dataform


To view the Picker applet copy the file OrderEntryhtml from the

ExamplesDerivations sub-directory of your Sentences installation into the

ltSentences_homegtTomcat4webappsSentences directory

To examine the parameters for the picker applet open the file OrderEntryhtml using

a text editor and compare the settings with the list of parameters in ldquoApplet parameters

for the Picker appletrdquo

Using the Picker applet to enter and update orders


You can view the Picker applet for the Order Entry example file in your browser by

entering a suitable URL If you are using the default installation of Sentences with

Tomcat the URL you need to use is

httplocalhost8090SentencesOrderEntryhtml

You may need to adjust this URL for your installation

Figure 11-18 The Picker applet for the Order Entry example application

The Order Entry browser page presents a Picker display that lists all the existing orders

The positioner and filter fields are available as in any Picker and can be used to locate

items in the displayed list

To edit an existing order double-click on the order or select it and click Edit To create a

new order click Create

Derivations example

Worked examples

433

The picker launches the custom Dataform for Order This Dataform can be used in

exactly the same way as a Dataform launched from the Sentences Explorer

You can now experiment with creating new orders by following the steps given in ldquoOrder

Entry base Dataform and custom Dataformrdquo

Design assumptions used in the Order Entry example

application

The Order Entry example application is a simplified Sentences schema for a fictitious

Order Entry system The design assumptions used in creating this profile are given below

as an example of the kind of issues that you need to consider when designing an

application

The design assumptions for the Order Entry system are as follows

bull Every order has an automatically generated order number assigned to it when it is first

placed

bull Users can create new orders or select and amend existing orders

bull The system automatically records the date and time at which an order was created This

value cannot be changed

bull Orders can be amended at any time The system automatically records the date and time

of the last modification This value is updated every time an order is amended but cannot

be changed by the user

bull The system records all customer names and their address When an order is placed the

name of the customer and the delivery address is recorded in the order The delivery

address is normally the same as the customerrsquos address but it can be modified on the

order

bull Users entering orders can select the name of an existing customer or enter the details of

a new customer

bull There is a fixed list of items in stock that may be ordered Each stock item has a current

price which may change at any time The current price of an item is stored with the order

when the order is created Any changes to the current price of an item must not affect

orders that have already been placed

bull Users entering orders can only select stock items that already exist They cannot create

new items or view or modify the details of any existing stock items

bull An order is made up of one or more order lines Each order line details a specific item

the quantity required the unit price at the time the order is placed and the line total

(quantity unit price)

bull The unit price of an item is taken from the stored current price for the item Users

entering or modifying an order can adjust this price for example for special promotions

or discounts

bull The net total for all items ordered is displayed on the orderrsquos Dataform but is not stored

in the database

bull Tax is added to the net total of an order The tax rate is selected by category The actual

percentage rate is taken from the current rate when an order is placed The current rate can

change at any time and must not affect any orders already placed The actual rate applied

is stored with the order

bull The Tax category selected and the corresponding percentage rate applied is stored with

the order and added to the net total to create the gross total which is also stored with the

order The user cannot modify any of these values Whenever an order is changed (by

adding deleting or amending ordered stock items) these totals are recalculated

Trigger examples

Worked examples

434


As you imported a separate profile for the Order Entry example the original Human

Resources profile was unaffected To restore the original Human Resources profile

choose Open Profile from the File menu and select the profile name

You can completely remove the Order Entry example application by choosing Delete

Profile from the File menu and selecting the profile name and then deleting Order Entry

profile chapters from your chapters directory

Trigger examples

Note The symbol sect indicates that a line of text has been split to allow display in this book

only You should type in the text as one line

A number of example Sentences triggers which can be used with the Human resources

example application are included in the Sentences installation under the Triggers

directory This section describes how these triggers work with the Human resources

example application

The triggers are

bull Refuse Update trigger which can check and refuse any update with which it is

associated

bull Email Address trigger which can test and if necessary refuse updates to email

addresses

bull Auto Number trigger which can create new associations with uniquely numbered

targets for an instance

bull RenameInstance trigger which is used to demonstrate the automatic generation of

entity instance names when the Instance names created by trigger is selected for an

entity type (see ldquoInstance optionsrdquo ) This trigger is demonstrated in the ldquoDerivations

examplerdquo

More details about the function of each of these triggers are given in the relevant

examples

The example procedures for demonstrating the trigger examples refer to the Sentences

Enterprise Edition The triggers can also be demonstrated with the Sentences Personal

Edition

Example trigger classes

The example triggers are implemented as Java classes as follows

bull RefuseUpdateTrigger

bull EmailAddressTrigger

bull AutoNumberTrigger

bull RenameInstanceTrigger

These classes along with other classes located under comsentencesexamples

which they make use of form a Java package named

comsentencesexamplestriggers and are built into a Java archive file

ExampleTriggersjar

Loading the example triggers

If you install the Sentences Application Suite the example triggers file

ExampleTriggersjar is copied from its default location in


ltSentences_homegtTriggers This directory is listed in the TriggerPath property

Trigger examples

Worked examples

435

in the Serverproperties file and therefore the triggers are loaded when you start


If you did not install the Sentences Application Suite you must copy the example triggers

file ExampleTriggersjar from its default location in


ltSentences_homegtTriggers and then restart the Sentences server

The following trigger initialisation messages should be visible along with other Sentences

server messages for example in the Tomcat MS-DOS window

Administrator info trigger Refuse Update instantiated All updates of

associated type and event combinations will be refused

Administrator info trigger Email Address instantiated

Associated hyperlink instances must start with the email HTTP protocol

mailto

Administrator info trigger Auto Number instantiated Update events for any

associated type will generate autonumbering on instances

These messages are not visible when using the Sentences Personal Edition

If you are using the Sentences Enterprise edition and these messages are not visible

check that the Triggers directory is listed in the TriggerPath property in the


Viewing enabled triggers

To view a list of triggers currently enabled on the server select Triggers from the View

menu in the Sentences Explorer Sentences displays the Available triggers list as shown

in Figure 11-19

Figure 11-19 The Available triggers list

Attaching triggers and editing trigger assignments

Triggers are attached to entity and association types by using the Triggers page of the

Properties dialog for the selected type An example of the Triggers page isshown in

Figure 11-20

Trigger examples

Worked examples

436

Figure 11-20 The Properties dialog Triggers page

Details of how to attach a trigger to an entity or association type and how to edit trigger

assignments are given in the section ldquoAttaching a triggerrdquo

Refuse Update trigger example

The Refuse Update trigger simply refuses any update with which it is associated This

action is completely generic and therefore the trigger can be assigned to any Sentences

type and any trigger event and to as many type and event combinations as required

Subsequent transactions which include an occurrence of that event for that type are

refused Schema designers can therefore use this trigger to enforce the refusal of any user

updates they wish

Refuse Update on deleting an Employee

The following procedure shows how the Refuse Update trigger is used to prevent the

deletion of any instance of Employee in the Human resources example application

1 Open the Human Resources example application You should create a new chapter in



Open the Edit Profile dialog Click Add and then New and create a new chapterwith the

name Refuse Update Example and click OK to add it to the profile Do not remove

either of the existing chapters Select the new chapter as the target chapter for Schema

changes Data changes and Query changes The Edit Profile dialog should look like

Figure 11-21

Trigger examples

Worked examples

437

Figure 11-21 Edit Profile dialog for the Refuse Update trigger example

2 Click OK to save the profile



page they need to be deleted for this demonstration If this is the case you may wish to

consult your Sentences administrator before continuing


Refuse Update from the list of triggers and Delete from the list of Trigger Events and

click OK

Figure 11-22 The Triggers page with the assigned trigger

The triggers page should now look as shown in Figure 11-22

Trigger examples

Worked examples

438

5 Click OK to save and then click Close to close the Properties dialog

6 In the Sentences Explorer data pane and select any of the Employee instances for

example Barney Norris

7 Try to delete the selected Employee using either the context menu Delete option or the

tool bar Delete button

Figure 11-23 The Impact of deleting window for the instance Barney Norris

8 Sentences displays the Impact of deletinghellip window showing the list of all the data

affected by the delete action as shown in Figure 11-23 Click the Delete button on this

window to confirm the delete action

Figure 11-24 The Message Log when the delete action is refused

9 Sentences displays the Message Log window with an error message as shown in

Figure 11-24 This error message text is generated by the trigger code For the deletion of

Barney Norris the full text of the message reads

Delete Instance operation on type Employee is refused for instance Barney Norris

by association with trigger Refuse Update

If you are using the Sentences Enterprise Edition you can see a server message in the

servlet container window confirming that the trigger has been assigned

The text of the message is

Administrator info trigger Refuse Update trigger initialised for type Employee

This message is only displayed on the first occasion that the trigger is applied to the type

10Click Close on the Message Log window The selected Employee is still displayed in

the data pane This demonstrates that the trigger has successfully refused the Delete

action

Trigger examples

Worked examples

439

The Refuse Update trigger with subsets and subtypes

Triggers assigned to types automatically apply to subsets of the type You can

demonstrate the application of the trigger to a subset without changing the trigger


1 Highlight the Current employee subset

2 Select an instance of the subset for example Barney Norris and try to delete it

The deletion is refused in the same way as trying to delete an instance of Employee

Triggers assigned to types automatically apply to subtypes of the type If you want to

demonstrate the application of a trigger to a subtype you need to change the trigger


1 Open the Properties dialog for Employee and select the Triggers page

2 Remove the Refuse Update trigger and click OK then Close

3 Open the Properties dialog for Person a supertype of Employee and select the

Triggers page

4 Add the Refuse Update trigger for Delete events using the procedures shown in the

section ldquoRefuse Update on deleting an Employeerdquo

5 Select any of the Person instances in the data pane for example David Quentin and

try to delete it

This action is refused in the same way as the deletion of an Employee previously The

Message Log displays the message

Delete Instance operation on type Person is refused for instance David Quentin by

association with trigger Refuse Update

You can see the same result - that is an attempt to delete is refused - if you try to delete an

instance of a subtype of Person for example the Employee instance Barney Norris

The attempt to delete the employee is refused in exactly the same way as previously when

the trigger was assigned directly to Employee This time however the trigger invocation

occurred because it was assigned to Person the supertype of Employee


If you created a new chapter Refuse Update example as suggested and used it as the


Resources profile by simply editing the profile and removing the new chapter Restore




Email Address trigger example

The Email Address trigger is another example of a validation trigger which checks and

may refuse certain updates Its purpose is to check that email addresses are entered in the

correct format

At the time you assign a trigger to a type Sentences cannot check whether the assignment

is valid or logical This means that the trigger code must be able to check that the

assignment is valid each time it is invoked

Email addresses are usually stored in Sentences using the Hyperlink datatype

Values of this type represent email addresses when they commence with the HTTP email

protocol designator which is the string mailto However the Hyperlink datatype is

Trigger examples

Worked examples

440

also used for other kinds of hyperlinks for example Web addresses which commence

with the string http

The Email Address trigger may be applied either to an association type or to an entity

type The example procedure shows how the Email Address trigger is applied to the

association type Employee email address Hyperlink and ensures that all existing and

new target values for instances of the association type pass its check

It would not be appropriate to attach the Email Address trigger to the Hyperlink entity

type in the Human Resources example application This is because this entity type

like the Hyperlink datatype is used for all kinds of hyperlinks and not just for

email addresses However it is appropriate to restrict Hyperlink instances to those

commencing with the string mailto when they are used as the target of an email

address association

Rejecting incorrect values for email addresses

Use the following steps to demonstrate the behaviour of the Email Address trigger

1 Open the Human resources example application You should create a new chapter in



Open the Edit Profile dialog Click Add and then New and create a new chapter with the

name Email Address example and add it to the profile Do not remove either of the


changes and Query changes The Edit Profile dialog should look like Figure 11-25

Save the profile

Figure 11-25 Edit Profile dialog for the Email Address trigger example

2 In the Sentences Explorer highlight the Employee email address Hyperlink entity

type open the Properties dialog and select the Triggers page If there are any existing

entries on the Triggers page they need to be deleted for this demonstration If this is the

case you should check with your Sentences administrator before continuing

3 Click the Add button Sentences displays the Add Trigger Assignment dialog

Select Email Address from the list of triggers and Create from the list of Trigger

Events and click OK

4 Repeat the previous Add step and select Target Changed from the list of Trigger

Events and click OK

Trigger examples

Worked examples

441

Figure 11-26 The triggers page for the Employee email address Hyperlink association

5 The assignments are displayed on the Triggers page as shown in Figure 11-26 Click

OK on the Properties dialog to apply the assignments


Barney Norris and select Default Dataform from the shortcut menu

7 Click the ellipsis button for the Email address association and select a value

from the picker list which is not a valid email address for example the value

httpwwwsleepysoftcom Click Save

8 The trigger prevents Sentences from accepting this association instance update because

the association target fails the triggerrsquos checks This is indicated in two ways both shown

in Figure 11-27

bull the Dataform highlights the incorrect data and the page it is on in red

bull the Message Log displays an error message

Trigger data error An instance of the entity type Hyperlink has been found

with a value of ldquohttpwwwsleepysoftcomrdquo This fails the requirements of the

type (Employee email address Hyperlink) enforced by the trigger Email

Address

Figure 11-27 Email Address trigger rejects incorrect update

Trigger examples

Worked examples

442

9 If you are using the Sentences Enterprise Edition an initialisation message is displayed

in the servlet container window as this is the first invocation of the trigger against this

type

Administrator info trigger Email Address trigger initialised for type

(Employee email address Hyperlink)

10 Click the ellipsis button for the Email address association again and select a value

from the picker list which is a valid email address for example

mailtobarneynsleepysoftcom Click Save

This update is accepted and the fields and text revert to their normal colours


If you created a new chapter Email Address example as suggested and used it as the


resources profile by simply editing the profile and removing the new chapter Restore




Auto Number trigger example

The Auto Number trigger is an example of a trigger which adds data to an update It

automatically creates positive integer numbering for instances of any type it is associated

with when an instance is updated provided the requirements detailed below are met The

data generated by this trigger cannot be changed by users

This trigger is an example of how a generically coded trigger can achieve its purpose with

a minimum set of fixed dependencies and can be applied as widely as necessary by the

schema designer

Remember that Sentences server triggers act on user updates but not on data that is only

viewed Triggers are not applied to existing data until that data is the subject of a user

update

The Auto Number example trigger has the following requirements

bull A single entity type named Auto number must be defined by the profile

bull The datatype of that entity type must be Number

bull Any type to be auto-numbered must be the source type for an association type with Auto

number as its target type

bull Instances of that association type must obey the Singular inverse cardinality rule (see

ldquoSingular inverserdquo )

bull Target values for all instances of the association type must be positive and integer

When the Auto Number trigger is invoked for the first time it executes an initialisation

method which checks these requirements If the requirements are not met the trigger does

not operate on the assigned type

You can define an association type as Read only by checking the Read only check box

on the Format page of the Properties dialog In this case values cannot be added through

the Dataform If the Auto Number association type is defined as Read only then the

numbering is purely automatic If the Auto Number association type is not defined as

Read only then you can enter numbers on the Dataform and these number values are

checked by the trigger code

Defining the Auto Number association type as Singular inverse guarantees the unique

numbering which the trigger checks for when it initialises

Trigger examples

Worked examples

443

The trigger can be applied to many Sentences types simultaneously The same entity type

Auto Number must be used as the target type for all the numbering association types

The numbering is applied independently for each Auto Number association type so each

numbered source type is numbered independently in ascending sequence

Auto-numbering always uses the next available increasing positive integer for a new

numbering association If the association type is not defined as Read only you can enter a

number value on the Dataform which becomes the new starting value for numbering of a

type

Use of the Number datatype for the numbering entity type Auto number allows that

type to support the triggerrsquos operation because value instances cannot be deletedor

renamed (see ldquoBehaviour of value types and valuesrdquo )

Setting up the schema to use the Auto Number trigger

Before you can run the demonstration of the Auto Number trigger you need to make some

changes to the schema of the Human resources example application

1 Copy the file Human resources employee id schemachap from the

ExamplesChapters directory to the directory where your chapter files are located

If a copy of this chapter already exists in your chapters directory it is possible that this

demonstration has already been run on your installation In this case the Auto Number

trigger may generate different values from those shown in this text

2 Shutdown and restart the Sentences server so that Sentences recognises the new chapter

file If you are running the Personal Edition restart Sentences

3 When the server has restarted open the Sentences client and select the Human

resources profile If this profile is already running in the client refresh the display

4 Open the Edit Profile dialog Click Add and then New and create a new chapter with

the name Auto Number example and add it to the profile Do not remove either of the


changes and Query changes

5 Click Add again and add the chapter Human resources employee id schema to

the profile The Edit Profile dialog should look like Figure 11-28 Save the profile

Figure 11-28 Edit Profile dialog for the Auto Number trigger example

Trigger examples

Worked examples

444

6 In the Sentences Explorer schema pane select the Employee entity type and then select

one of the instances of Employee in the data pane for example Barney Norris Open

the Dataform on this instance The Dataform includes the newEmployee ID association

type as shown in Figure 11-29

Figure 11-29 Employee Dataform showing Employee ID association

If the new association type does not appear in the Dataform check the Edit profile dialog

to verify that the additional chapter Human resources employee id schema has

been added to the profile

If the additional chapter is listed in the Edit profile dialog but the Employee ID field is

not shown in the Dataform it may mean that another user has made changes to your copy

of the Human resources profile You can restore the original Human resources profile

chapters by copying the original chapter files from the Exampleschapters directory

of your Sentences installation

If the Employee ID association shows a target value for Employee number in the

Dataform this means that this trigger has already been demonstrated on your system You

should create a new temporary chapter for example Auto Number Example 2 and try

again

1 In the All types folder of the Sentences Explorer schema pane select the Auto number

entity type Open the Properties dialog and select the Datatype page as shown in Figure

11-30

Trigger examples

Worked examples

445

Figure 11-30 The Datatype page for the Auto Number entity type

The datatype of Auto number should be defined as Number and the maximum number

of decimal places as zero The code for this example trigger is designed to work when

instances of Auto number can be treated as numeric values and when the Auto number

entity type and all its instances use the same datatype

The Number datatype in Sentences defines a value type Value instances cannot be

deleted or renamed This complements the function of the trigger by ensuring that values

once created cannot be changed by a user

When these settings are correct close the Properties dialog

2 In the All types folder of the Sentences Explorer schema pane expand Employee and

select the association verb employee ID Open the Properties dialog and select the

Format page Make sure that the Read only on Dataform check box is selected as


Trigger examples

Worked examples

446

Figure 11-31 Format page for the Employee ID association

When the Read only on Dataform property for an association type is set Sentences does

not allow users to enter association values When you have checked that this setting is

correct close the Properties dialog

Demonstrating the Auto Number trigger

The following procedure shows how the Auto Number trigger creates employee

numbering data for the Human resources example application To do this each time an

Employee instance is the subject of an update the Auto Number trigger checks if there is

a target value for the Employee ID association If no value exists the trigger assigns the

next available number to the Employee If the user has entered a number the trigger

checks its value

When the Auto Number trigger is invoked it finds the highest existing target value of an

Employee ID association and uses that number plus one as the starting value for

subsequent numbering If no instances of the association are found the default starting

value of 1 is used



page they need to be deleted for this demonstration If this is the case you should check

with your Sentences administrator before continuing


Auto Number from the list of triggers and Create from the list of Trigger Events and

click OK

3 Click the Add button again and select Auto Number and Attribute Changed in the

list of Trigger Events and click OK

4 The two assignments should be displayed in the trigger assignments table as shown in

Figure 11-32 Click OK on the Properties dialog to apply the assignments

Trigger examples

Worked examples

447

Figure 11-32 The triggers page for the Auto Number trigger on Employee


Barney Norris and select Default Dataform from the shortcut menu You should see

Employee ID ltAuto numbergt as the first association on that Dataform as shown in

Figure 11-29

If a value is already shown for ltAuto numbergt this means that residual data remains in

the database from a previous demonstration of this example

6 In the Sentences Explorer schema pane All types folder select Auto number At this

stage you should not see any values in the data pane If values are present they are left

over from a previous demonstration of the Auto Number trigger and you should be able

to remove them by removing the temporary chapter in which they were created If you do

not remove this chapter the values that Sentences displays for Employee ID may be

different from those described in the following steps

7 In the Sentences Explorer schema pane select Employee and open the Dataform to

create a new instance The first page displayed is the Person page Select the Employee

page and check that no data is shown for this new person

You cannot type in the Employee ID target field Although you can place your cursor in

this field and select the field value Sentences does not accept any keyboard input for this

field because the association type has been defined as Read only This is because the

values for this field are to be generated by the trigger code

8 On the Person page type in a name for a new employee Steve Meyer Click Save

and Edit

9 Select the Employee page The next available Employee number value 1 has been

used as the target for an automatically generated Employee ID association 10If you are

using the Sentences Enterprise Edition an initialisation message is displayed in the

servlet container window as this is the first invocation of the trigger against this type

Administrator info trigger Auto Number trigger initialised for type Employee

Numbering of instances will begin at 1

11Click the Yes radio-button for Project resource and click Save Steversquos employee

ID still shows as 1 Once calculated it should never change Click Close

Trigger examples

Worked examples

448

12Select Barney Norris and open the Dataform To create an Employee ID value for an

existing employee you must update the database in a way that references the Employee

An update which results in no net change to the database does not invoke a trigger

13Click the Project resource radio-button again and click Save The next available

value 2 should show as the Employee ID for Barney Click the radiobutton again to

restore its original value and click Save and then click Close

14In the Sentences Explorer schema pane All types folder select Auto number The

values just created (1 and 2) are shown

Cases in which the Auto Number trigger is not invoked

The Auto Number trigger is only invoked when the instance to be numbered is either

created or updated The following procedure illustrates an action that can be taken that

involves an instance of Employee but does not update the instance In this case the Auto

Number for the Employee ID association is not created

1 Select the Employee instance Freda Quentin in the data pane and open the Dataform

The Employee ID association has not yet been set for Freda

2 Select the Resource skills page Double-click over the table line Java Novice to open

a child Dataform on this association Click the ellipsis button for Expertise and select the

value Competent Click Apply and then click Close

3 Click Save on the Resource page The changed data is now displayed in the table

4 Select the Employee page The employee ID value is still not set

This is because although an update was submitted and committed to the database it did

not reference an Employee as its subject or source Instead the source type for the update

was Employee skill Skill

5 Select the Resource skills page Right-click over the empty table space and select

Create (hellip skill Skill)hellip from the shortcut menu In the child Dataform that opens use

the picker to select a skill of C++ and an expertise of Novice

Click Apply and then click Close and then click Save on the Resource Skills page

6 Select the Employee page The Employee ID value has now been set The new skill

association you created had an Employee as its source As a result the trigger was

invoked and was able to update that Employee and create an Employee ID association

for Freda

Using the Auto Number trigger when user entries are allowed

The following steps illustrate how the Auto Number trigger can be used when users are

allowed to enter numbers that is when the association type is not defined as Read only

1 Select the association type Employee employee ID Auto number in the schema

pane and open the Properties dialog and select the Format page Clear the Read only

checkbox and click OK and Close

2 Select any Employee in the data pane If you select an Employee who already has a

number for example Barney Norris you can replace that number with a new value

(This action does not succeed if the Refuse Update trigger is currently loaded) If you

select an Employee who does not yet have a number for example John Atkins you can

enter a number for the first time For the purposes of this demonstration select an

Employee who does not yet have a number for example John Atkins

3 Select and type into the Employee ID target field This is now enabled as the Read

only setting on the association type has been removed Enter an unacceptable value for

example ndash1 and click Save The trigger detects that a value has been entered and checks

it The value entered is not acceptable and hence is rejected The Message Log displays

an error message

Trigger examples

Worked examples

449

Trigger data error An instance of the autonumber entity type Auto number has

been found with a value of -1 Values are required to be greater than zero by

trigger Auto Number

4 Repeat the above step entering a positive but non-integer value for example 25 This

value is also not acceptable to the datatype setting of zero decimal places The datatype

check is applied before the user trigger is invoked hence this value is rejected by the

datatype The Dataform highlights the incorrect data and the page it is on in red If Save

is clicked the Message Log displays an error message

1622 Bad value for ldquoEmployee IDrdquo

5 Repeat the above step entering a value which is already in use for this association type

for another employee for example 2 The trigger detects that this value is already in use

for this association type and rejects the update with the error message

Trigger data error An instance (2) of the autonumber entity type Auto number

has been found to be the target for more than one instance of the numbering AT

(Employee employee ID Auto number) eg (Barney Norris employee ID 2) This

condition is disallowed by the trigger Auto Number

Having demonstrated the error detection capabilities of the trigger for data entry we can

now illustrate how the auto-numbering uses the highest existing target value for the

association type to determine the next number to assign

1 Select an Employee who does not yet have a number for example John Venice and

open the dataform Select and type into the Employee ID target field a new high value

for example 100 and click Save

2 Now select another Employee who does not yet have a number for example Mark

Goldstone and open the dataform Click the Project resource radiobutton and click

Save The next available value 101 should show as the Employee ID for Mark


To restore the Human resources example application you must first edit the profile and

remove the additional schema chapter Human resources employee id

schemachap from the profile If you created a new chapter Auto Number example as

suggested and used it as the target for both schema and data changes in the profile you

must remove this chapter as well the new chapter Restore the original schema and data

changes chapters and save the profile



Disabling the example triggers

To unload the example triggers you should use the following procedure

1 Remove all assignments of the triggers to any type in the schema for example by

following the procedures to restore the original Human resources example application

for any of the trigger demonstrations which you have used

2 Remove the trigger JAR file from the defined location for triggers on the Sentences

server This location is specified by the TriggerPath property in the


TriggerPath=ltSentences_homegtTriggers

3 Restart your Sentences server and refresh any open profiles at the running clients If

you are using the Personal Edition restart Sentences


Worked examples

450


A simple example custom datatype which can be demonstrated with the Human

resources example application is available in your Sentences installation

The example implements a datatype called TelecomsNumber as the Java class

Telecoms which is itself defined in a Java package called

comsentencesexamplesdatatypes (in the subdirectory

comsentencesexamplesdatatypes) The example consists of a source code file

Telecomsjava and a built Java archive ExampleDatatypejar

About datatype classes

A Sentences custom datatype can only be created as a Java class which implements the

Sentences LazyDatatype interface An effective way to achieve this is to extend the

default implementation of this interface in the class LazyAbstractDatatype Another

way to do this is to sub-class an existing specific Sentences datatype The directory

ExamplesExistingDatatypes contains the source files for the interface

LazyDatatype and for its top-level implementations LazyAbstractDatatype

LazyNumber and LazyString as well as for the other Sentences datatypes The

interface and the listed classes are described within the Javadoc documentation for the

API

Loading the custom datatype example

If you install the Sentences Application Suite the example datatype file

ExampleDatatypejar is copied from its default location in

ltSentences_homegtExamplesJars to the datatype directory

ltSentences_homegtDatatypes This directory is listed in the DatatypePath

property in the Serverproperties file and therefore the datatypes are loaded when

you start the Sentences server

If you did not install the Sentences Application Suite you must copy the example datatype

file ExampleDatatypejar from its default location in

ltSentences_homegtExamplesJars to the datatypes directory

ltSentences_homegtDatatypes and then restart the Sentences server

Checking the example custom datatype

1 Select the Telecoms number entity type and open the Triggers page of the Properties

dialog to make sure that no trigger has been enabled for it If a trigger has been enabled

you cannot test the custom datatype properly See the section ldquoDisabling the example

triggersrdquo for instructions on how to remove any of the example triggers if necessary

2 Restart the Sentences server and open the Sentences client Open the Properties dialog

for any entity type and select the Datatypes page TelecomsNumber should now be

found in the drop-down Datatype list

If the new datatype is not visible this may be because of the way that data caching is

implemented on the computer running the Sentences client Check your browser and Java

Plug-in settings You may need to shut down and restart your Web browser and servlet

container to try and resolve this problem

If Sentences displays an error message at the client check the Sentences trace file at the

server for details If no trace file is present check the configuration changes made to the

servlet container configuration for example in the tomcatbat file

References to datatype classes including custom datatypes are used at several levels

within Sentences For example references to datatype classes are stored with any entity

instances which were created with their use Because of this custom datatypes should be

used with caution when only being demonstrated or still under development


Worked examples

451

Unloading the example custom datatype

To unload a custom datatype remove the custom datatype JAR file from the defined

location for datatypes on the Sentences server This location is specified by the

DatatypePath property in the Serverproperties file The default location is










which is why we recommend using a new data chapter specifically for the purpose of

demonstrating custom datatypes



datatype

Custom datatype example TelecomsNumber

The TelecomsNumber datatype is a simple example datatype for telephone numbers

which extends the base Sentences datatype of LazyString This datatype only accepts

numbers beginning with a plus sign (+) and consisting of digits parentheses and spaces

only

This custom datatype supports two format styles

bull Full which displays the number formatted as entered

bull Number only which displays the number as only the leading plus sign and digits

This example datatype is provided to illustrate the datatype mechanism and not as a

suggestion of how telecoms numbers should be implemented in Sentences applications

Note The symbol sect indicates that a line of code has been split to allow display in this

book only You should type in the code as one line

Using the example custom datatype

Use the following steps to try out the behaviour of the TelecomsNumber example

custom datatype with the Human resources example application

1 Open the Human resources example application and open the Edit Profile dialog

You must add a new chapter to the Human Resources profile for this demonstration and

use it as the Data changes chapter If you do not use a new chapter as the Data changes

chapter it may be difficult to remove all references to the custom datatype after you

complete this demonstration (see ldquoUnloading the example custom datatyperdquo )

2 In the Edit Profile dialog click Add and then New and create a new chapter named

HR custom datatype test data and add it to the profile Use this chapter as the target

chapter for Data changes but do not remove either of the existing chapters Check that

the Edit Profile dialog looks like Figure 11-33 and save the profile


Worked examples

452

]

Figure 11-33 Edit Profile dialog for the Custom Datatype example

3 Highlight the Telecoms number entity type from the All types folder in the Sentences

Explorer schema pane and select Properties from the shortcut menu Select the Datatype

page and check that the Datatype field is set to ltNonegt

If this field shows any value other than ltNonegt then your database may have already

been customised by another user

Figure 11-34 Selecting the TelecomsNumber datatype

4 Click the down arrow on the Datatypes field and scroll through the list of available

datatypes and select the example custom datatype TelecomsNumber as shown in Figure

11-34 and click OK and then Close to close the Properties dialog

5 Reopen the profile to refresh the schema or select Refresh from the toolbar


Worked examples

453

6 Select Telecoms number again You can see that there are now no values displayed in

the data pane This is because when an entity type has a datatype assigned to it only the

instances that have the same datatype are displayed

If you can see instances of Telecoms number at this stage it means that your database

may have already been customised by another user or that you did not create a

completely new chapter as the Data changes chapter for this demonstration

The TelecomsNumber datatype is defined as a value datatype and Telecoms number is

therefore a value type and can only be used as a target and not as the source of

association types

The TelecomsNumber datatype requires that all instances start with the + character and

only contain numerals and parentheses characters ( ( and ) )

1 Highlight the Person entity type and open the Default Dataform from the shortcut

menu Create a new instance with the name Arthur Test and enter the following value in

the Home telephone association field

1 (212) 262 4515

This value is not valid Click Save amp Edit or tab out of the field Sentences indicates an

invalid value by highlighting the Person page and the Home telephone number field in

red Sentences also displays an error message in the Message Log because the value does

not commence with the character +

2 Enter the value

+ 1 [212] 262 4515

the Home telephone number field and tab out of the field

Sentences rejects this value also because the value contains square bracket characters ( [

and ] ) that the datatype does not allow The Home telephone number field remains

highlighted with a red background and displays the string +12 (345) 678 9123 which is

an example of the correct format for a valid value

3 Enter the value

+ 1 (212) 262 4515

the Home telephone number field and click Save amp Edit followed by Close Sentences

accepts this value and display it in the data pane when you select Telecoms number in

the schema pane

4 In the Sentences Explorer schema pane select the Person entity type and select an

instance of Person for example Barney Norris Open the Dataform for Barney Norris


Worked examples

454

Figure 11-35 Previous data no longer visible in Dataform

The Home telephone and Work telephone associations on the Person page of this

Dataform are empty and display the place-holder text ltTelecoms numbergt as shown

in Figure 11-35 This is because these association types use Telecoms number as their

target As you have just changed the datatype for this Telecoms number any instances

created before the change of datatype are no longer visible

5 Click the ellipsis button on the Home Telephone association field and select the

only available value from the picker list This is the new value you have just created +1

(212) 262 4515 Click Save

6 Type in a valid value for the Work telephone association field for example +1 (212)

544 6241 and click Save Sentences accepts the update Click Close on the Dataform

7 Select Telecoms number in the Explorer schema pane Only the newly created valid

values for Telecoms number are displayed in the data pane

The default Style for the TelecomsNumber datatype is its Full format You can select

Full or Number only by using the Style field on the Format page of the Properties

dialog Select the Telecoms number entity type in the schema pane and open the

Properties dialog and select Number only for the Style field and click OK on the dialog

to apply the change then click Close

8 Click the Refresh button on the toolbar The display of values for Telecoms number

throughout Sentences now appears in the Number only style as a leading + followed by

digits only

9 Select Telecoms number and select Properties from the shortcut menu Select the

Datatype page and set the datatype to ltNonegt Click OK and Close

10Click the Refresh button on the toolbar The original values for Telecoms number

are now visible Scroll to the end of the list of instances in the data pane using the

Morehellip prompt if necessary The newly created values are visible and are listed after the

original instances This is because datatype ltNonegt allows visibility of all other

datatypes The new values are in a separate group because values are sorted in

independent groups by datatype These instance are displayed in the default style for their

datatype as they are not of the current datatype for the entity type

Restoring the original Human resources example application

To restore the original Human resources example application follow these steps

1 Set the datatype of Telecom number back to TelecomsNumber

Client API example

Worked examples

455

2 Open the dataform on the Person you edited (Barney Norris) Delete the instances

you created for the Home telephone and Work telephone associations Click Save and

Close

3 Delete the additional Person instance you created (Arthur Test)

4 Reset the datatype of the entity type Telecom number to ltNonegt Refresh the data

pane display of Telecom number instances

5 Open the Edit Profile dialog Highlight the HR custom datatype test data chapter

and click remove Make the existing chapter Human Resources data the Data changes

chapter and save the profile

6 Remove the custom datatype JAR file from the defined location for datatypes on the

Sentences server This location is specified by the DatatypePath property in the



Alternatively set the datatype of the entity type Telecom number to ltNonegt and

remove the HR custom datatype test data chapter from the profile

Client API example

A simple example of using the Sentences Client API is included in the Sentences

installation This is a Java program called SalaryUpdate implemented in a Java class

SalaryUpdate and defined in a Java package called

comsentencesexamplesclient (under the directory Examples) The example

consists of a source code file SalaryUpdatejavaand a built Java archive

SalaryUpdatejar in the subdirectory Jars

This section demonstrates the use of SalaryUpdate with the Human resources

example application As this program uses the Client API it can run alongside other client

access to the Sentences database The Sentences server must be running to allow the

SalaryUpdate program to access the database

In the Human resources example application Employees have employment history

events including salaries recorded by date The SalaryUpdate program takes two

arguments on its command line which are the Employee to be updated and the new

Salary value to assign The program first lists all the existing salary events for the

Employee then creates a Raise event assigning the new salary with effect from todayrsquos

date

Preparing to run the demonstration

This example is a standalone Java program which must be run using a Java 13 or higher

compliant virtual machine The following instructions are based on the following

assumptions

bull You are running the Sentences server on a Microsoft Windows operating system

bull Your installation of Sentences is in CProgam FilesLazySentences40

If your copies of Java and Sentences are in different locations you must modify the path

names in these instructions accordingly

Using the Salary Update example

The client-side API used by this example program requires that the Sentences servlet is

running and therefore it cannot be used with the Sentences Personal Edition

The following conditions must be met before you can run the example program All these

conditions are met automatically if you are using a default installation of Sentences with

Tomcat The conditions are

Client API example

Worked examples

456

bull The example program must be run on the machine where the Sentences server is

installed This is because the example code uses a fixed value for the Sentences

connection host (localhost) It also guarantees local access to the required Sentences

JAR file and Java installation

bull The Sentences server must be serviced by a Web server responding to a fixed IP port

number port 8090 This is because the example code uses a fixed value for the port

number

bull The Web server and servlet container for Sentences must be running and able to start the

Sentences servlet

bull You must know the location of and have access to the Sentences Enterprise Edition

installation and an installation of the Java 2 Runtime Environment (J2SE JRE)

In addition to these conditions you must adapt your Sentences installation to enable Client

API connections as described in the following section

Enabling Sentences Client API connections

You must make sure that client API access to Sentences is enabled for your installation

Although access is enabled in the default installation of Sentences the default setting may

have been changed for some reason To verify that access is enabled follow these steps

1 Using a text editor open the Serverproperties file and locate the section headed

Access to the different Sentences Servlets

2 Find the setting for the client API servlet which is

ClientApiAccess

3 Make sure that this setting is set to true as follows

to

ClientApiAccess=true

4 Save the file then stop and restart your Sentences server

Setting up the demonstration profile

You need to create a new profile to demonstrate the SalaryUpdate program

1 Ensure that your Sentences server is running start the Sentences client and open the

Human resources example application

2 Open the Edit Profile dialog and create a new profile named Human resources API

updates

3 Use the Add and New options to create a new chapter The chapter can have any name

you like for example API updates chapter Use this chapter as the target for Data

changes Set the target for Schema changes to (none)

4 Click OK and Yes to save this new profile

Creating a command file

The example SalaryUpdate program must be run from a command line The actual

command needed to run this program may be quite long (depending on the actual file

paths used on your system) so you must create a batch file to run the program as follows

1 Make a copy of the batch file lazystartbat in the

ltSentences_homegtResources directory and name it SalaryUpdatebat Move

this file to the ltSentences_homegt directory and open it using a text editor

2 In the CP (classpath) section add the following two new lines immediately after

the line set CP=SENTENCES_HOME

set CP=CPSENTENCES_HOMETomcat4webappssect

Client API example

Worked examples

457

SentencesSentencesjar

set CP=CPSENTENCES_HOMEExamplesJarsSalaryUpdatejar

3 In the Java Execution command section edit the last line of the file to include the

path to the Salary Update example classes as follow

_RUNJAVA JVM_OPTS -cp CPsect

comsentencesexamplesclientSalaryUpdatesect

1 2 3 4 5 6 7 8 9

4 Save the file as plain unformatted text in the Sentences_home directory The

Salarybat file you have created invokes the Java interpreter passes it the example

specific and Sentences client Jar files as a classpath argument then specifies the example

specific class as the program entry point and passes it up to nine arguments as entered on

the command line

Demonstrating the Salary Update example

The following procedure demonstrates how the example client API program can submit

updates to the database It assumes that all the previous procedures within this section

have been successfully completed

1 Ensure that the Sentences server is running start the Sentences client and open the

Human resources API updates profile

2 Highlight the Employee entity type in the Explorer schema pane select the Employee

instance Barney Norris and open the Default Dataform

In the dataform for Barney his employment history is shown in the table titled Event

His last salary change from 01-May-2000 shows that his latest salary is $76500 Itrsquos

time for Barney to get a raise Leave the dataform open

3 On the host where the Sentences server is installed open an MS-DOS prompt window

and navigate to the Sentences installation directory where you saved the command file

SalaryUpdatebat

4 At the MS-DOS prompt enter the following command

SalaryUpdatebat ldquoBarney Norrisrdquo USD83500

5 As it is running the salarybat command should output messages similar to the

following

6 If the final line of the message is not Successful completion there has been an

error and you may see the text

User message ERROR in class SalaryUpdate ERROR exit

followed by a description of the error

If the entered Employee was not found the error description is similar to

The requested Employee Barney Norriss was not found

CProgram FilesLazySentences22gtSalaryUpdatebat Barney Norris

USD83500

User message class SalaryUpdate Sentences Example code started

Human

resources API updates

User message class SalaryUpdate Opening Sentences client session to

host localhost port 8090 and profile Human resources API updates

Salary history for Employee Barney Norris

01-Jun-1997 Joined $47000

01-Feb-1999 Raise $58500

01-May-2000 Promoted $76500

User message class SalaryUpdate Salary update performed

Successful completion


Worked examples

458

If the entered Salary was not valid the error description is similar to

The supplied salary value USD 83500 was incorrectly formatted

Other possible causes of error include

bull mistakes in the SalaryUpdatebat file

bull mistakes in the entered arguments

bull the Sentences server is not running

bull you have not enabled Client API connections at the server

bull you are running the Sentences Personal Edition instead of the Enterprise Edition

7 Return to the open dataform on Barney Norris in your Sentences client The data

displayed is unchanged as Sentences does not push data changes to clients

8 Close and re-open the dataform on Barney Norris The Event table now shows his

updated employment history including his new salary $83500 with todayrsquos date

9 You can repeat these actions with other inputs to demonstrate the program further


To restore the database to its original condition do the following

1 Delete the profile you created for this demonstration Human resources API

updates

2 You may wish to disable subsequent client API connections to the Sentences server To

do this reverse the steps you took to enable client API connections (see ldquoEnabling

Sentences Client API connectionsrdquo )


You can use CSV Export (see ldquoCSV Exportrdquo ) and CSV Import (see ldquoCSV Importrdquo ) to

integrate data from Sentences with Microsoft Office applications

For example you can use Sentences data with Microsoft Word to create Mail merge

documents and email messages and with Microsoft Outlook create Contacts data

You can also import data from Microsoft Outlook Contacts into Sentences In some of the

following procedures you can use data exported from Sentences directly in a Microsoft

Office application and in other procedures you need to modify the data using another tool

such as Microsoft Excel before it can be used

The procedures in this section have been tested with Microsoft Office 2000 running on

Windows 98 and Window NT 40 operating systems Some of the commands used in

these examples may be slightly different in other versions of Microsoft Office

These procedures can be used with either the Sentences Enterprise Edition or the


Creating Mail merge letters from Sentences data


Mail merge letter in Microsoft Word You must first use a query in Sentences to select

the data you want to use and then export the query result as a CSV file

To generate a Microsoft Word Mail merge letter using names and addresses from a


Exporting address data from Sentences

1 In Sentences create or configure a query to return names and addresses for the



Worked examples

459

bull using an existing query or create a new query or

bull using a parameter to select the correct recipients for each letter or


should receive them

An example query for this purpose which returns the names and addresses for


Figure 11-36 Sentences query for Employee mail merge





on Windows is csv

4 Using Microsoft Notepad or a similar text editor open the CSV file you saved The file

should look like the one shown in Figure 11-37

Figure 11-37 CSV Export output file in a text editor


Worked examples

460

Importing address data into Microsoft Word

1 In Microsoft Word create your form letter and use place-holders such as name and

address where you want merged data to appear




letter you have prepared

4 In step 2 Data source select Get data and then Open data source and then navigate

to the directory where you saved your CSV file Microsoft Word does not include the

csv extension in the list of file options so you need to select All types to select your

file When you have selected your file click OK


5 Highlight one of the place-holders in your document and select Insert Merge field

from the Mail merge tool bar If the Mail merge tool bar is not visible select Toolbars

and then Mail merge from the View menu

6 Select the field you want to use from the list of fields for example Employee You

must repeat this step for every field you want to insert The merge field names are derived

from the first line of the CSV file which is treated as a line of column headings Second

and subsequent columns of the CSV file are named by Sentences with a combination of

their entity type and association type verb As an example the Employee address column

from the example application appears as merge field Addressaddress Do not change the

column headings line

7 Select the Merge button and in the dialog box select New document and then click

Merge Microsoft Word creates a new document containing one form letter for each set of

data in the CSV file This document can be saved printed and also edited as you require

Creating Mail merge emails from Sentences data


Mail merge electronic mail messages (emails) in Microsoft Word You must first use a

query in Sentences to select the data you want to use and then export the query result as a

CSV file You must the edit the CSV file in Microsoft Excel before you create your

emails

The Mail merge email procedure requires you to have a Messaging Application

Programming Interface (MAPI) compliant email package such as Microsoft Exchange

installed on your system

To generate a Microsoft Word Mail merge email using names and addresses from a


Exporting email data from Sentences

1 In Sentences create or configure a query to return names and email addresses for the



bull using a parameter to select the intended recipients for an email

bull adding one or more entity types or association types to define email types and who

should receive them

An example query for this purpose which returns the names and email addresses for



Worked examples

461

Figure 11-38 Sentences query for Employee email mail merge





on Windows is csv

Figure 11-39 Email query output in Microsoft Excel

Modifying the email data CSV file in Microsoft Excel


Figure 11-39 Note that any Employee who does not have an email address in the

Sentences database is shown without an email address in the CSV file

2 Sentences requires the protocol string mailto in email addresses but the MAPI mail

program does not To remove it select the Replace option from the Edit menu and type


Worked examples

462

in the string mailto (with a space at the end) in the Find what field Leave the

Replace with field blank and click Replace all


delimited)

Importing email data into Microsoft Word

1 In Microsoft Word create the text of your email and use a place-holder such as name

where you want merged data to appear The email address does not need to appear in the

standard document

2 If you want your the text from your main document to appear in the body of your

email you should save the document as plain text with no formatting Use the Word Save

as type option Text Only If you save your document as a formatted Word document it is

sent as an email attachment




email you have prepared

5 In step 2 Data source select Get data and then Open data source and navigate to

the directory where you saved your CSV file from Excel Microsoft Word does not

include the csv extension in the list of file options so you need to select All types to

select your file Be sure to select the file with edited email addresses as saved from

Excel not the file as output from Sentences When you have selected your file click OK


6 Highlight one of the place-holders in your document such as name and select Insert

Merge field from the Mail merge tool bar If the Mail merge tool bar is not visible select

Toolbars and then Mail merge from the View menu

7 Select the field you want to use from the list of fields for example Person You need to

repeat this step for every field you want to insert

8 Select the Mergehellip button and in the dialog box select Electronic mail and then click

Setup

9 In the field Data field with MailFax addresses select the column name from the CSV

file which contains the email addresses With the Human resources example application

this column is named with a combination of its entity type and association type verb as

Hyperlinkemail_address

10Type in some text for the email subject line in the Mail message subject line field

11If you have created a formatted document select the Send document as an

attachment checkbox If you have created a plain text document leave this checkbox

clear Click OK to return to the Mergehellip dialog box

12In the Mergehellip dialog box click Merge Microsoft Word creates an email message

which is sent to each email address in the CSV file A copy of each message is placed in

your Sent Items folder

Creating Microsoft Outlook Contacts from Sentences data

You can export data from Sentences to for use in a Microsoft Outlook Contacts folder

You must first use a query in Sentences to select the data you want to use and then export

the query result as a CSV file You then need to edit the CSV file in Microsoft Excel

before you import it into Microsoft Outlook After import you need to configure the

Outlook folder for use as an address book


Worked examples

463

Exporting Contacts data from Sentences

To create a CSV file follow these steps

1 In Sentences create or configure a query to return the data you want for each person

such as name address phone number email address and so on This may be either


bull using a parameter to select the correct recipients for each letter


should receive them

An example query for this purpose which returns the name address home telephone

work telephone email address and date or birth for Persons from the Human resources

example application is shown in Figure 11-40

Figure 11-40 Sentences query for Outlook contacts

2 In the Sentences Explorer highlight the query name and run Export to CSV filehellip

from the Results option on the Query menu or on the right-click context menu



on Windows is csv


Worked examples

464

Figure 11-41 Outlook contacts query results in Microsoft Excel

Modifying Contacts data in Microsoft Excel


Figure 11-41

2 Sentences requires the protocol string mailto in email addresses but the Outlook

does not To remove it select the Replace option from the Edit menu and type in the

string mailto (with a space at the end) in the Find what field

Leave the Replace with field blank and click Replace all


delimited)

Note You do not need to delete any duplicate columns in your file If you are planning to

import data from an Outlook Contacts folder into the same Sentences database then you

can refer to this CSV file to learn what column structure matches the database

Importing Contacts data into Outlook

To import the data into Outlook follow these steps

1 Open Microsoft Outlook and select the Contacts folder You may want to create a new

contacts folder for the data imported from Sentences To add a new folder right click the

Contacts folder and select New Folder from the shortcut menu

2 Highlight the target Contacts folder and select Import and Export on the File menu

This displays the Import and Export wizard

3 The steps in the Import and Export wizard are as follows

bull Select Import from another program or file and click Next

bull Select the option Comma separated values (Windows) and click Next

You may be need to install an additional software module if you have never imported this

kind of file into Outlook before

bull Use the Browse button to navigate to the directory where you saved your CSV file from

Excel Be sure to select the file with edited email addresses as saved from Excel not the


Worked examples

465

file as output from Sentences Choose one of the options for dealing with duplicate data

and click Next

bull Select the destination folder and click Next

bull In the next screen select the checkbox next to the option Import

ltfilenamecsvgt into ltfoldernamegt Click Map custom fieldshellip if the Map custom

fields dialog does not open automatically

bull In the Map custom fields dialog choose the way you want the columns in your CSV file

to map to the fields in the Outlook contacts folder Mappings can be created by dragging

and dropping values from the From list to the To list

An example of a finished mapping from the Human resources example to Outlook may

look like the list below

Field Mapped from

Name Person


Business Phone Telecoms number work telephone

Home Phone Telecoms number home telephone

Name Person


bull At this stage you should ignore duplicate fields in your file After completing the

mapping of your fields click OK and then click Finish

bull Outlook should now import your data to the target folder and create or populate

Contact records with the data from Sentences

Configuring the new folder as an address book folder

To configure the new contacts folder as an address book folder follow these steps

1 Highlight the new contacts folder right-click and select Properties from the shortcut

menu

2 Select the Outlook Address book page and select the check box Show this folder as

an email address book and click OK

3 Select the Services command on the Outlook Tools menu

4 On the Addressing page below the box marked When sending mail check names

usinghellip click Add

5 Select the new contacts folder and click Add then click Close Apply and OK

6 Now when you type the contacts name into the address field of an email Outlook can

find the corresponding email address

Creating Sentences data from an Outlook Contacts folder

Microsoft Outlook allows you to export Contacts data to a CSV file and you can use this

feature to take data from Outlook and import it into Sentences

You must make sure that the layout of the data in your CSV file matches the schema of an

existing Sentences database One way to do this is to examine a CSV file exported from a

Sentences database for example one created by the procedure described in ldquoCreating

Microsoft Outlook Contacts from Sentences datardquo 4


Worked examples

466

You can edit the CSV file derived from Outlook in Microsoft Excel or in a text editor to

make sure that it conforms to the structure you need You may need todivide the data

from Microsoft Outlook into two or more CSV files before importing the data into

Sentences

Creating a CSV file from Microsoft Outlook

1 In Outlook select Import and Export from the File menu

2 In the Import and Export wizard follow these steps

bull Select Export to a File and click Next

bull Select Comma separated values (Windows) and click Next

bull Select the folder you want to export from in this case a Contacts folder and click Next

bull Type in a path and file name for your CSV file or click Browse to select an existing

file and click Next

bull Select the check box next to Export Contacts from the Contacts folder

Click Map custom fieldshellip if the Map custom fields dialog does not open automatically

bull In the custom fields dialog select the fields you want to export and click OK If you

have recently imported a CSV file into Outlook the field names from that file are shown

in the custom fields dialog

bull Click Finish

Editing the Outlook CSV file for import into Sentences

You need to edit the CSV file that is created by Outlook before you can import the

Contact data into Sentences You can do this in Microsoft Excel or using a text editor

When you edit the file you should note the following points

bull The values created by Outlook for Name fields are based on the value stored in the ldquoFile

asrdquo field You may want to change this value when you edit the file

bull You may need to rename the column headings - the values in the first row of each

column - to match the type names required by Sentences

bull If you want to import email addresses into Sentences you need to add the string

mailto to the start of each email address To do this in Excel follow these steps

1 Open your CSV file in Microsoft Excel

2 In the first new column paste the string mailto into every cell

3 In the second new column give row 1 the value of row 1 in the column containing the

email addresses from Outlook for example ldquoHyperlink email addressrdquo

4 In all other cells paste an Excel function to concatenate these values together if the

Outlook email address is not blank eg

ldquo=IF(ISBLANK(E2)CONCATENATE(G2E2))rdquo

5 Add a new sheet to the Workbook

6 Cut and Paste the original column of email addresses into the first column of the new

sheet

7 Repeat for the column of mailto values into the second column of the new sheet

8 Save the file to a new CSV file

bull You should now be able to import these contacts into Sentences using the CSV Import

command


Worked examples

467

Copying Excel Data to and from Sentences

Contiguous selections of cells in Microsoft Excel can be pasted into a Sentences

Dataform table Any empty cells will be ignored but incompatible values will produce an

exception After pasting the data the Dataform can still be saved or canceled in the usual

way

The context menu on the first column of a Dataform table includes a Copy menu item that

copies the table contents onto the clipboard in the format that Excel is expecting


Crystal Reports can use an XMLSchema definition and XML data as a source input to

Reports See ldquoReporting using SAP Crystal Reportsrdquofor details



469

Appendix A


All the following menu command key combinations and shortcut keys are valid in the

Microsoft Windows operating system environment only This summary has not been

updated for Version 40


Menu namehellip contains these commands Keyboard

sequence

Shortcut

File New Profile 1 Alt+f n Ctrl+n

Open Profile 1 Alt+f o Ctrl+o

Edit Profile 1 2 Alt+f e

Delete Profile 1 2 Alt+f d

Refresh Profile Alt+f r

Reload data Alt+f a F5

Exit (Personal Edition

only)

Alt+f x

Edit Cut 3 Alt+e t Ctrl+x

Copy 3 Alt+e Ctrl+c

Paste 3 Alt+e p Ctrl+v

Delete 2 3 4 Alt+e d Delete

Rename 2 3 4 Alt+e m Ctrl+ r

Properties 5 Alt+e r Ctrl+p

View Default Dataform Alt+ v f Ctrl+ d

Show source and target Alt+ v s

Follow hyperlink Alt+ v h

Retrieve by source Alt+ v b

Retrieve sorted Alt+ vs



470

Menu

name


sequence

Shortcut

Retrieve unsorted Alt+ v u

New Explorer Tab Alt+ v n

New Explorer Tab on Target Alt+ v t

Delete Explorer Tab Alt+ v d

Expand All Alt+ v x

Collapse All Alt+ v c

Expand Node Alt+ v p

Collapse Node Alt+ v l

Stop Execution (Q) Alt+ v q

Messages Alt+ v m

Triggers Alt+ v i

Options Alt+ v o

Diagram Editor Alt+ v a

Schema Create Entity Type 2 Alt+ s e

Create Association Type 2 Alt+ s n

Insert Association Type Above 2 Alt+ s a

Display in Core types folder 279 Alt+ s o

Display in Core queries folder 27 Alt+ s o

Attach Set Query 6 Alt+ s u

Attach Query 2 Alt+ s y

Tables and Views 8 Alt+ s l

Export Schema to XML Alt+ s t

View Schema in XML Alt+ s v



471

Menu

name


sequence

Shortcut

Query Create Set Query 6 Alt+ q s

Create Query 2 Alt+ q c Ctrl + q

Edit Query 2 Alt+ q q

Execute Query Alt+ q x

Results Export to CSV file Alt+ q r v

Results Export XML results Alt+ q r e

Results Export XML DTD Alt+ q r o

Results Export XSL Stylesheet Alt+ q r x

Results View XML results Alt+ q r i

Help Help Topics Alt+ h t

Tutorial Alt + h u

About Alt+ h a

Notes

1 Not shown when the profile cannot be changed

2 Not shown when user cannot edit schema

3 Not shown when user can deleterename data but not schema

4 Not shown when user cannot edit schema or data (in addition to 2)

5 Properties are read-only when the schema is read only

6 Not shown when Set Queries are not selected in the Edit Profile dialog

7 The Display in Core types folder command is only available for types and the Display

in Core queries folder command is only available for queries

8 The Tables and views command is used only with the LazyView tool For more

information please refer to the LazyView Guide

9 The Display in Core types folder command is only available if the Core types arenot

being created automatically



472





F2 Allows in-place renaming

F5 Reload data in the Explorer or execute the selected query in

the explorer






Tab Moves to next control in sequence (sequence includes Filter

and Positioner fields)


Shift + Tab Moves to previous control in sequence (Sequence includes

toolbar)

Dataform function keys




Alt + F4 Allows in-place renaming

Alt+F6 Sentences help (in Sentences Personal Edition) Browser


Shift F10 Allows in-place renaming

Tab Reload data in the Explorer or execute the selected query in

the explorer

Alt+Tab Toggle between data pane and schema pane

Shift+Tab Select vertical divider for resizing

Ctrl+Tab Select first menu on menu bar

Ctrl+Shift+Tab Closes current window

Query Editor menus


473

Query Editor menus

Menu


Keyboard

sequence Shortcut

Query Save Query 1 Alt+ q s

Save as 1 Alt+ q a

Properties Alt+ q r

Close Alt+ q c

Edit Add Alt e + a

Add submenu

Associations Alt e + a s

Add submenu

Instance Specific Associations Alt e + a n

Add submenu

Derived type Alt e + a d

Add submenu

Selection Alt e + a i

Add submenu

Sort Alt e + a o

Add submenu

Page Alt e + a p

Hide Branch Alt e + h

Show Branch Alt e + s

Bind to instance Alt e + b

Bind to node Alt e + o

Make recursive closure 2 Alt e + k

Add transitive closure 3 Alt e + n

Set Required Alt e + i

Set Derivation Alt e + v

Edit Expression Alt e + x

Properties Alt e + r Ctrl + p

Cut Alt e + t Ctrl + x

Copy Alt e + c Ctrl + c

Paste Alt e + p Ctrl + v

Delete Alt e + d Del

Rename Alt e + m

View Expand All Alt v + x

Collapse All Alt v + c

Expand Node Alt v + p

Collapse Node Alt v + l

Create Parameter Alt p + r

Set Type Alt p + t

Set Default Value Alt p + f



474

Menu


Keyboard

sequence Shortcut

Set Mandatory 3 Alt p + n

Results Execute Query Alt r + x

Reload data Alt r + a F5

Stop Execution (Q) Alt r + q

Export to CSV file Alt r + v

Export XML results Alt r + e

Export XML DTD Alt r + o

Export XSL Stylesheet Alt r + p

View XML Results Alt r + i

Dataform Default Dataform Alt d + f Ctrl + d

Custom Dataform Alt d + u

Help Menu Help topics Alt+ h t

Tutorial Alt+ h u

About Alt+ h a

Notes

1 Not shown when the user cannot save changed queries

2 Displays Make recursive closure or Break recursive closure depending on the status of

the selected node

3 Displays Add transitive closure or Remove transitive closure depending on the status of

the selected node

4 Displays Set mandatory or Set optional depending on the status of the selected

parameter



F1 Sentences help

F2 Allow in place renaming

F5 Executes the current query





Alt + F6 Toggle to Java console display


Tab Moves to next control in sequence


Shift + Tab Moves to previous control in sequence



475



sequence

Shortcut

File Export Diagram1 Alt f + e

Import Diagram Alt f + i

Save as GIF Alt f + s Ctrl S

Page setup Alt f + u

Print Alt f + p

Close Alt f + c

Edit Add association types Alt e + a

Add query results Alt e + q

Copy Alt e + c

Paste Alt e + p

Remove Alt e + r

Remove all Alt e + m

Select all Alt e + s

Add core entity types Alt e + e

Add all entity types Alt e + y

Add annotation Alt e + n

Add Title Alt e + t

Add Chapter Legend Alt e + l

Refresh Chapter

Legend

Alt e + f

Increase font size Alt e + I

Decrease font size Alt e + d

Increase zoom Alt e + z

Decrease zoom Alt e + o

View Default dataform Alt v + f Ctrl-D

Follow Hyperlink Alt v + h

Expand all Alt v + x

Collapse all Alt v + c

Expand node Alt v + p

Collapse node Alt v + l



476


sequence

Shortcut

Stop Execution Alt v + q

Preferences Alt v + r Ctrl-P

Draw finished diagram 1 Alt v + g

Help Help Topics Alt h + t

Tutorial Alt h + u

About Alt h + a

Notes

1 Displays Draw finished Diagram or Draw outline diagram depending on the current

drawing mode



F1 Sentences help (in Sentences Personal Edition)

Browser help (Sentences Enterprise Edition)

F6 Toggle between canvas pane and schema pane



Alt+F4 Closes current window


Tab Moves to next control in sequence (sequence does

not includes toolbar) Includes individual diagram

elements


Shift + Tab Moves to previous control in sequence (Sequence

does not includes toolbar) Includes individual

diagram elements

Ctrl+Tab Moves to next control in sequence including out of

the diagram canvas

Shift+Ctrl+Tab Moves to previous control in sequence including

out of the diagram canvas



477

Appendix B


This chapter contains information covering topics intended for use by a System

Administrator who needs to monitor the usage and statistics of the Sentences Server

as follows

bull Viewing Sentences message statistics

bull Viewing Sentences user statistics

bull Viewing Sentences profile statistics

bull Viewing Sentences chapter statistics

bull Viewing scheduled process list status

bull Detailed Chapter statistics

bull Chapter file analysys


When you install Sentences with Tomcat a statistics servlet is installed alongside the

main Sentences servlet The statistics servlet has the class name

comsentencesservletStatsServlet

You can control the access to Sentences servlets including the statistics servlet by setting

parameters in the Serverproperties file (see ldquoServlet access toSentencesrdquo on page 1-

75) By default access to server statistics is set to true and access to chapter statistics is

set to false

The Sentences installation links this servlet to the URL path Statistics If access to

the statistics server is allowed you can access the statistics servlet by entering a URL in

your browser for example

httplocalhost8090SentencesStatistics

You must substitute the name of your installationrsquos Sentences host for localhost8090

in the example

If you are not using Tomcat you need to configure your web server and servlet container

to use the statistics servlet

The statistics servlet returns a standard HTML page which can be viewed in any browser

without needing an applet The page is not dynamic which means that it is not

automatically updated as the data changes Use your browserrsquos Refresh command to re-

load the page with more current data

The page contains four tables covering messages profiles users and chapters and a

memory usage summary



478

Message statistics

Figure B-1 Server message statistics

Figure B-1 shows the message statistics for the host named in the table heading The first

data line shows total counts since the server was started and the second line shows counts

for a recent one-minute period

The columns in the table are as follows

Column Description

Time Period The time period for which counts are shown

Messages In The number of messages received during the time period

Average Delay If messages have been delayed by the throughput limiting

mechanism this column shows the average time in milliseconds

by which messages have been delayed

Max Delay If messages have been delayed the maximum time that any

message has been delayed in milliseconds

Messages Out The number of message responses sent during the time

period

Average Time The average time in milliseconds taken by the server to


Max Time The maximum time in milliseconds taken by the server to


User statistics

Figure B-1a User statistics

Figure B-1a shows user statistics for the host named in the table heading There is one

data line for each user that has logged onto the system on this server The ldquologged inrdquo

column will only show ldquonordquo if the user explicitly logged out of the system Simply

closing their client browser will not log them out of the system

Open profile statistics

Figure B-2 Open profile statistics



479

Figure B-2 shows the open profile statistics for the host named in the table heading There

is one data line for each profile that is currently in use on this server The system profile

Profiles is always shown as currently in use ldquoCurrently in userdquo means that the profile has

been opened and that the server has not yet closed it The server closes a profile after it

has remained inactive (has received no requests) for a period of time determined by the

ProfileTimeout value in the Serverproperties file


Column Description

Profile Name The name of the profile Any profile that is not available to be

opened by users for example one that has been edited but

not saved is marked with an asterisk

Opened Time The time that the profile was opened

Requests

The number of requests that this profile has processed since

it was opened Each message from the client is a request

but requests are also generated internally so that in general

the total number of requests is higher than the total number

of messages received

Pending Results

Whenever a client result includes a continuation marker

shown in the Sentences Explorer as the Morehellip prompt the

server retains data about the request so that more data can

be supplied if requested These pending result sets are

discarded when the client indicates that they no longer

required or after a period of time determined by the

ldquoPendingTimeoutrdquo parameter in the Serverproperties file

This column shows the number of such result sets currently

held by each profile

Open Queries

Whenever a query is to be executed it must first be

validated The server keeps a list of validated queries

This column shows how many are held by each

profile

Visible Hidden

Trans

These columns show the number of references held in the

profiles visibility cache the number of database items

known to be visible the number known to be hidden and

the number of transactions known to have been validly

committed The visibility cache contributes to the memory

requirement of each open profile these numbers provide an

indication of the size of that contribution



480

Chapters statistics

Figure B-3 Chapters statistics

Figure B-3 shows the chapters statistics for the host named in the table heading There is

one data line for each available chapter on this server


Column Description

Chapter Name The name of the chapter as shown in the Edit Profile

dialog

Cache Size The amount of memory currently in use as a database file

cache for that chapter

Disk Requests The number of requests made by the profiles for database

objects from that chapter file since it was opened

Cache Hits The number of requests for database objects that were met

from the database file cache

Cache Hit Rate The number of cache hits expressed as a percentage of the

total number of disk requests

Detailed chapter statistics

More detailed statistics on chapter files are available Before you can view these detailed

statistics you must enable the Chapter Statistics servlet For details of how to enable the

Chapter Statistics servlet see ldquoServlet access to Sentencesrdquo

After you have enabled the Chapter Statistics servlet each of the chapter names shown in

the Chapters statistics table (Figure B-3) is an active hyperlink Clicking the link displays

a summary page for the chapter as shown in Figure B-4



481

Summary page

Figure B-4 Chapter summary page

The summary page heading is the chapter name as shown in the Edit Profile dialog The

Chapter UID is the internal identifier by which the chapter is known to Sentences The

Path is the pathname of the disk file for the chapter If the SpatialAccess property in

the Serverproperties file is set to false meaning that access to the Spatial view is

not allowed the summary page displays the message Spatial view unavailable

The following sections give more details of the Spatial view Block statistics and Triple

counts options

Spatial view

Access to the spatial view is controlled by a separate servlet listed in the

Serverproperties file (see ldquoServlet access to Sentencesrdquo ) By default access to the

spatial servlet is set to true

Click the link to the Spatial view to see a three-dimensional graphical representation of

the data stored in the file as shown in Figure B-5

Figure B-5 Spatial view of chapter file

The spatial view uses an applet to show a three-dimensional map (a cube shape) of the

distribution of triples within the chapters triple store The three axes of the cube represent

source IDs (red axis) verb IDs (green axis) and target IDs (blue axis) Each triple is



482

represented by a white dot at the point corresponding to its source verb and target The

cube is intersected by orange lines which represent the boundaries of triple pages The

applet allows you to rotate the cube by dragging the mouse pointer over it You can also

zoom in to display a section of the cube at higher magnification and zoom out to return to

the less detailed view

Note Displaying the spatial view or triple counts on a large chapter is a resource

consuming operation which may have a noticeable impact on a running server

Block statistics

The block statistics page shown in Figure B-6 displays a table of information about the

contents of the blocks used by the chapter file

Figure B-6 Block statistics

The left-hand column of the Block statistics table headed Type lists the various block

types that are used within the file The following table describes the information given for

each type

Column Description

Blocks The number of blocks of that type in the file

Entries The total number of entries Each block type has its own

specific type of entry for example each entry in a triple

store block is one association

Bytes free The total amount of free space within the blocks of that type

Bytes available The total amount of usable space within the blocks

Percent free The fraction of the usable space which is currently free

shown as a percentage

The block types used are shown in the following table

Type Description

File Header The header of the file This holds datatype information and

data about other chapters referenced from this one

Entity Types An index to the entity types which have instances held in this

chapter Each entry is an entity type

Atom Store

Entity instances both values and non-values are held in the

atom store which provides access by type and name Each

entry is an entity instance This includes entities with long

names (see Long Atoms below)



483

Type Description

Long Atoms

Entity instances which are too long for the name index

structure are held in a separate area of the file Each entry is

one entity instance with a long name

Atom ID Table The index to entity instances by Sentences ID Each entry is

one entity instance

Triple Index An index to the pages of the triple store Each entry holds

information about one triple page

Triple Store The pages holding associations Each entry is an

association

Triple ID Table The index to associations by Sentences ID Each entry is an

association

Triple B-Tree A secondary index to associations by target Each entry is an

association

Triple counts

The triple counts page counts the numbers of triples of various kinds in the triple

store and displays the result in a table as shown in Figure B-7

Figure B-7 File triple counts

The information in this table allows you to judge whether exporting and reimporting the

data is likely to improve performanceThe column headed This chapter refers to triples

whose source is in this chapter the column headed Other chapters refers to triple whose

source is in some other chapter

Each row shows the number of triples of specific types

bull Stop triples are created when a database item is deleted Stop triples whose source is in

this chapter are removed by exporting and re-importing the data

bull Rename triples are created when a type or an entity is renamed Like stop triples rename

triples whose source is in this chapter are removed by the export process

bull A transaction start triple is created for every transaction started in this chapter

bull If the transaction has user text associated with it a transaction text triple is created as

well

bull When the transaction is successfully committed a transaction commit triple is created

The export process removes transaction triples of all three types

Memory usage summary

At the end of each statistics page there is a summary line showing the server memory

usage in the following format

Server memory 419 GB of 502 GB



484

The first figure shows the amount of memory currently being used and the second figure

shows the total amount of memory allocated to the server process These figures are totals

for the Java Virtual Machine that the Sentences servlet is running in and so include other

memory than that used by the Sentences server

You can change the amount of memory that the Java Virtual Machine allocates to a

process by adjusting the -Xmx or the -Xms parameter on your servlet container If you

select the Custom installation option for Sentences you can set the Java memory

parameters during the installation procedure (see the Sentences Installation Guide for

more details)

You can set the Java memory parameters for server utilities such as Export and Import in

the lazystart script file (see ldquoThe lazystart script filerdquo )

If you are using Tomcat you can add the server memory specification to the

Catalinabat file (or Catalinash file for Linux Unix) which is in the Tomcat4bin

folder of your Sentences installation If you are not using Tomcat the memory parameter

should be specifiable in your servlet container See the documentation for your servlet

container for details

If you are using Tomcat you can add the line below in the section headed Verify and Set

Required Environment Variables

set JAVA_OPTS=-Xmx4096m -Xms2048m

where -Xmx specifies the maximum of memory that can eventually be used (shown here

with the example value 4096m meaning 4GB) and -Xms specifies the initial amount of

memory to be allocated at the start (shown here with the example value 2048m meaning

2GB)

Scheduled process status

Sentences will display the outcome of the currently running Scheduled Process List once

complete but until it is complete only the fact that it has started will be shown The

Statistics servlet has an option to view more granular information about which items in

the list have completed so far

To view the progress of the currently running Scheduled Process List follow these steps

1 In your browser enter the URL for your Sentences Server Statistics page with

the process query parameter

httplthostgt[ltportgt]SentencesStatisticsprocess

For example in the default installation using the Tomcat test web server

theURL will be

httplocalhost8090SentencesStatisticsprocess

2 The web page returned will either state that there is no currently running process

or will display the name of the Scheduled Process List the status (which is the

currently running item) and a list of all the items

Each item listed will state whether it has been completed or not


You can use the InspectChapter command-line tool to analyse the structure of a

chapter file and create a more detailed listing of its contents To use this tool open a

command prompt and navigate to your ltSentences_homegt directory and enter the

following command

InspectChapter ltchapter filegt ltoptiongt



485

where

ltchapter filegt is the file name of a Sentences chapter file to be analysed

ltoptiongt is a keyword specifying the information to be listed

The available keywords are described below

Keyword Description

header

Lists information from the file header including its block

size its internal identifier and the names and internal

identifiers of chapters that are referenced from within this

chapter

blockstats

Lists block statistics This is the same information as

displayed on the block statistics HTML page described

above

atoms Lists all the entity instances in the chapter by name within

entity type

atomIDs Lists all the entity instances in the chapter by ID

tripleIDs Lists all the associations in the chapter by ID

triplepages

Lists information about all the triple pages showing the

range of associations held in each one but without

listing the associations themselves

triples Lists all the triple pages in the chapter including all the

associations held in each one

rtree Lists the R-tree index used to access triple pages

The InspectChapter command does not use the ChapterPathList setting from the

Serverproperties file and does not check for the existence of the databaselock

file You must therefore use the fully-qualified path and file name for example


It is strongly recommended that you shut down the Sentences server before running this

command

Server request statistics

Sentences can record the number of requests received by the Sentences server in a text

file This file is created if you set the optional parameters StatisticsPath and

StatisticsPoll in the Serverproperties file (see ldquoStatistics propertiesrdquo )

The file created by this setting is named Statisticsxxxtxt (where xxx represents a

timestamp and the file lists the date and time of each record followed by the number of

server requests received in the previous time period

Glossary

Glossary

This glossary gives definitions of terms as they are used in Sentences


All types folder A folder in the Sentences Explorer schema pane where all entity types are displayed

All queries folder A folder in the Sentences Explorer schema pane where all queries are displayed

applet A program written in Java for displaying data in a web browser The Sentences client for the Enterprise Edition is a Java applet that runs in a Web browser

association An association stores data about the interaction between two other things which may be entities or associations An association is an instance of an association type

association type An association type is part of the database schema and is used to define some of the attributes of the associations that are based on it

associative

model

A new model for the structure of computer databases of which Sentences is an implementation

bind In a query to force a request node to return only an instance specified in some way either a fixed instance a parameter value or the result of some other node

bound Of a request node in a query forced to return a specified instance See bind

branch In a query request tree a group of request nodes originating with one common parent node

Business Rule There are two kinds of Business rule used to prevent defined state changes or act on a state change

Change Rule A Change Rule is a Business Rule that mandates an action when it detects a change of state

chapter A logical repository within a Sentences database for schema data or query information stored on disk as a chapter file A chapter may be included in zero one or many Sentences profiles

child Dataform A second or subsequent Dataform opened from an association on another Dataform

child node In a schema or query tree a node other than the root node A child node always has only one parent node

client A device that displays data and allows user interaction but does not store data

Core types

folder

A folder in the Sentences Explorer schema pane used to display selected entity types from your schema In any profile you can choose between manual or automatic selection of entity types for this folder If you choose automatic selection then entity types are shown in the Core types folder when they are the source of an association which is itself the source of further associations

Glossary


Core queries

folder

A folder in the Sentences Explorer schema pane used to display selected queries from your schema Queries in the Core queries folder are always selected manually by the user

custom datatype A datatype defined by a user using the Sentences API and the Java programming language

Data page See Page

data pane The right-hand pane of the Sentences explorer used primarily for viewing and selecting instances and associations

data request In a query the request node at the root of the request tree

database All the data and schema information in one or more Sentences chapters that are used in a profile or a in a set of related profiles

Dataform One of the major parts of the Sentences user interface used for dynamic data viewing and data entry

datatype A way of defining certain attributes of an entity type Applying a Sentences-supplied datatype or a custom datatype to an entity type may make it a value type

Diagram Editor An editor for the basic graphical representation of database elements may also be used for exploring or documenting a schema

Diagram element A graphical representation in the Diagram Editor of an element in the Sentences database also applies to text labels and annotations

Display Name

Query

This is a type of Sentences Query that has been created to provide an alternative name for an instance

derivation A calculated value on a forward request query node that may populate or replace the target of its association

derived type In a query an operator request which specifies that new values should be created based on a calculation or other derivation from other results

drill-down The process of viewing database information by moving through the data pane or schema pane in the Sentences Explorer

DTD A Document Type Definition for an XML document

Effector Query A Sentences Update Query that is either attached to a particular State Domain State or mandated in a Change Rule in order to effect a change when that state change is detected

Enterprise

Edition

The Sentences configuration that uses a Web server and servlet container with the Sentences client running on the same machine or on a remote machine for example as a Java applet in a Web browser

entity An entity stores data about something that has an independent existence in the real world An entity is an instance of an entity type

entity type An entity type is part of the database schema and is used to define some of the attributes of the entities that are based on it

Glossary


equivalent Two types in Sentences that represent the same real world thing may be defined as equivalent types Two instances in Sentences that represent the same real world thing may be defined as equivalent instances

filter tool A tool for selecting data according to criteria entered by the user

forward request In a query a request for associations in the forward direction

GUID A Globally Unique Identifier is an identifier that can be generated automatically as an ID for an Entity

hidden node In a query a request node whose results are not included in the returned result tree A hidden node is usually included to provide data for an expression

HTML The HyperText Markup Language an international standard file format based on SGML used for hypertext documents on the World Wide Web

HTTP The Hypertext Transfer Protocol an Internet protocol based on TCPIP used to fetch hypertext documents from remote hosts on the World Wide Web

Inactive

instances

An inactive instance is one that is no longer valid to be used in new data entry but is still required for historical references An Association Type can be used to identify itrsquos sources as being invalid when an instance exists

instances A collective term for entities and associations

Internet A global network of computer networks The World Wide Web is part of the Internet

Intranet A private closed network that uses the same communications protocols as the Internet

inverse

association

An instance of an association type as referred to from its target to its source

Inverse request In a query a request for associations in the reverse direction

inverse verb The verb associated with the inverse component of an association type

items A generic term for instances and types

J2EE The Java 2 Enterprise Edition the Java standard for multi-tier enterprise applications

J2SE JRE The Java 2 Standard Edition Runtime Environment including the Java Virtual Machine Java core classes and associated resources

Java A programming language developed by Sun Microsystems Inc now owned by Oracle Sentences is written in Java

Java SDK The Java 2 Standard Edition Software Development Kit a development environment for the Java programming language

Java Web Start A Desktop application that allows Java Applets to be run outside a browser as a Desktop Application

JAR file A file in the Java Archive file format typically containing a bundle of Java class files and additional resources associated with a Java applet

Glossary


JDBC Java Database Connectivity technology provides a means of connecting from Sentences to many Relational Databases Each Database Vendor requires a JDBC Driver in the form of a JAR file

LazyView LazyView is a technology whereby one or more Relational Databases may be dynamically viewed in Sentences or a static snapshot of data may me imported A LazyView chapter defines the relational database to connect to and the mapping between the Relational Schema and the Sentences Schema

local mode A method of running the Sentences Enterprise Edition in which the Sentences server and the Web browser client are installed on the same computer

Mapping

Definition

A LazyView Mapping Definition defines how Sentences transforms the Relational Schema into the Sentences Schema using the Associative Model of Data

node A named point in a schema or query tree for example a type or instance

operator request In a query a request node that modifies the results returned by its parent

Page Schema Pages are used to organise Association Types into logical groups They are used in base dataforms to generate Dataform Tabbed Pages They are also used to generate Data Pages in the same positions in the data pane Page Nodes can be manually added in a Custom Dataform and when adding Association Types to a Custom Dataform Query the Association Type Schema Pages can be used to generate default Page Nodes

parent Dataform A Dataform opened from the Explorer from which one or more child Dataforms may be opened

parent node In a schema or query tree any node that is the parent of one or more child nodes

Personal Edition A special Sentences configuration intended for evaluation purposes only that has a Sentences client and server bundled into a single Java application

positioner tool A tool for positioning the data pane display according to criteria entered by the user

profile A selection of one or more of the chapter files which

form a Sentences database A profile also defines a collection of chapter files and how they operate together to produce a view of their combined schema query and data information

privilege A User is granted privileges to perform certain tasls by

being assigned User Roles

query A way to specify data to be extracted from the database A query can be used to return selected data from the database or to create XML output or to define a custom Dataform

Query Editor One of the major elements of the Sentences user interface used for creating queries

Glossary


query parameter In a query a value which can be supplied to modify the execution of the query in some way

recursive

closure

A query operation that follows a transitive relationship as far as it goes

request node In a query one element of a request tree

request tree In a query a structure of request nodes that a user builds to define a query

result tree In a query a data structure holding the results of a query

root The point of origin of a schema or query tree The root is always displayed at the top of the tree

Sandbox Mode A Sandbox is a term used to describe a mode of operation where any changes are only temporary and the system can revert to the state it was in prior to entering Sandbox Mode There are two types of Sandbox in Sentences Full and Data In Data Sandbox mode any schema changes will be permanent but data changes are transient In Full mode any changes to schema or data are transient

Scheduled

Process List

A list of processes that are scheduled to execute at a particular time or reglar intervals on the server

Scheduler The Sentences Server includes a Scheduler that can execute processes at regular intervals

schema The sum of the type and properties information for all data in the database

Schema page See Page

schema pane The left-hand pane of the Sentences Explorer Used for building and viewing the database schema

selection

request

In a query a request node that filters the results returned by its parent

Sentences An implementation of the Associative Model of Data written in Java by Lazysoft

Sentences Explorer

One of the major elements of the Sentences user interface Used for browsing and viewing schema and data information

sequenced Arranged in an explicitly assigned order The order can be changed only be an explicit re-sequencing action

server A device that runs programs and stores data and supplies data for display on a client in response to a request

servlet A Web server component written in Java that provides dynamic content

servlet container A Web server component written in Java that provides network services for servlets (previously known as a servlet engine)

servlet context A collection of resources associated with a servlet that can be shared which is often used as part of a URL

set query A query based on the Set Query Editor used in Sentences Version 1

Glossary


Set queries

folder

A folder in the Sentences Explorer schema pane where all Set queries are displayed This folder is only available if you have chosen to show Set queries in your profile

sort request In a query a request node that re-orders the results returned by its parent

sorted Arranged in a value determined order for example alphabetical

source An item which is the origin of an association or association type

source request In a query a request node representing the source of an inverse request

State Domain You may define State Domains for Sentences Types Each of these Domains has a set of States that instances of the Type can exist in together with an assumed ldquoundefinedrdquo State

State Rule A State rule is a Business Rule that prevents a given change of state

subset A subset is defined by a query against a superset The subset is named and appears as a new type Its members are all those instances of the superset type which match the criteria of the subset query Subsets and their supersets must both be either entity types or association types

subtype When defined as a subtype a type automatically assumes all of the association types defined with its supertype as their source or target Subtypes and their supertypes must both be either entity types or association types

supersede The supersedes command is used to replace one instance by another

superset A type from which one or more subsets is derived

supertype A type from which one or more subtypes is derived

System State

Domain

This is a State Domain that describes states internal to Sentences (such as Existence) as compared with User-defined State Domains

target An item which is the forward end-point of an association or association type

target request In a query a request node representing the target of a forward request

Transaction

Visibility

Transaction visibility is the mechanism for displaying the Sentences database at a point in time in the past

transitive

closure

A query operation that follows a transitive relationship to a specified depth but displays the results as a single level

Translation List A Translation List (in the context of LazyView) is a list of words phrases and letter combinations that should be replaced in the Relational Schema names to make more meaningful Schema names in Sentences

tree A graphical representation of a data structure in Sentences schemas and query requests and results are displayed as trees The root is always displayed at the top of the tree

Glossary


trigger Custom code that enforces rules and takes actions when the database is updated

types A collective term for entity types and association types

Update Query A Sentences Query that executes in the context of a transaction to make changes to data and perform other actions such as notifying the user and sending simple emails

URL Abbreviation for Uniform Resource Locator an address for data on the Internet or an intranet

User A Sentences database user who is assigned Roles and privileges such as the ability to Manage Sheduled Processes

User Role Sentences User Roles are defined in the User Security system to be assigned to Users in order to grant them privileges to certain functionality

value An instance of value type such as a number or a date

value type A representation of a real-world thing about which you do not need to record additional information such as numbers or dates

verb A name used to define the nature or significance of a particular association type

W3C Abbreviation for the World Wide Web Consortium an international body that develops and maintains standards for Web technology

WAR file A Web Archive file used by a Web Application Server

Web Abbreviation for the World Wide Web (WWW) a graphical part of the Internet

Web Application

Server

A Java technology-based application deployment environment for the World Wide Web

Web mode A method of running the Sentences Enterprise Edition in which the Sentences server runs on one computer and the Web browser client is installed on one or more different computers

Web Start A Java Technology that is part of the Runtime environment for launching Java Applets as Desktop Applications

XML The Extensible Markup Language a standard for structured data and documents on the Web developed by the W3C

XSL In a query a request node representing the target of a forward request

Index

A

Action attributes 386

Add a chapter 143

additional expression capabilities 325

All queries folder 121

All types folder 121

Allowing in XML 391

allowing the action attribute 391

API 402

and triggers 405


building and running programs 402

class hieracrchy diagram 403

class hierarchy 403

custom datacodes 409

example code 402

example program 455

introduction to 401

online documentation 402

packages 403

triggers 404

use of 389

applet

classpath 38

CLASSPATH 39

classpath argument 38

client

Sentences client 52

Dataform applet 244

Picker applet 248

Query applet 251

Senteces applet window 159


Sentences applet parameters 42

using applets 110

using colour in applets 253

application suite 26 28

arithmetic operations

with date and time datatypes 313


example 307

assigning datatypes 190


cardinality 171

creating verbs 108

defining source verb and target in 170

instant specific 109 219

inverse verb 170

metatype targets 238

properties 185

properties page 213

renaming 176


sequencing 184

singular inverse property 171


subsets 204

targets 238

associations

creating 174 237

databases

comparison with relational databases

75

display order 172

introduction to 71


associative model

comparison with relational model 74

further reading 71


B

background colour

BackgroundColour parameter 247 250

XSL background colour option 360

backup


backing up data 49

copying chapers for backup 51

exporting a profile for backup 51

online backup 49

base dataform 235

batch files

parameter limit 156

binding nodes 296

to an instance 296

to other nodes 297

to parameters 297

block size 146

block statistics 482

changing 158 484 485

Border parameter 247 250 253

browsing transactions 163

business rules 220

change rules 228

domains and states 221

effector query parameters 226


reference 230

state rules 227

system state domains 221

using states

in dataforms 225

in queries 225

C

can create target 212 361


canvas 394

cardinality 171

and data display 171

cascarding stylesheet 369

certificate 53


changing block size 158

changing user 149

chapter files

analysis 484

deleting 146



format 158

locations 136

naming 145

properties 146

statistics 480

system chapters 136

Chapters 135

add a chapter 144




commands 137

copying 158

deployment 158


export and import single chapter 159

importing

and profile visibility 156

importing 154


new chapter 145

renaming 145

restrictions on copying chapter files 158

use in database design 109

working with chapters 144

checkbox presentation option 195

child dataform

opening from a table row 239

choosing entity association or value types

107

client API 402

example 455

use of 111


client server interaction diagram 264

closure

recursive 321

transitive 319

code example

picker applet 249

collapse view 295

colours

applet colour features 253

using in Sentences applets 253

combo presentation option 195

commands

ExportChapter 159

ImportChapter 159


example 308

concatenation operator 306


configuration 22

optional parameters 43


the lazystart script file 37

configuring with non-J2EE Web servers 25

contacting Technical Support 56

context menu

see shortcut menu 127

copying and pasting actions 115

core queries 121

core queries folder 121

core types 120


core types folder 120

behaviour 143

setting display in 187

create Dataform 235

CreateButton parameter 251

creating


custom Dataforms 241

custom help 413

entity types 164

new profile 138

parameters 323

CSS 369

CSV 255

exporting query results as 374

file structure 256

CSV Export 258

and multiple associations 375

CSV Import 255

and cardinality rules 256

example 417

on Solaris Linux or AIX 257

on Windows 257

rules 256

running command 257

with supertypes and subsets 256

CSV Import Example

adding image data 420

data targeted on associations 419

CSV Import Example

importing example files 419

preparing a profile 418

CSV Import Example

viewing imported data 419

CSV Import Example

viewing additional data 421

CSV Import Example

repeating the demonstration 422

Currency 192


Currency datatype 192

custom Dataform 110

properties dialog page 208 209 210 211

212

refresh button 243

restrictions 243

selecting 243


telecoms number 453


API 410

import and export 411

installing 410

loading custom datatype 450

unloading custom datatype 451

custom Help

adding custom help 411

creating 412

file name and location 413

help button display 411

help mapping 412

mapping to help topics 413

precedence of help pages 412

updating help topic mappings 412

custom Help mapping

association type mapping 413

custom dataform mapping 413

entity type mapping 413

D

data

demand loading of 178

data changes 135

data changes chapter 143

data exchange 255

data items

size of 165

data models

associative 72

comparing associative and relational 74

data pane 121

features 117

icons 117

data request node 291

data request nodes

creating 291

data visibility 152

database

benefits of exporting 152

class hierarchy in 403

database lock file 55

Dataform 128 232

default export behaviour 153

design 71

assumptions for Order Entry example

433

creating verbs for association types

108

design guidelines 75

design skills 75

export

and internal identifiers 152

export and import 152

export file 153

exporting 153

importing 154

modelling 108

queries 290

views

creating using profiles and chapters

275

example 275

Dataform

appearance 265

appearance with supertypes 266

base Dataform 235

changing targets in 240

create Dataform 235


example with subsets 269

instance specific 240




shortcut menu 130 238

tabbed pages 129 232 233 234

targets that are subsets 240

targets with duplicate names 240

update dataform 236

use of 110

Dataform applet 244

colours 253

parameters 245


Dataform is read only 212 361

Dataform navigation


Dataform parameter 247 250

Dataform quick tour 128

Dataforms

different kinds of 128


datatype classes 450

datatype method example 313

datatypes 189

ltnonegt 190

assigning 190

changing 167

currency 192

date 193

date and time 192


default directory 27

deleting types 167

hyperlink 190 191

image 166

image 190

methods 313

mixed currency 192

number 191

numeric types 191

output style 197

percentage 192

presentation methods 193

properties 189

string types 190

text 190

time 193

timestamp 193

undefined 190

value types 167

date and time datatypes 192


date datatypes 193

date formats

presentation 199


default target 215

using expression 216

using instance 216

default value 311

DeleteButton parameter 251

deleting 174 175


profiles 144

deletion


deployment

copying chapter files 158

deployment

exporting and importing profiles 151

derivation properties dialog 303

derivations 301

and XML import 386

calculation settings 303

example 422


recalculation rules 302

setting 304

derivations example 422

base and custom Dataform 424

design assumptions 433

importing order entry profile 423

order entry query 428

page nodes 429

setting dataform navigation 430

derived type node

expressions 304



derived types and derivations 299

description 207

design

associative database 71

database design 71 75

design for change 108

skills 75

diagram editor

adding query results 398

canvas 394

components 393

consistency with explorer 397

menus 475

preferences 394

starting 393

toolbar 394

diagram elements

adding 396

deleting 397

selecting 397

diagrams 393

export 398

import 398

printing 398

saving as a GIF file 398

display

refreshing 160

display height 198


display name queries 351

creating 351

in Sentences 352

display options 123

display order of instances 159

display width 198

DisplayStatus parameter 247 250 253

divider bar 123

in query editor 134

document conventions 19

documentation directory 27

drill down 118

DTD 377

create a DTD from a query 370

parameter 384

servlet access 381

DTD reference 369

duplicate instances are not allowed 172 187

E

edit profile dialog 142

editions 21

EditOption parameter 246


creating 227

element identifiers 368

element IDs parameter 385

elements

in XML 378

ellipsis button 130

EnablePickers parameter 247

enterprise edition 21

entities 164

creating 165

introduction to 71

size of 165

entities and associations 71

entities and values 73

entity types 164

creating 164

naming rules 165

properties 185

renaming 176

equivalence 206 218

defining 201 206

error messages 54

client must be loaded from same host as

its HTML page 57

database not available 55 56

Error 1222 54

Error 1265 54

Error 1266 55

Error 1267 55

Error 1268 56

Error 1272 56

Error 1403 57

errors reported at the Sentences client 54

server connection expired 54

example custom datatype

use of 451

example trigger classes 434

disabling 449

examples

chapter directory 27

client API example 455

CSV Import example 417


directory 27


458

trigger examples 434

worked examples 416

exists() conditional function 311

example 311

expand and collapse node buttons 118

expand view 295

explorer 114

data pane 121

deleting 174

display options 123

divider bar 123

drill down 118

menu bar 114

shortcut keys 123

shortcut menu 127

status bar 122

tabs 118

toolbar 115

tooltips 116

export

and triggers 409

databases 152

diagrams 398

options 153


troubleshooting 157

export and import


ExportChapter command 159

expression editor 336

expression syntax

for queries 305

expressions




creating 338

datatype methods 313

deleting 340

editor 336

exists() function 311

group functions 312

in queries 304


nested 341

results 315

syntax 305


wildcards 308

Extensible Stylesheet Language (XSL) 378

external formats 255

F

feedback 20

file URL prefix 191

filter tool 181

pattern matching 181

finding data 116 120 178

ForegroundColour parameter 248 250

format

display height 198

display width 198

format options 198

picker 196

presentation 194


style 196


XML query output options 368 379

function editor 336

function keys

Dataform 472

Diagram Editor 476

Explorer 472

Query Editor 474

functions

deleting 341

editing 336 339

nested 341

unwrapping 340

wrapping 340

G


group functions 312

example 313

grouping results 349

H

hidden in Dataform tables 198

hidden on Dataform 198

hide

hide nodes in queries 318

how to use this guide 19

http URL prefix 191

Human Resources example application 416

employee entity type 416

group company entity type 417

project entity type 417

hyperlink datatype 190 191

I

icons 116

in query editor 132

identifiers

in query expressions 315

image datatype 190

ImageURLBase parameter 36 247 250



import

and triggers 409

database 152

diagrams 398

from earlier versions 156

options 155


XML data 381

ImportChapter command 159

installation 17

installation directories 25

instance equivalence 218

instance options 172 187

instance specific association types 109 219

instances

creating in the Dataform 239

deleting 174

display order of 159

introduction to 73

names created by trigger 188

operations on 217

visibility 168

instances are values 189

instances may not be created 172 187

instances may not be deleted 172 187

instances may not be renamed 187


creating mail merge emails 460

creating mail merge letters 458

creating Outlook contacts 462

creating Sentences data from an Outlook

contacts folder 465 467

internal identifiers

Chapter UID 146

displaying 123

renaming 176





delayed display 159

inverse verb 170

iterative design 108

J

J2SE JRE 53

Java 53

J2SE JRE 53

Java console tool 54

on Solaris and Linux systems 53 54

on Windows systems 54

Java runtime environment 53

Sentences and Java 263

Java plug in security warning 54

Java server pages 110

JSPs 110

K

key features 17

keys

not used in Sentences 74

L


layout

XSL layout options 357

LazyId parameter 247

LazyID parameter 251



LazyQuery parameter 253

LazyType parameter 246 250

licenses directory 28

licensing 22

list presentation option 195

localisation 414

application text 415

example messages file 415

messages file location 415

messages file name 415

messages property file 414

system text 414

locating data 178


log files 52


behaviour with missing values 309

example 309

M

mailto URL prefix 191


memory usage summary 483

menu bar

explorer 114

query editor 132

menus

diagram editor 475

explorer menus summary 469

query menus summary 473

shortcut menus 127

message log 134


messages 134

messagesproperties 414

metaschemechap 26

metatypes 174 238

mixedcurrency datatype 192

modelling 107

common behaviours 109

one to many association types 108

morehellip prompt 178

multi-line edit presentation option 195

multi-line label on Dataform 199

multiple instances

sequencing 185

multiple line presentation option 195

multiple profiles 275 277 283

multi-user environments

XML import 385

N

naming

parameters 323

new chapter 145

new features 18

new profile

creating 138

new profile wizard 138

node names for XML output 370

nodes 116

and icons 116

binding 296

none datatype 190

none datatype 167

number datatype 191

O

online backup 49

preparation 49

restoring data 50

online backup using the command 50

open profile dialog 138

operations on instances 217


options dialog 123

order entry example

picker applet 432

outlook URL prefix 191

Output Format parameter 384

overview 17

P

page nodes 354

added automatically 354

adding 354

Dataform display nodes 354

in derivation example 429

using 354

parameters

BackgroundColour 247 250

Border 247 250 253


CreateButton 251

creating 323

Dataform 247 250

defining 324

defining type 324

defining value 324

DeleteButton 251

DisplayStatus 247 250 253

EditOption 246 250

EnablePickers 247 250

ForegroundColour 248 250

ImageURLBase 247 250

LazyID 247 251

LazyInstance 246 251

LazyQuery 253

LazyType 246 250

mandatory 324

maximum number in Windows batch files

156

naming 323

Picker 251

Picker Applet Parameters 250

Profile 246 250 253 325

Query applet parameters 253

query parameters 323

RequestSize 247

SaveButtonText 247 251

ServletContext 245 250 253

ServletPort 43 245 250 253

ShowTitle 251

Target 253


viewing in Explorer 325

parent and child dataforms 237

parent dataforms 265

password


for chapter files 57

percentage datatype 192

personal edition 21

Picker applet 248

code example 249

parameters 250

using colours 253

Picker applet example

use of 432

picker lists 130 240

displaying in the Dataform 237

picker type selection 196

Picker parameter 251


using togethert 182

positioner tool 180

preferences

diagram editor 394

presentation 194

presentation methods for datatypes 195

presentation options

checkbox 195

combo 195


list 195

multiple line 195

radio button 195

single line 195



tree 195

printing

diagrams 398

printing page breaks

XSL printing page breaks option 360

Profile parameter 250 253

profiles 135

commands 137

creating 138

deleting 144


editing 142

editing profile dialog 142

export command switches 153

export command troubleshooting 157

import command switches 155

opening 138

renaming 143

saving 144

the profiles profile 136

using multiple profiles 137

visibility of imported profiles 155

profiles and chapters

constraints 137

profiles database 136

export using XML 156

import using XML 156

transferring 156

profileschap 26

properties 185



Custom Dataform 208 209 210 211 212

datatype properties 189

default target 215

description 207

equivalence 206

general 186

query properties

Dataform properties 360

derivation properties 303


general properties 290

query node properties 355

XML properties 367

XSL stylesheet properties 357


subets 202

subsets 200 201 202


transitive closure node properties 362


association type page 213

datatype properties page 189

description properties page 207

equivalence properties page 206

format properties page 194

general properties page 186

subset properties page 200 201 202

supertypes properties page 205

target parameters properties page 214

triggers properties page 206

prototyping 108

Q

queries 287

creating 288

creating a new query 288

derived type nodes 299

description 290

display name 351

displaying 294

editing 289

executing queries with parameters 324

execution process 325

expression syntax 305

hidden nodes 318

navigation 212 361

no results 295


output format 368

parameters 323

recursive closure 319

renaming nodes 317

request tree 290

required nodes 316

result trees 294

saving 289

selection nodes 298

sort nodes 299


update 343

XML properties 367

Query applet 42 251

code example 252

colours 253

parameters 253

query changes chapter 143

Query Editor

and Dataforms 353

and XML 362 367

availability 288

divider bar 134

drag and drop cut copy paste 293

icons 132

introduction 287

menu bar 132

menus 473

query pane 133

quick tour 131

results pane 133

schema pane 133

starting 288

status bar 133

stop button 295

toolbar 132

use with XML 381

user interface 289

window 289

XML options 392

query expression examples




conditional operators 310

datatype methods

currency and mixed currency 314

date and time 313

text string methods 314

exists conditional function 311

group functions 312




void 310

wildcards 308

query expressions



default value 311

identifiers 315

missing values 316

syntax 305

using conditionals to check for parameter

values 312

using parameters 311

using void 310

zero token given as result 316

query node dataform properties


dataform is read only 212 361

interaction between properties 212 361

query node properties dialog

format page 356

query nodes

adding 292

query pane 133

query results

adding to diagram editor 398

displaying 294

displaying in Explorer 295

export as CSV data 374

export as XML 371

view as XML 372

query shortcut menu

add options 292

R

radio button presentation option 195


recalculation

rules for derivations 302

recursive closure 319 321

referential integrity 175

refresh button

on custom dataforms 243

refreshing the display 160

relational and associative model comparison

74

relational databases

access with LazyView 76

relational model

in comparison with associative model 74

rename

rename a chapter 145

renaming

nodes 317

renaming 176

renaming a profile 143

request tree

in queries 290

RequestSize parameter 247

required nodes 316

resources directory 28

restarting the Sentences server 47

restore


restore default settings 199

restoring data 49

result trees 294

results

grouping 349

results pane 133

retrieval options 213 216

right align in dataform fields 199

right align in dataform tables 199

running CSV import 257

S

Salary Update example

use of 455

sandbox modes 161

access 161

changing 161

SAP Crystal Reports 350



saving

saving a profile 144

schema

export to XML 379

schema changes 135

schema changes chapter 143

schema diagram

a simple association 71

an associative schema 74

more complex association 72

target parameters schema 270

schema pane

description 119

features 117

icons 117

in the query editor 133

schema pane 133

schema visibility 152

scroll bars 122

searching for data 178

security 57 148


checking HTML page host 57

user security 148

using database views 57

selection nodes 298

and expressions 304

Sentences

and Java 263

and XML 377

configuration 22


database design 107

diagrams 393

licensing 22

log files 52

queries 288

security 57

transactions 264

uninstall 69

user interface design options 109

user interface options 109

XML conventions 389

Sentences API 401


parameters 42

Sentences client 21 52

starting 52

Sentences editions 21

Sentences Explorer 159

drill-down 118

quick tour 114

tabs 118

tooltips 116

updates 264

use of 110

Sentences IDs parameter 385

Sentences server 21

shutting down and restarting 47


sentences_chapters 26

sentences_home 27

sentences_images 26 27

sequencing 184


multiple instances 185

server

statistics 477

server activity

monitoring 47

Server API 402

server request statistics

statistics

server requests 484 485

server side triggers 258 260 261 404

servlet access to Sentences 67

ServletContext parameter 245 250 253

ServletPort parameter 43 245 250 253

servlets

access to Sentences features using 67

available in Sentences 67

enabling and disabling 69

for access to XML 382

use to a DTD 381

use with XML 381

set queries 287

visiblity 152

shortcut keys 123

shortcut menus 127

Dataform 130

show grid

XSL show grid option 360

show separator

XSL show separator option 360

ShowTitle parameter 251

single line presentation option 195

singular inverse 171

size of entity and value instances 165

sort nodes 299

sorting 184

source 170

spatial view 481

statistics

chapter statistics 480

memory usage 483


open profile statistics 478

open profiles 478

summary page 481

viewing 477

status bar 122

Query Editor 133

stop button 183

in Query Editor 295


in Query Editor 295

string datatype 190

strings 314

style 196



stylesheets directory 28

subset queries

attaching to subsets 325

subsets 109 200 201 202

and Dataform 265

create 203

ordering 265

properties 202

properties dialog page 200 201 202

properties page 202

subset queries 325

used as targets 239

viewing subset instances 204

subsets and supertypes

comparison 203

dataform behaviour 204

ordering 265

using to design Dataform 265

supersedes 218

supertype

defining 205

supertypes 109

and Dataform 266


properties page 205

using with association types 206

support information 125

symmetric 172

system chapters 26 136

T

tabbed pages

on dataform 129




target 170

Target parameter 253


allowed products example 274

conference room example 271

limitations 275 277 278 283 284

properties page 214

targets

and subsets 240

with duplicate names 240

technical support

contacting 56

text datatype 190

time formats

presentation 199

tomcat

diagram editor 393

explorer 115

home directory 28

sentences directory 29

web applications directory 28

toolbar

query editor 132

tooltips 116

trace files 51

trace level settings 51

transaction processing 264

transaction visibility 162

transactions

browing 162

browsing 163

transactions

Explorer based updates 264

transactions

in Sentences 264

transactions




tree displays 116

tree displays in Sentences 113

tree presentation option 195

trigger examples

auto-number example 442

email address example 439

refuse update 436

triggers 206 404

actions 408

and the Sentences API 405


attaching 405

calling 408

creating instance names 188

customised validation 408

examples 405

installing 405

invocation 408

loading example triggers 434


rules 408

threading 408

trigger actions 409

using with import 255

using with import and export 409

viewing enabled triggers 435

XML import 386

triggers directory 29

triple counts 483


example 315

type properties 185

types

and instances 73

deleting 174

introduction to 73

typographical conventions 19

U

undefined datatype 190


uninstaller directory 29

uninstalling Sentences 69

update Dataform 235

update queries 343

updating changes 135

URL

using a URL with a hyperlink datatype

190 191

user

changing user 149

preferences 149


and the client API 47

and triggers 47

format 46

how to refer to 47

pre-defined names 47


user parameters 47

user interface

explorer 114

introduction 113

options 109

Query Editor 131

schema pane 119

the Dataform 128

user preferences 149

user security 148

V

valid XML 377

value types 166

and datatypes 166

behaviour 168

creating 166

values

behaviour 168

creating 169

introduction to 73

size of 165

visibility 168

verb 170

virtual directories 36

visibility

of instances 168

of schema and data 152

W

web security 57 68

whatrsquos new 18

wildcards 308

example 308

X

XML 378

action attributes 386

associations appear as child elements 389

attributes 378

combining simple elements 391

conventions 389

data input and output methods 380

derived element type names 390

DTD 377

DTD parameter 384

elementIDs parameter 385

elements 378

export Sentences schema 379

export using command line 387

import and derivations 386

import and triggers 386

import in multi user environments 386

import using a servlet 385

import using command line 388

import XML data 381

including sentences IDs 391

introduction to 377


mixed content is not allowed 390

online importing 388

output format parameter 384

output options 368

output options for schema export 379

380


query properties 367

SentencesID parameter 385

servlet access 382

servlet parameters 382

setting options in Query editor 392

split multiple lines 390



terminology 377

use content not attributes 389

using alternative parsers 389

using command line tools 387

using element IDs 391

using servlets 381

using the API 388

using the Query editor 381

valid XML 377

well formed 377

XML based user interface 111

XSL

background colour option 360

export stylesheet 371

generated stylesheet 369

layout options 357

no (none) stylesheet 369

printing page breaks option 360

show grid option 360

show separator option 360

stylesheet 357

stylesheet from server 369

stylesheet from URL 370

stylesheet options 368

stylesheet properties 357

tablexsl example 374

XSLT 378

Y

your comments 20