You are on page 1of 579

Sesame User Guide

A guide to getting the most from


Sesame Database ManagerTM

Release 2.0
Sesame Database ManagerTM User Guide
The software described in this Users Guide is furnished under a license agreement and may be
used only in accordance with the terms of that license agreement.

Copyright Notice
Copyright 2007 Lantica Software, LLC. All Rights Reserved.
Documentation version 2.0

NO WARRANTY: This documentation is delivered to you AS-IS. Lantica Software, LLC makes no
warranty as to its accuracy or use. Any use of this documentation or the information contained
herein is solely at your own risk. This documentation may include technical or other inaccuracies
or typographical errors. Lantica Software, LLC reserves the right to make changes to this
documentation without notice.

No part of this publication may be copied by any means without the express prior written
permission of Lantica Software, LLC, P.O. Box 27, Penns Park, 18943-0027

Acknowledgements
Sesame uses parts of the iMatix SFL package, Copyright 1991-2000 iMatix Corporation
http://www.imatix.com.
Sesame is based in part on the work of the FLTK project (http://www.fltk.org).

Sesame is based in part on the Hoard software product (http://www.hoard.org). Copyright


1998 - 2003, Emery Berger and The University of Texas at Austin. The use and distribution of
Hoard is governed by a modified version of the GNU Lesser General Public License version 2.1 as
published by the Free Software Foundation, http://www.fsf.org.

Sesame makes use of the PCRE library. Copyright (c) 1997-2006 University of Cambridge
this software is provided by the copyright holders and contributors "as is" and any express or
implied warranties, including, but not limited to, the implied warranties of merchantability and
fitness for a particular purpose are disclaimed. in no event shall the copyright owner or
contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential
damages (including, but not limited to, procurement of substitute goods or services; loss of use,
data, or profits; or business interruption) however caused and on any theory of liability, whether
in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the
use of this software, even if advised of the possibility of such damage.

Trademarks
Sesame Database Manager is a trademark of Lantica Software, LLC.
Windows, Microsoft Office, Microsoft Word, and Microsoft Excel are registered trademarks of
Microsoft Corporation.
WordPerfect is a registered trademark of Corel Corporation.
Other product names mentioned in this documentation are trademarks of their respective
companies and are hereby acknowledged.

LANTICA SOFTWARE LICENSE AND WARRANTY


IMPORTANT: PLEASE READ THE TERMS AND LLC AND/OR ITS SUBSIDIARIES (LANTICA) IS WILLING
CONDITIONS OF THIS LICENSE AGREEMENT CAREFULLY TO LICENSE THE SOFTWARE TO THE INDIVIDUAL,
BEFORE USING THE SOFTWARE. LANTICA SOFTWARE, COMPANY OR OTHER LEGAL ENTITY THAT WILL BE
USING THE SOFTWARE (REFERENCED BELOW AS YOU abuse or misuse. All replacement media will be warranted for the
OR YOUR) ONLY ON THE CONDITION THAT YOU remainder of the original warranty period or thirty (30) days,
ACCEPT ALL OF THE TERMS OF THIS LICENSE whichever is longer. Lantica does not warrant that the Software will
AGREEMENT. THIS IS A LEGAL AND ENFORCEABLE meet your requirements or that the operation of the Software will be
CONTRACT BETWEEN YOU AND LANTICA. BY OPENING uninterrupted or that the Software will be error-free.
THIS PACKAGE, BREAKING THE SEAL, OR LOADING THE
SOFTWARE, YOU AGREE TO THE TERMS AND THE ABOVE WARRANTY IS EXCLUSIVE AND IN LIEU OF
CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT ALL OTHER WARRANTIES, WHETHER EXPRESS OR
AGREE TO THESE TERMS AND CONDITIONS, MAKE NO IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED
FURTHER USE OF THE SOFTWARE AND REMOVE ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
INSTALLATION FROM YOUR SYSTEM. PARTICULAR PURPOSE AND NON-INFRINGEMENT OF
INTELLECTUAL PROPERTY RIGHTS. THIS WARRANTY
1. License GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE
The software which accompanies this license (collectively, the OTHER RIGHTS WHICH VARY FROM STATE TO STATE
Software) is the property of Lantica and/or its licensors and is AND COUNTRY TO COUNTRY.
protected by U.S. and international copyright law. While Lantica
continues to own the Software, you will have certain rights to use 3. Disclaimer of Damages:
the Software after you accept this license. This license governs any SOME STATES AND COUNTRIES DO NOT ALLOW THE
releases, revisions, or enhancements to the Software that Lantica LIMITATION OR EXCLUSION OF LIABILITY FOR
may furnish to you. You may be held legally responsible for any INCIDENTAL OR CONSEQUENTIAL DAMAGES SO THE
copyright infringement which is caused or encouraged by your BELOW LIMITATION OR EXCLUSION MAY NOT APPLY TO
failure to abide by the terms of this license. Except as may be YOU.
modified by a Lantica license certificate, license coupon, license TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE
key (each a License Module) which accompanies, precedes, or LAW AND REGARDLESS OF WHETHER ANY REMEDY SET
follows this license, your rights and obligations with respect to the FORTH HEREIN FAILS OF ITS ESSENTIAL PURPOSE, IN NO
use of the Software are as follows: EVENT WILL LANTICA OR ITS LICENSORS BE LIABLE TO
YOU FOR ANY SPECIAL, CONSEQUENTIAL, INDIRECT,
You may: PUNITIVE, INCIDENTAL OR SIMILAR DAMAGES,
A. Use one copy of the Software on a single computer. If a License INCLUDING BUT NOT LIMITED TO ANY LOST PROFITS OR
Module accompanies, precedes, or follows this license, you may LOST DATA ARISING OUT OF THE USE OR INABILITY TO
make that number of copies of the Software licensed to you by USE THE SOFTWARE, EVEN IF LANTICA HAS BEEN
Lantica as provided in your License Module. Your License Module ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN NO
shall constitute proof of your right to make such copies; EVENT SHALL LANTICAS OR ITS LICENSORS' LIABILITY
B. Make one copy of the Software for archival purposes; EXCEED THE PRICE THAT YOU PAID FOR THE
C. Use the Software on a network, provided that you have a SOFTWARE. The disclaimers and limitations set forth above will
licensed copy of the Software for each computer simultaneously apply regardless of whether you accept this license or not.
accessing the Software over that network; and
D. After written notice to Lantica, transfer the Software to another 4. General:
person or entity on a permanent basis, provided that you retain no This license will be governed by the laws of the Commonwealth of
copies of the Software and that the transferee agrees to the terms of Pennsylvania, United States of America, notwithstanding any
this license. conflicts rules to the contrary. This license agreement and any
related License Module is the entire agreement between you and
You may not: Lantica relating to the Software and supercedes all prior or
A. Copy the printed documentation that accompanies the Software; contemporaneous oral or written communications, proposals and
B. Sublicense, lease, or rent any portion of the Software; representations with respect to its subject matter, and shall prevail
C. Distribute the Software to others; over any conflicting or additional terms of any quote, order,
D. Reverse engineer, decompile, disassemble, modify, adapt, acknowledgement, or similar communications between the parties.
translate, make any attempt to discover the source code of the This agreement may only be modified by a License Module or by a
Software, or create derivative works based on or incorporating the written document which has been signed by both you and Lantica.
Software; or This license will automatically terminate without notice from
E. Use the Software in any manner not authorized by this license. Lantica if you fail to comply with any of the terms contained
herein. You may terminate this license at any time by giving
2. Limited Warranty: written notice of termination to Lantica. Upon any termination of
Lantica warrants that the media on which the Software is this license, you must cease all use of and destroy all copies of the
distributed will be free of defects in materials and workmanship Software. The disclaimers of warranties and damages and limitation
under normal use and service for a period of sixty (60) days from on liability shall survive any termination of this license. Should you
the date of delivery of the Software to you. Your SOLE remedy in have any questions concerning this license, or if you desire to
the event of a breach of this warranty will be that Lantica will, at its contact Lantica for any reason, please write to: Lantica Customer
option, replace any defective media returned to Lantica within the Service, P.O. Box 27, Penns Park, PA 18943-0027, USA
warranty period or refund the money that you paid for the Software.
This warranty will not apply if the defect resulted from accident,
Sesame's Menu Trees
Sesame Application Menu Application Menu (multiple databases)

Add Data Menu (top)

Add Data Menu (bottom)

4
MENU TREES

Search Menu

Application Utilities Menu

Search Update Menu Submenus

5
MENU TREES

Search Update Menu (top)

Search Update Menu (bottom)

6
Table of Contents

Sesame's Menu Trees................................................................4

Introducing Sesame................................................................ 21

1 Getting Started................................................................. 23
What is Sesame? ........................................................................... 23
Why are there two Sesame programs?.......................................................... 23
What is a database? ................................................................................... 23
What is a layout? ....................................................................................... 23
What is a layout element? ........................................................................... 24
What is a field and a record? ....................................................................... 24
Summary .................................................................................................. 24
Installing Sesame.......................................................................... 25
Starting & Using Sesame ............................................................... 25
Start Sesame Database Manager ................................................................. 25
Converting your Q&A databases to Sesame ................................................... 30
To Start Sesame Designer........................................................................... 30
Using Sesame Help .................................................................................... 31
Uninstalling Sesame ................................................................................... 32

2 Sesame's Screens and Menu System ................................ 33


Sesame's Menu Bar and Toolbar .................................................................. 33
The Menu Bar ............................................................................................ 34
The File Menu ............................................................................................ 34
The Edit Menu ........................................................................................... 34
The Macro Menu ........................................................................................ 35
The View Menu .......................................................................................... 35
The Help Menu........................................................................................... 36
The Quick Start Menu ................................................................................. 36
The Toolbar and icons................................................................................. 36
The Status area ......................................................................................... 37
Sesames main screens............................................................................... 38
Quick Start Menu ....................................................................................... 39
Single Level Menu Trees ............................................................................. 42
Hiding the Menu Tree ................................................................................. 43
Application Menu........................................................................................ 43
Search/Update expanded menu ................................................................... 44
Add Data expanded menu ........................................................................... 45
The Spec Window .......................................................................... 46
The Spec Action Bar ................................................................................... 48
Ways of Working with Sesame ..................................................................... 49
Using the Application menu ......................................................................... 49

7
Contents continued

Search/Update Submenus ........................................................................... 50


Function Key Menu ..................................................................................... 55
Window Management .................................................................... 56
Shift-Enter Toggle ...................................................................................... 56
Attachment ............................................................................................... 57
Embedded Dialogs ..................................................................................... 57
The F6 Edit Window.................................................................................... 58
Edit Window Features ................................................................................. 59

3 Designing a Sesame Application....................................... 61


Introduction .................................................................................. 61
To Start Sesame Designer. ............................................................ 61
Terminology .............................................................................................. 63
Some definitions ........................................................................................ 64
Fields and layout elements .......................................................................... 65
Summary .................................................................................................. 66
Ways to Start Designer and Use DSR files ..................................................... 66
The DSR file .............................................................................................. 67
Creating a New Sesame Application .............................................. 68
ASCII Database ............................................................................. 68
XML Database................................................................................ 70
Q&A Translation ............................................................................ 70
Q&A Translation Options ............................................................................. 71
Managing Q&A Translation Errors ................................................................. 72
Improved Q&A Report Translation ................................................................ 72
Correction to Run-On Q&A Programming imports ........................................... 72
Creating a new application using Designer.................................... 73
Creating a new database and form ............................................................... 74
Laying out a form....................................................................................... 75
Moving around the form.............................................................................. 76
Adding and deleting layout elements ............................................ 77
Changing the Basic Form Size...................................................................... 77
Types of layout elements ............................................................................ 77
Static Text Elements .................................................................................. 77
Adding static text....................................................................................... 77
Adding Dynamic (Data) Layout Elements ...................................................... 78
Text Boxes ................................................................................................ 78
Adding Layout Elements by Typing on the Form ............................................. 78
Rules for naming Layout Elements ............................................................... 79
Spaces in Layout Element names ................................................................. 79
Adding a layout element with the Layout Element Adder ................................. 81
Element Example Palette ............................................................................ 82
"Word Processor" Capabilities While Typing On Form ...................................... 83
8
Contents continued

Types of layout elements that can be added to a form .................................... 83


The different element types......................................................................... 85
Tabbed Pages ("Tabs") ............................................................................... 91
Subforms .................................................................................................. 91
Static Scroll Region .................................................................................... 91
Page Marker .............................................................................................. 93
Binding layout elements to database fields .................................................... 94
Designer Layout Tools ................................................................... 96
Moving Between Elements in Designer .......................................................... 96
Resetting Navigation Order ......................................................................... 96
Scoot Mode ............................................................................................... 96
Snap To Grid ............................................................................................. 97
Right Click Menu ........................................................................................ 97
Make Like Me ............................................................................................ 97
Move Up Layer/Move Down Layer ................................................................ 98
Relabel an element..................................................................................... 98
Use as Example ......................................................................................... 99
Duplicate Me (copy a layout element)........................................................... 99
Duplicate Selected Elements...................................................................... 100
Deleting layout elements .......................................................................... 101
Undo ...................................................................................................... 101
Working with multiple layout elements ....................................................... 101
Selecting Multiple Groups of Elements With Shift-Rubber-band ...................... 102
Moving layout elements ............................................................................ 102
Resizing layout elements........................................................................... 103
Resizing the form ..................................................................................... 104
Off the form the "canvas" ...................................................................... 105
Previewing the application......................................................................... 105
Can use X commands in Preview Mode ....................................................... 106
Saving Your Design as a Sesame Application............................... 108
Changing the Appearance of Forms ............................................. 109
Form redesign ......................................................................................... 109
Control Panels ......................................................................................... 109
Property Editor vs. Property Viewer ............................................................ 112
Property Viewer ....................................................................................... 112
Property Editor ............................................................................ 114
Property Editor - Color tab ........................................................................ 115
Property Editor - Text tab ......................................................................... 116
Property Editor - Look tab ......................................................................... 116
Property Editor - Position tab..................................................................... 116
Property Editor - Format tab...................................................................... 119
Setting formats for a layout element .......................................................... 120
Formatting multiple layout elements together.............................................. 123

9
Contents continued

Setting default formats for a layout (form or report)..................................... 123


Setting default formats for an application.................................................... 124
Property Editor - Other Tab ....................................................................... 125
Bound To See "Binding layout elements to database fields" on page 6. ....... 126
Selection Layers .......................................................................... 128
Set Selection Layer .................................................................................. 129
The Advanced Element Selector Control Panel............................. 131
Examples of using Advanced Element Selector............................................. 131
Customizing Forms ...................................................................... 133
Changing a layout element's label .............................................................. 133
Renaming a Layout Element ...................................................................... 134
Renaming a series of layout elements - the "R" setting ................................. 136
Setting a layout element's initial value........................................................ 136
Making a layout element read-only............................................................. 137
Making a layout element unique................................................................. 138
Making a layout element invisible............................................................... 138
Adding data entry restrictions.................................................................... 139
Programmed data entry restrictions ........................................................... 142
Setting an Element to Store Unique Values ................................................. 143
Data Entry Templates ............................................................................... 144
Creating User Help Screens ....................................................................... 146
Creating custom help screens .................................................................... 147
Creating custom tooltips ........................................................................... 149
Other Form Customization........................................................... 150
Program Editor ........................................................................................ 150
Change Program Execution Order............................................................... 150
Change Navigation Order .......................................................................... 152
Resetting Navigation Order ....................................................................... 153
Directional Navigation............................................................................... 153
Other Control Panels When Designing A Layout............................................ 153
The Message Log ..................................................................................... 153
Change Log/Advanced Undo ...................................................................... 153
Form Management features......................................................... 155
Switch to Alternate Form .......................................................................... 155
Relink Form............................................................................................. 155
Startup Form........................................................................................... 156
Setting Properties for an Application........................................... 158
Application Property Manager .................................................................... 158
Setting values ......................................................................................... 160
Managing a Database .................................................................. 161
Managing fields........................................................................................ 161
Managing Layouts .................................................................................... 163
Attribute Table......................................................................................... 165

10
Contents continued

Application Documenter .............................................................. 165


Other Application Menu Tree Options .......................................... 166
Delete All Data Records ............................................................................ 166
Security Manager ..................................................................................... 167
Temporarily Disable Security ..................................................................... 167
Global Values List Manager........................................................................ 167
Export Design to XML ............................................................................... 167
Merge Application .................................................................................... 167
Making Design Changes to a Sesame Application ........................ 168
Working with Designer files ....................................................................... 168
Saving Your Design as a Sesame Application ............................................... 169
Reconciling Designer Changes..................................................... 170
What is Reconciling?................................................................................. 170
Steps to reconcile .................................................................................... 171
Reconcile Options..................................................................................... 171

4 Tabbed Pages ................................................................. 175


Adding a Tab Group ................................................................................. 176
Adding a Layout Element to a Tab Page ...................................................... 177
Adding additional tab pages ...................................................................... 179
Renaming Tab Pages ................................................................................ 180
Aligning layout elements ........................................................................... 181
Changing Order of Tab Pages .................................................................... 181
Deleting a Tab Page ................................................................................. 182
Selecting Elements on a Tab Page .............................................................. 182
Changing Tab Colors ................................................................................ 182
Sizing Tab Groups .................................................................................... 183
Moving Tab Groups .................................................................................. 184
Deleting a Tab Group................................................................................ 184
Selecting Position of Tab Labels ................................................................. 184

5 Creating Subforms ......................................................... 185


Terminology ............................................................................................ 186
Creating a subform .................................................................................. 187
The Subform Settings dialog...................................................................... 190
Creating a subform using relational linking .................................................. 195
Importing subform data ............................................................................ 198

6 Adding and Editing Data................................................. 201


Introduction ............................................................................................ 201
Data types .............................................................................................. 201
Using forms............................................................................................. 204
Entering data from the keyboard................................................................ 206
11
Contents continued

Text elements.......................................................................................... 206


Single line text element ............................................................................ 206
Autocomplete .......................................................................................... 207
Multi-line text element.............................................................................. 207
LE Auto-selection ..................................................................................... 207
The Expanded Field Editor ......................................................................... 208
Using special layout elements .................................................................... 208
Using a combo box................................................................................... 209
Using a list box ........................................................................................ 209
Using a check box .................................................................................... 210
Using a radio button group........................................................................ 211
Using an image field ................................................................................. 211
Navigating around a form.......................................................................... 212
Data entry shortcut keys........................................................................... 213
Saving a record ....................................................................................... 216
Record-to-record navigation ...................................................................... 216
Bookmark a Record .................................................................................. 217
Deleting a record ..................................................................................... 217
Duplicate Records........................................................................ 218
Removing or Deleting Duplicate Records from a Result Set............................ 218
Use of Duplicates Search........................................................................... 223
Re-using Previous Values ............................................................ 224
Autocomplete .......................................................................................... 224
Using the Windows Clipboard Cut/Copy/Paste .......................................... 225
Ditto Field/Record .................................................................................... 226
Memory Menu.......................................................................................... 226
Copying fields and records ........................................................................ 226
F11 Copy and Paste Records...................................................................... 227
Copying / Pasting a Single Record .............................................................. 227
Copying / Pasting Multiple Records ............................................................. 228
Copying Main Form & Subform Data ........................................................... 229
Undo ...................................................................................................... 231
'Immediate' Undo..................................................................................... 232
Restoring a field or record to original values ................................................ 232
Making Corrections................................................................................... 232
Printing Records....................................................................................... 233
Using Table view to add/view/edit data ..................................... 233
Switching to Table View ............................................................................ 233
Customizing Table View ............................................................................ 234
Sorting records in Table View .................................................................... 235
Saving Table View specs ........................................................................... 235
Summary functions and charts .................................................................. 235

12
Contents continued

7 Navigating Forms ........................................................... 239


Navigation keys ....................................................................................... 239
Element types and keystrokes ................................................................... 241
Moving between main form and subforms ................................................... 243
Navigating Table View .............................................................................. 244

8 Searching and Sorting .................................................... 247


Introduction and terminology .................................................................... 247
Basic Searches ........................................................................................ 247
Autocomplete when searching. .................................................................. 250
Templates and searching .......................................................................... 250
The Result Set ......................................................................................... 251
Performing a new search........................................................................... 253
Search criteria essentials .......................................................................... 254
Special search characters.......................................................................... 255
Wildcard characters.................................................................................. 258
Advanced searches ...................................................................... 259
Other Menu Commands to Run a Search ..................................................... 261
Searching all fields: Simple Search & Universal Search ................................. 262
Simple Searches ...................................................................................... 263
Universal search ...................................................................................... 266
Keyword searches .................................................................................... 267
~ (Sounds-like Search)............................................................................. 269
Refining the result set .............................................................................. 271
Next matching Record in Current Results .................................................... 273
Searching Special Layout Elements ............................................................ 275
Image searches ....................................................................................... 277
Programmed retrieves .............................................................................. 280
Performance of retrieve spec programming ................................................. 282
Find on this Form ..................................................................................... 283
Saving Searches for re-use ....................................................................... 284
Using the Spec Manager ........................................................................... 284
Regular Expressions .................................................................... 288
The Basics............................................................................................... 290
Quantifiers .............................................................................................. 290
Groups and Text Ranges ........................................................................... 291
Character Classes .................................................................................... 291
Constructs regex() and qanda() ................................................................. 292
Sorting records............................................................................ 293
How to Sort............................................................................................. 293
Saving sort specs for re-use ...................................................................... 296
Setting a default sort spec ........................................................................ 296

13
Contents continued

9 Mass Updating................................................................ 297


Mass Update overview .......................................................................... 297
Running a mass update ............................................................................ 298
Interrupting a Mass Update ....................................................................... 301
Using the Mass Update Spec...................................................................... 301
Using the Program Editor .......................................................................... 304
Saving mass update specs for re-use.......................................................... 307
Using the Spec Manager ........................................................................... 307
Mass updates and security ........................................................................ 312
Q&A
Q&A and mass updates........................................................................ 312
Special Notes on Mass Update ................................................................... 313

10 Printing Forms ............................................................. 315


Printing in Update mode ........................................................................... 316
The Print Forms Dialog Box ....................................................................... 317
Printing in Add mode ................................................................................ 322
Appearance of the printed record ............................................................... 322
Printing table view ................................................................................... 324
More ways to print ................................................................................... 327

11 Merge Printing Your Data ............................................. 329


Merge documents..................................................................................... 329
Merge File Print........................................................................................ 329
Merging via data export ............................................................................ 331
WordMerge ............................................................................................. 334

12 Import, Export And Copying Records ........................... 337


Importing Data............................................................................ 337
File format for import file ASCII ............................................................. 337
How to import ......................................................................................... 339
Ignoring columns ..................................................................................... 340
Import errors .......................................................................................... 343
Exporting Data ............................................................................ 343
File format for export file ASCII.............................................................. 344
Sorting of Export files ............................................................................... 344
Sort Order of Export ................................................................................. 347
ASCII options .......................................................................................... 347
Fixed ASCII export and truncating values.................................................... 350
Copying Records.......................................................................... 352
How to copy ............................................................................................ 353
Manual element matching ......................................................................... 357
Copying the same field to multiple destinations ........................................... 358
XML Utilities ................................................................................ 359
14
Contents continued

Export Application to XML ......................................................................... 359


XML Database ......................................................................................... 359
Export Design to XML ............................................................................... 359
Warning on export to XML ......................................................................... 359
Export Layouts to XML .............................................................................. 359
Import Layouts from XML.......................................................................... 360

13 Working With Subforms ............................................... 361


Using subforms........................................................................................ 361
Types of subform ..................................................................................... 361
Form Navigation ...................................................................................... 363
Adding and editing data ............................................................................ 364
Parents and children................................................................................. 365
Editing existing data................................................................................. 366
Printing forms.......................................................................................... 368
Searching ............................................................................................... 368
Importing and exporting ........................................................................... 372

14 Creating and Using Macros ........................................... 377


Alerts appear while recording/playing macros .............................................. 378
Recording a macro ................................................................................... 378
Playing back a macro................................................................................ 379
Saving and naming a macro ...................................................................... 380
Loading a macro ...................................................................................... 380
Macro files .............................................................................................. 381
Macros vs. programming........................................................................... 381
Human readable macro files ...................................................................... 381
Series Counter......................................................................................... 382
Recently-used Macro List .......................................................................... 383

15 Designing Reports ........................................................ 385


Introduction ................................................................................ 385
Designing and Using Quick Reports ............................................. 386
Full-Feature Reports.................................................................... 390
The report interface.................................................................................. 392
Columnar reports ........................................................................ 396
Basic design ............................................................................................ 396
Adding layout elements to the report.......................................................... 397
Element Selection .................................................................................... 401
Element Movement .................................................................................. 401
Changing properties ................................................................................. 401
Property Editor / Property Viewer............................................................... 402
Preview mode.......................................................................................... 403
15
Contents continued

Additional Design Features ........................................................................ 404


Ignore Blank Values ................................................................................. 404
Breaks .................................................................................................... 404
Page Headers and Footers......................................................................... 404
Multiple breaks on single group.................................................................. 404
No Repeat option ..................................................................................... 405
Month and Year Breaks ............................................................................. 405
Scrolling ................................................................................................. 405
Printing Options ....................................................................................... 405
Freeform Reports ........................................................................ 405
Basic Design............................................................................................ 405
Add layout elements to the report .............................................................. 406
Combination Freeform/Columnar reports.................................... 409
Basic design ............................................................................................ 409
Adding layout elements to the report.......................................................... 410
Report Creation Wizard ............................................................... 412
Attaching retrieve and sort specs ................................................ 416
Saving a report ............................................................................ 418
Previewing a report ..................................................................... 418
Reconciling a report .................................................................... 420
Running a report from the Application Menu ............................... 420
Advanced Report Features........................................................... 420
Toggle the display .................................................................................... 420
Summary totals and breaks....................................................................... 421
Derived columns ...................................................................................... 423
HTML output files ..................................................................................... 425

16 Using the Application Utilities ...................................... 427


The Application Utilities Menu .................................................................... 427
Backup Application ................................................................................... 427
Design New Application............................................................................. 428
Redesign Current Application ..................................................................... 428
Merge Application .................................................................................... 428
Trim Application....................................................................................... 429
Export Application to XML ......................................................................... 430
Copying .................................................................................................. 431

17 Securing Your Applications .......................................... 433


User levels .............................................................................................. 434
The Security Manager ............................................................................... 437
Groups tab Defining groups ................................................................... 438
Users tab Define users .......................................................................... 439

16
Contents continued

Layout and Layout Element settings tab Define element level access .......... 441
Application Settings tab Define application-wide rights.............................. 443
Using a protected application..................................................................... 445
Password Controls.................................................................................... 446
Deployment and preventing design changes ................................................ 446
Server administration ............................................................................... 447
Summary ................................................................................................ 449
Temporarily Disable Security ..................................................................... 449
Security frequently-asked questions ........................................................... 450

18 Web Capabilities .......................................................... 451


Web Server.................................................................................. 451
Sesame Web Server Mini-Tutorial............................................................... 451
Available Fields and Tags .......................................................................... 470
Automatic Email Retrieval and Response..................................... 472

19 Troubleshooting ........................................................... 477


Q&A Translation Errors................................................................ 477
Managing Q&A Translation Errors ............................................................... 477
Starting Server Administration................................................................... 477
Unlocking an Application ............................................................. 480
Starting Server Administration................................................................... 480

APPENDIX 1 - Network Administration ................................. 483


Why use a client-server setup? .................................................................. 483
Configurations ......................................................................................... 483
Limitations .............................................................................................. 485
Setting Up the Client-Server environment ................................................... 485
Command line options .............................................................................. 486
Server .................................................................................................... 486
Client ..................................................................................................... 486
Ports ...................................................................................................... 486
Using Sesame Server ............................................................................... 487
Server Status Window .............................................................................. 488
Server Administration Interface .................................................. 489
Standalone administrative client ................................................................ 498
Network administration tips ........................................................ 498
Sesame on the Internet ............................................................................ 499
New Sesame 2.0 Integrity Features ............................................ 502
Log File................................................................................................... 502
Lock/Unlock ............................................................................................ 502
Communications ...................................................................................... 503

17
Contents continued

Optimizing Performance .............................................................. 504


Find Duplicates Optimization ..................................................................... 504
Relational Records Search ......................................................................... 504
X-Commands........................................................................................... 505
Images ................................................................................................... 505
FormFieldValues in Tables ......................................................................... 505
Just in Time Compilation ........................................................................... 505

APPENDIX 2 - Sesame Environment Variables ...................... 507


All Operating Systems Variables................................................................. 507
Unix-only variables................................................................................... 507
Setting Report Writer Output File Environment Variable ................................ 508

APPENDIX 3 - Philosophy ..................................................... 515


Filling the void ......................................................................................... 515
Batch based operation .............................................................................. 515
Form based ............................................................................................. 515
Non-invasive interface .............................................................................. 515
Revaluate ease-of-use .............................................................................. 516
The philosophy in action ........................................................................... 516
Property Editor vs. Property Viewer ............................................................ 517
Report Writer .......................................................................................... 517
Whats in it for you? ................................................................................. 517

APPENDIX 4 Advanced Concepts........................................ 519


Application components ............................................................................ 519
Forms and layout elements ....................................................................... 519
Record definitions and field definitions ........................................................ 520
Binding user interface components to data engine components...................... 521
Subforms and subrecords.......................................................................... 523
Natural vs. relational linking ...................................................................... 523
Pipes and wires........................................................................................ 527
Running client/server vs. running standalone .............................................. 528
The command protocol and the notification protocol ..................................... 531
Encryption............................................................................................... 531
Delegation of labor................................................................................... 532
File pairings............................................................................................. 533
Operating system platforms ...................................................................... 534
The user interface .................................................................................... 534
The hardware interfaces ........................................................................... 535
Non-proprietary code and non-invasive installation ...................................... 535
Future versions........................................................................................ 536

18
Contents continued

APPENDIX 5 Sesame Utility Programs............................... 537


SUnlock .................................................................................................. 537
SVersion ................................................................................................. 537

APPENDIX 6 Sesame Shortcut Keys .................................. 539

APPENDIX 7 Sesame.ini File.............................................. 541


Sesame Initialization File ............................................................ 541
Creating a Sesame.ini file ......................................................................... 541
Look and Feel Commands ......................................................................... 542
Window Property Commands ..................................................................... 544
Client Behavior Commands........................................................................ 545
Server Behavior Commands ...................................................................... 547
SDesigner Commands .............................................................................. 549
Security Commands ................................................................................. 550
Mode Commands ..................................................................................... 550
Memory Menu Commands ......................................................................... 550
Email Commands ..................................................................................... 551
SCommands ............................................................................................ 552

APPENDIX 8 Startup Switches........................................... 555

INDEX ................................................................................... 561

-------------------------  -------------------------

19
Introducing Sesame
SESAME is a powerful and flexible database manager designed to meet the needs of a
wide range of users and developers. Whether you are a small business do-it-
yourselfer, the head of an organization, a corporate department administrator or a
professional developer, Sesame gives you the tools you need to easily create database
applications and organize and present the information in them.

Features like centralized application design facilities, a form-based interface, intuitive


query-by-example searching, and portable HTML reports will have you creating
attractive and smoothly functioning applications soon after starting with Sesame.

If you are new to databases, Sesame makes getting started with simple applications
easy, fast, and fun. As you learn, Sesame offers more advanced tools to further
enhance your applications. For those with more experience, Sesame provides a variety
of options all within easy reach for customizing and programming your
applications. Basic design tasks are easy to perform, but when you need to move
beyond the basics, the tools to do so are at your fingertips.

Sesame provides seamless client-server capabilities as different "personalities" of the


same program. This means that your copy of Sesame can run standalone, serve other
Sesame clients, or connect to a Sesame server just by the way you start the
program. Connecting to a Sesame server across the Internet is like connecting to a
Sesame server on the desk next to yours.

Sesame is a truly cross-platform product, currently available for a number of versions


of both Microsoft WindowsTM and Linux. If you are considering switching platforms, or
you have (or are considering) a network environment mixing both platforms, Sesame
is an ideal choice. Making the switch is a simple matter of copying your application
files to the new platform* and running the appropriate executable.

If you are making the switch to Sesame from another database manager, a variety of
integrated facilities can help simplify that transition. Sesame provides Symantec
Q&ATM users with an extensive translator for Q&A databases. Those using other
programs can take advantage of Sesame's data import facilities, including the ability
to perform hierarchical imports when migrating from a relational product.

The documentation that comes with Sesame is designed to get you quickly started and
to serve as a complete reference library as you begin to explore Sesames features
and capabilities. Four guides are included with the product:

21
INTRODUCING SESAME
Sesame Quick-Start Tutorials This practical hands-on guide demonstrates the
basic commands and building blocks of Sesame by guiding you step-by-step through
creating four database applications, each with a focus on different features and tasks.
If you are new to Sesame or database managers in general, we encourage you to
work through these tutorials as a first step to using Sesame.

Sesame User Guide This comprehensive guide to all of Sesames features


and facilities provides both basic instructions and more detailed reference
information on all aspects of using the product. New users should see the
sections on Getting Started and Sesame's Screens and Menu System. Those
involved in data entry should see the sections on Adding and Updating Data
and Searching and Sorting. If you are switching to Sesame from another
program or need to integrate with other programs, there are sections on
Importing and Exporting Data. Those who want to create their own new
applications can use the sections on Designing a Sesame Application and
Designing and Using Reports. Professional developers who need in-depth
information on how Sesame operates should see the appendices, including
Advanced Concepts, in the back of this guide.

Sesame Programming Guide This guide provides the detailed information


needed to create truly extraordinary applications to meet the demands of
home office and small business users, all the way to medium-sized
organizations and corporate departments. Sesame contains a wealth of
programming tools in a language designed to be easy enough for non-
programmers yet powerful enough for experienced application developers.
Sesame's programming language, its features, syntax and commands with
accompanying usage examples are all covered in this guide.

Q&A Database Translation Guide A goal of Lantica Software is to


provide a bridge to the future for users of Symantec's Q&A database manager.
As such, Sesame includes the ability to translate Q&A databases into Sesame
applications. This guide provides all the information needed to make those
translations go smoothly, including advice on preparing Q&A databases to
minimize post-translation efforts in Sesame.

The above guides are designed to help you learn and build on your experience with
Sesame. As your interest and requirements grow, and you need to further adapt,
customize and expand your applications, you will find sections in these guides covering
the information you need.

* Assumes matching chip architecture, i.e. Intel to Intel.

22
Section 1
Getting Started
In order to begin using Sesame and working with the tutorials in the Sesame Tutorials
booklet, there are a few things it will help you to know. All of the concepts in this
section are covered in greater detail elsewhere in the Sesame User Guide, but a quick
overview of the basics will make it easier for you to get started.

What is Sesame?
Sesame is a database management system (DBMS). It is a program that gives you the
tools to add, store, retrieve, and work with your information.

Why are there two Sesame programs?


One is the Sesame database manager program (also known as "Sesame Runtime"),
the other is Sesame Designer. In Sesame, the design tools are separate so that you
can work on redesigning your database applications while others are still actively using
them.

What is a file with a .DB extension as opposed to one with a .DSR extension?
The Sesame Tutorials and Sesame User Guide refer either to a .db file or a .dsr file,
depending on the task you are performing.

Each Sesame application consists of a pair of files. The working application that you
use to enter and update records, run reports, and otherwise work with your data is
made up of a .db file and .dat file pair. When you open an existing application, Sesame
shows only files with the .db extension.

The copy of the application that you use in Sesame Designer to make design changes
is made up of a .dsr file and .ddt file pair. When you open an existing Designer file,
Sesame shows only files with the .dsr extension.

What is a database?
A Sesame application contains one or more databases that are in some way related
such as a customer database, an orders database, and an inventory database.
Basically, a database is all the records of a particular type along with the all of the
forms and reports that show the information in those records. For example, an Orders
database might consist of all the order records, the order form and the Orders By
Month report. For a detailed explanation of a database, see the Advanced Concepts
appendix.

What is a layout?
A layout is a form or report. It defines how you will look at and use the parts of your
information. Since Sesame is form-based, you create your databases by building and
editing layouts.

23
1 GETTING STARTED

What is a layout element?


A layout element is anything you place on a layout. A layout element can
be purely cosmetic, such as a graphic line or a box, it can display data from your
database records, display the result of a calculation, or let you change information
simply by clicking or making a selection from a pick-list. Sesame offers a variety of
layout elements you can use when designing your forms and reports.

What is a field and a record?


A field is where Sesame actually stores an item of data, such as a telephone number.
A record is a collection of fields. A record is displayed in a form.

For example, an Orders record may have fields for OrderDate, CustomerName and
ShipToAddress. It is rare, in Sesame, that you will work with actual fields. Normally,
you will work with layout elements. A layout element that displays the value (content)
of a field is said to be bound to that field. The only time that you need to deal with a
field is if you change its data type or its name.

Summary
An application, which consists of two files application.db and application.dat is
comprised of one or more databases each with one or more forms and optional
subforms. Forms and subforms are both comprised of layout elements. Most of those
layout elements will be bound to fields.

Data is stored in fields.


Fields are displayed on forms using layout elements, which can be thought of
as placeholders for those fields.
A layout element is unique to a specific form, and a form is defined by its
elements.
A field is not unique to a specific form. The same field can be displayed on
different forms.
Layout elements are bound to the fields whose information they display.

If I dont understand all this, can I still use Sesame?


Yes. You dont need to understand database structure or theory to make a useful
application thats easy to work with. As you progress through the tutorials, you will
learn how to accomplish everything you need to be successful with Sesame.

If you are eager to jump right into creating databases, we urge you to take advantage
of the practical exercises you will find in the Sesame Quick-Start Tutorials booklet,
particularly the first three:

24
1 GETTING STARTED

1. Form Designing Basics

2. Building a Simple Application

3. Building an Application with Multiple Databases

In an hour or less, you will gain more know-how about this part of Sesame than by
any other means.
Q&A
If you are migrating to Sesame from Symantec's Q&A, you will
also want to read the Q&A Database Translation Guide, a separate
booklet that comes with Sesame.

Installing Sesame

Sesame is easy to install. In Microsoft Windows:

Insert the Sesame CD.


After a moment, the Sesame installation screen will appear.
Click OK and follow the prompts.

For the most part, the Sesame installation is a simple file copy procedure. Directories
will be created and the required files copied into them. Depending on your operating
system, Sesame may also create desktop shortcuts for you. There are no registry
entries, DLLs, or changes to any system folders or settings. The only exceptions to this
are the desktop shortcuts, which are placed in the appropriate system folders on your
computer.

The Linux version of Sesame is also on the CD. The README file provides step-by-step
instructions for installing the Linux version.

For complete installation instructions for your operating system, and a list of installed
files, please refer to the separate Sesame Installation Guide provided with your
Sesame package.

Starting & Using Sesame

Start Sesame Database Manager

To start Sesame Database Manager (as opposed to Designer), do one of the following:

25
1 GETTING STARTED

Double-click on the Sesame shortcut on


your desktop:

Figure 1. Starting Sesame from the desktop


shortcut.
OR
Select :
Start / Programs / Sesame / Sesame
(Windows 2000).
Start / All Programs / Sesame / Sesame Figure 2. Starting Sesame from the Programs
(Windows XP). menu.

The Sesame opening screen is displayed:

From here you can open an


existing Sesame application by
either clicking on the Open
button on the toolbar (see
Figure 3 above) or by
selecting Open Application from
the File menu.

The File Open dialog is


displayed.
(See Figure 4 below.)

Figure 3. Sesame opening screen.

Figure 4. File Open dialog. Samples folder highlighted

26
1 GETTING STARTED

To open one of the sample databases supplied with Sesame, click on the Samples
folder and it will expand, showing the files within it. Only Sesame applications (with a
.DB file extension) are shown.

Select an application file with the keyboard or click on it to open it. (See Figure 5.)

Figure 5. Opening Customers application

The application is opened and you are shown the opening screen. (See Figure 7 on
page 29.) You are not automatically looking at data.

Recently Opened File list


Sesame keeps track of the last Applications you have worked on. To access this list,
you click on the dropdown arrow at the right of Sesame's file open dialogue root
directories line (see Figure 6 below).

Sesame will display your default directories and drives (as defined by your rootdirs.ini
file) followed by the list of applications you have recently opened. The list will be
displayed with the most recent file being the first on the list. Clicking on any filename
in the list will open that file.

If you are using Sesame runtime, you will see a list of all recent Sesame runtime
applications (*.DB).

In SDesigner, you will be presented with a list of all recently used runtime applications
(*.DB) and designer files (*.DSR).

27
1 GETTING STARTED

If you select File/Translate Q&A in runtime the list will show all recently translated
Q&A databases (*.DTF).

Figure 6. Recently Used File list

Sesame also keeps a text version of this list of files, sesame_recent_files.txt, in the
Sesame startup directory.

Once the application is open you will want to view data, add data, or perhaps run a
report. All of these require using a form. To do so, you:

1. Select an operation (Add data, Search/Update)


2. Select a database within this application (there may be only one)
3. Select a form to use (there may be only one)

28
1 GETTING STARTED

Figure 7. Sesame opening screen. No form open at this stage.

In Figure 7 above, what is selected is:  Forms / Search/Update


 Customers database
 Main Form

Opening a form in Add Data mode shows you the form ready to add a new record. See
the section Adding and Editing Data in this user guide for full details.

Opening a form in Search/Update mode shows you the form open at the Retrieve
Spec. Press F10 or select Search Commands / Retrieve New Results from the menu
tree to display all records and browse through all of them, of fill in search criteria to
view just some of the records. See the section Searching and Sorting in this user
guide for full details.

To learn all about Sesame's user interface, see the next section in this user guide
Sesame's Screens and Menu System.

To view the complete menu tree structure, see section at the front of this user guide
Sesame's Menu Trees.

To learn how to move around a form, see the section Navigating Forms in this user
guide.

29
1 GETTING STARTED

Converting your Q&A databases to Sesame


Sesame will not only import your Q&A data, it will convert, or Translate your
databases into Sesame applications. Refer to the separate Q&A Database
Translation Guide for full details and a tutorial.

To Start Sesame Designer.


It is recommended that you become familiar with the basics of using Sesame
Database Manager before using Sesame Designer to create or modify Sesame
applications.

To start Designer do one of the following:

 Double-click on the SDesigner shortcut on your


desktop:

 Use the Start Menu / Program menu to start Figure 8. Desktop shortcut for
Designer (see Starting Sesame, above). Starting Sesame Designer.

There are two ways of starting Sesame Designer from within Sesame Database
Manager. You can open Designer and redesign the application you are currently
working with by selecting Application Utilities / Redesign Current Application from the
menu tree.

Or you can open Designer and start creating a brand new application by clicking on
the first button on Sesame's toolbar. (See figures 9 and 10 below.)

Figure 10. Opening Designer to create a new


application

Figure 9. Redesign Current Application

30
1 GETTING STARTED

You use Designer to create new Sesame applications and make design changes to
existing ones. Designer is described in the section Designing a Sesame Application
in this user guide.

Using Sesame Help

Sesame has three types of help facilities to assist users in all areas of the program:
context-sensitive help, custom help, and custom tool-tips.

 Sesames built-in help displays information about the particular task you are
performing. The information displayed pertains to the general area of the
program in which you are working. Built-in help displays when you press the
F1 key.

 Custom help allows the application designer to define a special user message
for any layout element on any form. When you press F1, Sesame first displays
the custom help message, if any, for the current element. (See Figure 11.) If
you close the custom message screen and press F1 again, Sesames built-in
help displays.

Figure 11. Custom help for Call Date. Displayed by pressing F1.

You can close a custom help screen by clicking the "X" (close window button) in the far
right corner of the help windows title bar, or by pressing F1 a second time to bring up
Sesames internal help screen.

You can resize the custom help screen by dragging its borders, or by using the title
bar buttons to minimize or maximize it.

31
1 GETTING STARTED

Note: The designer of the application may have programmed the form you are
using to automatically display a custom help message for any form element.

 The designer can also create a custom tooltip for any element placed on a
form. These display custom help messages in small pop-ups whenever the
mouse is positioned over the element. (See Figure 12.)

Figure 12. Custom tooltip for the Salesperson field.

Tooltips display automatically as you hover the mouse over the element to which they
are attached, and they self-close as you move the mouse off the element.

Uninstalling Sesame

Sesame makes no changes to your system settings or registry. To uninstall Sesame,


simply delete the Sesame directory. If shortcuts were created, you may also need to
delete these from your desktop and/or Start menus. Sesames non-invasive
installation makes it easy for you to move a Sesame installation from one computer to
another with no impact on the operating system.

32
Section 2
Sesame's Screens and Menu System
When you open a Sesame application, you are working in a multi-window environment
where different tasks are performed in different windows or panels. An example of this
is shown in Figure 1.

Figure 1. Sesames multi-window environment. Shown here is a database record in Update


mode in the main window; the Menu Tree in the top left window; and the Spec selector panel in
the lower left window.

This section covers the various screens you will see in Sesame. The actual operations
you perform within each screen will be discussed in the detailed
sections of the Sesame User Guide covering the individual operations.

Sesame's Menu Bar and Toolbar


Sesame uses a standard Windows type of menu bar and toolbar. (See Figure 2.)

33
2 SCREENS & MENU SYSTEM

Figure 2. Sesame Menu Bar and Toolbar

The Menu Bar


On the menu bar you will find the following choices and sub-choices:

The File Menu

 New Application Opens Sesame Designer to create a new application.

 Open Application Opens an existing Sesame application.

 Close Closes the current application.

 Save Forces a save of the current open application.

 Save As Copies the open application to a new application filename.

 Translate Q&A Translates a single Q&A 4.0 or 5.0 database to a new Sesame
application. This is not the same as importing data into an existing Sesame
application. See the section "Import, Export & Copy Records" if you want to
import data exported from Q&A.

 ASCII Database - Quickly creates a simple application when provided with only
the data from a previous application or database.

 XML Database Like the ASCII Database command it can create an application
from an ASCII file formatted as legal XML.

 Server Administration Opens the Administration window.

 Exit Closes open application and exits Sesame.

The Edit Menu

 Undo Undoes any new typing in the selected layout element. This is a one-
time operation that will undo and then redo only the new typing in an element.
It will leave previous, unchanged data untouched. Sesame has other types of
undo for records and designs on its menu trees.

 Cut Cuts to the clipboard any data selected in a layout element.

 Copy Copies to the clipboard any data selected in a layout element.

 Paste Pastes clipboard data to the selected layout element.


34
2 SCREENS & MENU SYSTEM

 Select All Selects everything in a selected layout element.

 Delete Deletes selected data in a layout element.

 Find on This Form Opens a query box that allows you to search for a text
string in the current record on an open form.

The Macro Menu

 Recording On Starts recording a macro.

 Recording Off Stops macro recording.

 Playback Plays back (runs) the current macro.

 Repeated Playback Runs the current macro the specified number of times.

 Save Macro Lets you name and save a recorded macro.

 Load Macro Loads a saved macro.

 Clear Macro Clears the currently loaded macro from memory.

 Set Series Counter Sets the initial value for an internal counter that is invoked
with the Ctrl-F2 keystroke combination.

 Set Series Format Sets the format of the Series Counter entries.

The View Menu

 Cursor Blink On Sets cursor to always blink.

 Cursor Blink Off Sets cursor to a non-blinking vertical line.

 Macro Visibility On Shows the results of a macro while it is being played back.

 Macro Visibility Off Hides the results of a macro while it is being played back.

 Autocomplete On - causes text elements to attempt to Autocomplete from all the


existing values for that element in the database.

 Autocomplete Off Turns off the Autocomplete feature. Useful in databases with
a very large amount of records.

 Directional Navigation On allows the Up and Down arrow keys to move up and
down based on element geography rather than navigation order.

 Directional Navigation Off Turns off Directional Navigation and reverts to


defined navigational order for the arrow keys.

35
2 SCREENS & MENU SYSTEM

 Open Command Area Displays the menu tree if it is has been closed by using
the Close Command Area command.

 Close Command Area Hides the menu tree.

 Show Quick Start Menu Opens a moveable, easy-click menu to access the
most used Sesame commands.

 Hide Quick Start Menu Closes the Quick Start Menu

 Show Function Key Menu Opens a pop-up Function Key Menu that provides
easy access to the keystroke combination commands used throughout Sesame
on a simple, moveable easy-click menu.

 Hide Function Key Menu Closes the Function Key menu.

The Help Menu

 Help Opens the main Sesame help screen.

 About Sesame Sesame program information screen.

The Quick Start Menu

 Performs the same function as the File selection Show Quick Start Menu and
open the Quick Start Menu.

The Toolbar and icons

Figure 3. Sesame Menu Bar and Toolbar

Looking at Figure 3, starting from the left, the Buttons are:

 New Opens Sesame Designer to create a new application.

 Open Opens an existing Sesame application.

 Save Saves the current open application.

 Record Navigation Controls See Figure 4. Allows one-click navigation to the


first record in the set (1), the previous record (2), the next record (5), and the
last record in the set (6). The number of records in the current set (4), and the
current record number (3) are displayed between these arrows.

36
2 SCREENS & MENU SYSTEM

You can type a record number into the


current record number box to move
directly to that record number. (The
current record number represents
Sesames internal record numbering
scheme and is not related to any
record number data field.) Figure 4. The Record Navigation Toolbar.

 Macro Shows the name of the macro loaded.

 Mode Shows which operational mode you are in, as follows:

Mode Color Action


Search Blue Retrieve Specification
Update Green Viewing Records
Add Maroon Adding Data
Working Red Sesame actively performing a task

The Status area


Sesame provides a status area to keep you informed as to where you are and provide
informational updates and messages as to what Sesame is doing. The status area, as
shown in Figure 5, has two parts:

The Tabbed window selector (upper part of status area)


You can open your application with access to Add and Search/Update modes at the
same time. The tabs allow you to easily toggle between the open modes, or go back to
the Application Menu by just clicking on them with the mouse. If you have multiple
databases in an application and open more than one, they will each show on a tab in
this area. The tabs will also respond to keyboard shortcuts. Alt-1 will move to the first
tab, Alt-2 to the second tab, and so on.

The Status line


The Status line is where Sesame tells you what mode it is in, how many records it has
found, or any errors that have occurred. It is also where custom messages are
displayed using the @Msg() programming command.

Figure 5. The Sesame status area. The Tabbed Window selector (top) and Status line (bottom).

37
2 SCREENS & MENU SYSTEM

Sesames main screens


The Sesame working screen is divided into three areas:

1. To the right is the Form area. This is the working area of Sesame for data entry,
searching, and updating your records.

Figure 6. Sesame Form window showing a record.

2. To the left of the Form area, at the top, is the application Menu Tree. The Menu
Tree is used for most day-to-day tasks, many of which can also be activated by
keystrokes. (See Figure 7.)

3. To the left of the Form Area, at the bottom, is the Spec Window. The Spec Window
is where you manage standard operations such as sorting, importing, exporting,
copying, and mass updating records. (See Figure 7.)

38
2 SCREENS & MENU SYSTEM

Figure 7. Partial view of an application in Update mode, showing part of the Form area, the
application Menu Tree (upper left) and the Spec window (lower left).

View options
The size of the Form area, Menu Tree, or Spec Window can be adjusted by clicking and
dragging the separator between the sections. You can also change the size of the
overall Sesame window with standard click and drag actions. This gives you flexibility
in sizing the various components of the Sesame window. The Spec Window can also be
maximized (take up the entire left hand pane) or minimized (closed) by using the Up
and Down arrows on the right-hand side of the Spec Window title bar. Sesame retains
set window sizes for the current session only. The menu tree can also be closed
(hidden) see "Hiding the Menu Tree" below.

Quick Start Menu


Sesame has a Quick Start Menu available for easy access to the most used Sesame
commands on a simple, moveable easy-click menu. The items that appear on the
Quick Start Menu are context sensitive and change as you move around the Sesame
screens. The choices on the menus are self explanatory and are accessed with a
mouse click on the menu choice.

39
2 SCREENS & MENU SYSTEM

Figure 9. Quick Start on Entering Add mode


Figure 8. Quick Start On Open Application

Figure 11. Quick Start in Update Mode


Figure 10. Quick Start at Search

There are various ways to access the Quick Start Menu.

Show Quick Start Menu


Show Quick Start Menu appears on the View pulldown.

Quick Start Menu Bar


Clicking the Menu Bar Quick Start Menu will open or redisplay the Quick Start Menu
window. It is colored red to be very visible until used when it will then revert to the
normal colors of the toolbar. If the Quick Start Menu is hidden behind other windows,
clicking on this menu bar item will redisplay it.

40
2 SCREENS & MENU SYSTEM

Sesame.Ini file
The Quick Start Menu can be made to open on application open by using the
Sesame.ini option:

QUICK START: <ON> | <OFF> | <DISABLED>

This command tells Sesame to open with the quick start menu visible, invisible, or
disabled. If it is disabled, you cannot invoke the menu by any means. If the entry is
not placed in the .ini file, the default is off.

Startup Switches
To open Sesame with the Quick Start Menu active and open use the following startup
switch when running Sesame:

Sesame.exe -quick_start

If an entry is not placed in the .ini file, or the startup switch is not invoked, the default
is off.

Hide Quick Start Menu


This command appears under the View pulldown menu and is available if the Quick
Start Menu is open. It will hide the Quick Start Menu.

Sesames Menu Tree


Most of the data management commands and functions you will need are available on
the Menu Tree on the left-hand portion of the screen. The tasks are arranged in a tree
structure similar to a standard Explorer window. Items which may be opened further
(expanded) are presented as folders with a plus (open) or minus (close) sign to their
left. Choices that will immediately perform an action have a green circle to their left.

Sesame menus are context sensitive. They will be different depending on the mode of
Sesame you are using.

The complete structure of the Sesame menus, in all modes, can be seen in the
Sesame Menu Structure appendix.

The key to working with Sesames menus is realizing that they are in a separate pane
and that the focus must be on that pane to work with the choices. Focus means being
the active object. When you click on a menu selection or in a layout element on a
form, it is said to have the focus. Focus in the Menu Tree window is attained by a
single mouse click in the pane. Once the menu pane has the focus, a single click on
any item will activate it. Likewise, once in the pane, the arrow keys and the enter key
on the keyboard may also be used to make selections. The selected item is highlighted
for easier navigation.

41
2 SCREENS & MENU SYSTEM

To better inform you where you are in the Sesame windows, whenever you click in the
menu tree area it will change color and show a highlight for the menu item selected.
Clicking away from the menu tree will make the highlight disappear and the menu
color dim back to the non-selected color. The color scheme will depend on your
Windows settings and/or your Sesame .ini file settings.

Single Level Menu Trees


Sesame has the ability to display the menu tree with only one level of commands
showing at a time vs the normal menu with all applicable levels open. See Figure 12
below.

Figure 12. Single Level vs Normal Level Display Menu Tree

Single Level menu trees may make the initial transition for untrained users easier.
Single level menus can be set in two places

Sesame.ini file
To set single level menus use the following line to the Sesame.INI file:

COMMAND TREE MODE: <SINGLE> | <FULL>

Single Menu tree will only show one level of commands at time.
Full Traditional mode wherein multiple levels are displayed at the same time.

42
2 SCREENS & MENU SYSTEM

Startup switch
To set single level menus use the following startup switch when running Sesame:

Sesame.exe -singlelevel

The -singlelevel command line startup switch causes the command tree in Sesame to
default to single level mode.

If you do not make an entry in the Sesame.Ini file or as a command line startup
switch, Full is the default.

Hiding the Menu Tree


The menu commands: View > Close Command Area, and View > Open Command Area
hide, or reveal, the menu tree to the left of the Sesame screen.
The command area can also be closed and opened programmatically. The menu
commands are disabled if SBasic invokes CloseCommandArea, or Sesame is started
with the "-closed" startup switch.

Application Menu
When you open an application in Sesame, you will be at the Sesame application menu
shown in Figure 13.

Figure 13. Main application menu that opens Figure 14. Main application menu with the
when starting a Sesame application. Application Utilities menu expanded.

From that point you will be able to make the choices to perform the following actions...

43
2 SCREENS & MENU SYSTEM

 Add data to any form(s) in any of the databases in the application.

 Search and Update your data in any form(s) in any of the databases in the
application.

 Use any of the application utilities shown in Figure 14.

Search/Update expanded menu


When you select Search/Update for a specific database and form, Sesame displays the
Search menu. (See Figure 15.) Here is where you provide your retrieval conditions for
the records you want to find and work with. Once youve done so, and select any of
the Search Commands or press F10, you will then see the Search/Update menu from
which you can manipulate your retrieved (found) record(s).
Full details of the search commands can be found in the Searching and Sorting section
of this user guide.

The keystroke or key-combination in parentheses next to any menu choice is the


keyboard shortcut for that selection.

Figure 15. The Search menu.

44
2 SCREENS & MENU SYSTEM

Add Data expanded menu


When you select Add Data for a specific database and form, from the main application
menu, Sesame will display the Add Data menu (Figure 16) containing all the options
available when adding new records to the database. Full details of the editing
commands can be found in the Adding and Editing Data section of this user guide.

Figure 16. The Add Data menu.

45
2 SCREENS & MENU SYSTEM

The Spec Window

The Specification or Spec window, which comprises the lower left hand quadrant of the
screen. The eight specs that can be displayed in the spec window are

 sort  export
 import  mass update
 Copy  Table View
 Quick Report  Duplicates
There will be a ninth spec Restrictions if there are any restrictions applied to one
or more layout elements.

The spec window is context-


sensitive. For example, when
the retrieve spec is open but
before a search has been
run, the spec window will
show only the Sort,
Duplicates and Table Specs
as the others are not
applicable. After a search
has been run and you have a
result set, other types of
specs, such as those
mentioned in the table above
can be selected.

The sort spec is not available


in Add data mode. You will
see only a restrict spec if at
least one layout element on
the form has restrictions.
(See Adding Data Entry
Restrictions in Customizing
Forms under the Designing a
Sesame Application section
of this Guide for information
on adding restrictions to
your forms.)
Figure 17. The spec window for the Customers form.

Once you have a result set, you can then select a different spec by using the spec
selector buttons the arrows on either side of the spec action bar, or by right-clicking

46
2 SCREENS & MENU SYSTEM

on the action bar for a list of specs. When viewing a result set following a search, the
sort spec is the default in the spec window.

Using the spec window


The spec window varies to some extent depending on whether it is displaying a sort
spec, a mass update
spec, or another type of
spec. But all the specs
have much in common.

Figure 18 shows the spec


window's components for
a typical sort spec.

The spec window consists


of the list of layout
elements on the form.
Each has a selector to
the left of the layout
element name. You click
on the selector to enable
that layout element. It is
then included in the sort,
mass update, export, or
Figure 18. The spec window components. Sort spec shown. what have you.

When you have multiple elements enabled, you can change the order of them in one
of two ways:

 Using the mouse by clicking on the name of the element and dragging it up
or down the list.

 Using the keyboard by clicking on the element name to select it, then
pressing Shift-Up Arrow or Shift-Down Arrow to change its position in the
stack.
You can only select one element name at a time.

When layout elements are enabled in the spec, they acquire a letter next to them to
show they are enabled. The letter varies depending on the spec.

Usually, you double-click on any enabled element to open up a window or dialog that
controls the operation. This includes the programming window for a mass update, or
the Export dialog for an export. An exception is the restrict spec. It has no selectors
and simply lists the layout elements that have restrictions along what the restrictions
are. This particular spec is for information only, it is not interactive.

47
2 SCREENS & MENU SYSTEM

The Spec Action Bar


The spec action bar serves as the title for
the spec window. It identifies the spec
type along with the form for example:
Sort Main Form or Mass Update Gem
Types. The name of the form is shown
because if the form contains a subform
then you get specs for both forms.

The spec action bar can be used in two


ways. When you left-click on the action bar
Figure 19. Spec Action Bar/dropdown list. you get a menu of five choices:

Run perform the action

Load opens the Spec Manager, for the current spec type (e.g. Sort, Export
etc) with the Load tab active, so you can easily retrieve a saved spec of
that type

Save opens the Spec Manager, for the current spec type (e.g. Sort, Export
etc) with the Save tab active, so you can easily save a spec of that
type.

Set All enables all the layout elements on the form useful for including all
fields in an export, for example

Clear All disables all the layout elements. So, for example, no mass update
programming will be enabled

When you right-click on the


action bar you see a list of all the
available specs.

Click on one to move directly to


that spec (see Figure 21).

This is a convenient alternative


to using the left/right arrows to
cycle through the various spec
types.

Figure 20. Right-click on action bar to see list of specs.

48
2 SCREENS & MENU SYSTEM

Ways of Working with Sesame


As with any program, you have choices in the ways you can use Sesame. You can use
menus, the toolbar, or keyboard shortcuts.
Q&A
Q&A users will find that, wherever possible, commonly-used Q&A
keystrokes are supported in Sesame and are given throughout this document.

Using the Application menu


The Application menu uses a familiar tree-like structure. Branches can be expanded
(opened) by clicking on the "+" or pressing the "+" key on your number keypad.
Branches can be collapsed (closed) by clicking on the "-" or pressing the "-" key on
your number keypad. Pressing the Enter key or clicking with the mouse will toggle a
branch between expanded and collapsed.

If the focus (where the cursor is) is on a form, one mouse click is required to move the
focus to the Application menu. Thereafter, a single click is all that is required to
activate any of the menu choices.

The Application menu is context-sensitive. This means that it changes as you work,
giving you only the relevant options. With no
application open, there is no Application
menu.

When you open a database, you see just the


options to open a form in either Add mode or
Search/Update mode (see Figure 17). For
something that affects the entire application,
choose Application Utilities.

On opening a form, you get many more


options depending on the mode you have
selected. In order to explain the Sesame
screens more fully, the next sections
describe, in detail, the menus and screens
you will use in Update mode. You will use a
similar set of screens in Add Data mode.
These will be covered in detail in the sections
on adding data to your application.
Figure 21. The Opening Application menu

At an empty Search/Update form, before any data is retrieved, you see various search
options.

Then, when you run a search, you see many more options. These choices are
presented as submenus or singular choices:
49
2 SCREENS & MENU SYSTEM

Figure 22 Submenus in Search/Update.

Search/Update Submenus

 Navigation Moving between records and saving data.

 Record Commands Deleting, printing, etc. a single record.

 Edit Commands Undoing, dittoing, and inserting the current date.

 Other Commands Help and Table view.

 Results Commands Performing various actions on the current result set of


retrieved records.

 Switch to an Alternate Form Switches between multiple forms in the same


database and presents the current found set of records.
The commands on each of these sub-menus are described below.

Navigation menu

Navigation Menu
What it Does
Menu Choice (Keystroke)
Advance Record (F10) Saves and moves to next record, if any, or
to a new blank record if there are no further
records.
Previous Record (F9) Saves and moves to previous record (if
any).

50
2 SCREENS & MENU SYSTEM

Navigation Menu
What it Does
Menu Choice (Keystroke)
Main Advance Record (Ctrl-F10) Saves parent and subrecords and goes to
next parent record. (Main/Subforms only
see Working with Subforms section).
Main Previous Record (Ctrl-F9) Saves parent and subrecords and goes to
previous parent record. (Main/Subforms
only see Working with Subforms section.)
Next Matching Record Allows special sub-set searching in a
retrieved record set.
Switch to Add Data Mode (Ctrl-F6) Opens another window in Add Data mode.
Save Record Saves this record, leaves it displayed.
Save Record and Close Form (Shift- Saves record and closes form.
F10)
Close Form Without Saving (Esc) Closes form without saving (warning if
unsaved edits).

Record Commands menu

Record Commands Menu


What it Does
Menu Choice (Keystroke)
Delete Record (F3) Deletes this record (with user confirmation).
Calculate (F8) Recalculates all On-Form-Change programming
for the form and all elements (not On-Form
Entry/Exit, or On-Element-Entry/Exit or any other
event programming).
Remove From Results Removes the current record from the result set.
Does not delete the record.
- PRINTING COMMANDS
Print Form Presents a configuration and printer dialogue box
and prints this record (with user confirmation).
Allows selections for background, no background,
portrait, landscape, current record or all retrieved
records, printing configurations, and use of the
regular printer control dialog for multiple printer
selections.

51
2 SCREENS & MENU SYSTEM

Record Commands Menu


What it Does
Menu Choice (Keystroke)
Print Form to HTMLZZ Prompts for an HTML file name and then saves
the form as an HTML image that opens in your
default browser.
Merge File Print (Current Allows current record to be merged with a
Record) previously created external document.

Edit Commands menu

Edit Commands Menu


What it Does
Menu Choice (Keystroke)
Undo Current Field (Ctrl-F7) Undoes changes to this field since record last
saved.
Undo Current Form (Shift-F7) Undoes changes to this record since last saved.
Ditto Current Field (F5) Copies contents of same field in previous
record.
Ditto Form (Shift-F5) Copies contents of all fields in previous record to
current record.
Copy Form to Buffer (F11) Copies the data from the current record into
Sesame's buffer. If a Copy Spec is current then
(See note below) only selected LE's are copied. Independent of
the Windows clipboard.
Paste Buffer to Form (Shift- Pastes the data from Sesame's buffer into the
F11) current record. If a Copy Spec is current then
only selected LE's are copied. Independent of
the Windows clipboard.
Copy Forms to Buffer (Ctrl-F11) Copies the data from all of the retrieved records
into Sesame's buffer. If a Copy Spec is current
then only selected LE's are copied. Independent
of the Windows clipboard.
Paste Buffer to Forms (Alt-F11) Pastes the data from Sesame's buffer into the
current records. If you move to Add mode, it
will create new records. In Update mode it will
overwrite the found set of records (with user
confirmation). If a Copy Spec is current then
only selected LE's are copied. Independent of
the Windows clipboard.

52
2 SCREENS & MENU SYSTEM

Insert Current Date (Ctrl-F5) Inserts system date in current element.


Insert Current Time (Alt-F5) * Inserts system time in current element.

Note: Further information on copying & pasting forms can be found in the Adding and
Editing Data section of this manual.
Q&A
* Alt-F5 enters a time including seconds. If your time LE is
formatted to display only hours and minutes it will complain that the
time cannot be saved with seconds and will strip them off. This is a
likely situation with translated Q&A databases as Q&A does not store
time with seconds. You will need to change the formatting to one that
accepts seconds if you plan to use the Alt-F5 keyboard shortcut.

Other Commands menu

Other Commands Menu


What it Does
Menu Choice (Keystroke)
Help (F1) Context-Sensitive Help.
Toggle Table View (Shift-F6) Opens current forms in table view
window. Shift-F6 toggles back to Form
view.
Toggle Attachment (Alt-F6) Toggles the current form into a
standalone window. This can be called
from either form or table views. All
keystrokes and functions still work but
the Sesame windows and trees are not
displayed. Alt-F6 or Escape will toggle
back to the Normal Sesame view.

Results Commands menu


When you retrieve a set of records that meet your specifications, Sesame presents
them as a Result Set. You can then perform additional operations on this set of
records as an independent group.

Results Commands Menu


What it Does
Menu Choice
Copy Copies records from an open result set in
another tab to the current result set in the
active tab. Uses current Copy Spec.
Mass Delete Permanently deletes all records in result set.

53
2 SCREENS & MENU SYSTEM

Results Commands Menu


What it Does
Menu Choice
Mass Update Mass Updates, using current Mass Update
Spec, all records in result set.
Export Data Exports, using current Export Spec, all
records in result set.
Import Data Imports into the database, using current
Import Spec, all records from an external
delimited file.
Remove Duplicates from Results Removes (hides) duplicate records in this
result set. Matches fields set in the duplicates
spec window. Does not delete records.
Delete Duplicates Permanently deletes all duplicate records in
this result set based on the fields selected in
the duplicates spec window (with user
confirmation).
Sort by Timestamp Sorts result set by date/time of last change.
Newest changed records shown first.
Sort Re-sorts result set according to the current
sort spec
- PRINTING COMMANDS
Print Forms Presents a configuration and printer dialogue
box and prints all records in the current set
(with user confirmation). Allows selections for
background, no background, portrait,
landscape, current record or all retrieved
records, printing configurations, and use of
the regular printer control dialog for multiple
printer selections.
Merge File Print Allows all records in the current set to be
merged with a previously created external
document.
Reports Lists and Runs selected report against the
current result set, or the retrieve and sort
spec attached to the report design.

Switch to an Alternate Form Switches between multiple forms in the same


database and presents the current found set of records.

54
2 SCREENS & MENU SYSTEM

Function Key Menu


Sesame also gives you the ability to use a pop-up Function Key Menu that provides
easy access to the keystroke combination commands used throughout Sesame on a
simple, moveable easy-click menu. The items that appear on the Function Key Menu
are context sensitive and change as you move around the Sesame screens. The
choices on the menus are self explanatory and are activated with a mouse click on the
menu choice. See Figure 23 below.

The Function Key Menu appears in a separate window that you can move around and
still work in your form. It can be minimized to the Windows toolbar. You can use it as
a combination keystroke tutor or as an actual keystroke executor.

If you have the Function Key Menu active (you have clicked in it and it is the selected
window) your keyboard is not active. Only your mouse will make selections. You must
click back in your form before continuing.

Figure 23. Function Key menu in Update Mode

55
2 SCREENS & MENU SYSTEM

In order to activate the Function Key Menu, use the


"Show Function Key Menu" that appears on the "View"
pulldown.

To close the Function Key Menu you can either use the
"Hide Function Key Menu" choice on the "View" pulldown
or you can click on the Windows close "X" at the upper
right corner of the menu window.

Figure 24. Activating the


Function Key Menu

Window Management

Shift-Enter Toggle
The Sesame screen can be toggled between a maximized window and its normal
(restored) window size by pressing the Shift-Enter key combination. If in Designer the
cursor must not be on a form otherwise the form is edited instead.

Figure 25. Normal Window.

56
2 SCREENS & MENU SYSTEM

Attachment
Pressing Alt-F6 or selecting Other Commands | Toggle Attachment (Alt-F6) from the
command tree causes the form area of the Sesame runtime window to occupy the
entire window. If the form area is already occupying the entire window (detached),
these commands, or escape, will restore the form to its usual position in the right
hand panel. While the form is detached, command tree commands, menubar pulldown
menus, and specs are not available to the user, but they are still available to SBasic
functions and subroutines.

Figure 26. Detached Window. Compare Figure 25.

If you attempt to close the window while the form area is occupying the entire
window, the form is restored to its usual position (attached) instead of closing the
window.

Embedded Dialogs
Starting Sesame with the "-embed_dialogs" startup switch, or with the sesame.ini file
entry: "EMBED DIALOGS: ON", causes Sesame to embed most popup dialog boxes in
the main window's frame, rather than popping up in their own standalone window.

If the original size of the dialog and the size of the Sesame main window differ, some
dialogs will scale to "fill" the entire window area.

57
2 SCREENS & MENU SYSTEM

Others will be embedded in the


upper left portion of the window
depending on whether the
content of the dialog can be
stretched without affecting the
function of the dialog box. If the
dialog itself invokes a second
dialog before the first is
dismissed, it will be layered on
top of the first.

Some dialog boxes or popups


will not embed. These include
alerts, the client file dialog, and
Figure 27. Embedded dialog filling window area.
the printer selection dialog.
Popups that cannot be
embedded will appear in their own standalone window positioned by the desktop's
window manager.

Warning: The window that the dialogs appear in is the main window. Closing the
main window will exit Sesame, even if dialogs are embedded.

The F6 Edit Window


Sesame provides an expanded window that allows you to edit text that is larger than
what you can see in the form's Layout Element. It is invoked by pressing the F6
function key when the cursor is in the field to be viewed or edited. The F6 window
functions as a mini word processor would.

See Figure 28 below.

The F6 window can remain open as you move through the elements on a form and
tries to stay on top of the Sesame form window. It is dynamic - as you move from
element to element the window reflects the data in the selected element. The window
is independent of the form and can be sized and moved like any window. As the
window is resized or the data is changed, horizontal and vertical scroll bars will appear
as necessary.

As the data in the F6 window is changed, the underlying data in the form element
simultaneously reflects the change. The F6 window reflects the data in the form
element when it is opened.

58
2 SCREENS & MENU SYSTEM

Figure 28. The F6 Edit Window.

Edit Window Features


The window provides many features accessible from its toolbar menu or right-click
mouse menu.

On the toolbar editor menu you can close the window (F6). Any changes are saved to
the underlying element on the form.
On the Edit Menu you can Undo, Cut, Copy, Paste, Select All, Delete, and Clear.
On the Format Menu you can select word wrap on or off. The default is On.
On the Search Menu you have the capability to perform find and replace operations.

The F6 window also supports the mouse right-click context menu with the choices to
Undo, Cut, Copy, Paste, Select All, and Clear.

Where applicable, these functions are also supported by standard shortcut keys such
as Ctrl-Z, Ctrl-X, Ctrl-C, Ctrl-V, and Ctrl-A.

59
Section 3
Designing a Sesame Application
Introduction
Sesame Designer is a self-contained application design module linked to the main
Sesame program. You use Designer to create and manage your databases,
design/redesign the forms for use with those databases, add programming, and create
reports in Designers Report Writer.

Designer has its own Preview mode where you can see the results of your design,
programming, and other changes before committing them to an actual Sesame
application.

Note: If you are entirely new to Sesame Designer, we urge you to read the
Sesame Quick-Start Tutorials booklet included in your Sesame documentation
package.

To Start Sesame Designer.

To start Designer do one of the following:

 Double-click on the SDesigner shortcut on your


desktop:
 Use the Start Menu / Program menu to start Sesame Figure 1. Desktop shortcut
for Starting Sesame
Designer.
Designer.

There are two ways of starting Sesame Designer from within Sesame Database
Manager. You can open Designer and redesign the application you are currently
working with by selecting Application Utilities / Redesign Current Application from the
menu tree.

Or you can open Designer and start creating a brand new application by clicking on
the first button on Sesame's toolbar. (See figures 2 and 3 below.) If you run Designer
as a separate standalone application, you can still create a new application or redesign
an existing one.

If you select Redesign Current Application, SDesigner will start and attempt to name
the designer file with the same name as your application except with a DSR extension.
If a current designer file of that name already exists, you will be prompted to
overwrite it or create a new filename.

61
3 DESIGNING A SESAME APPLICATION

Figure 3. Opening Designer to create a new


application

Figure 2. Redesign Current Application

In Designer, you work with a Designer file that has a .DSR filename extension. This
can either be a copy of your existing application or a completely new design. You
create your design or make changes to an existing design, then either reconcile the
changes to an active Sesame application or save the design as a new application. You
can modify an
applications design
while others are using
the live application.
Even major changes
to existing designs,
such as adding and
deleting fields, are
handled by reconcile.

If you selected "New"


from the Sesame
runtime toolbar,
Designer will open
and you will again
select 'New" from the
toolbar. You will be
presented with an
Figure 4. Naming your Designer file: in this example
open file dialog
Stamp_Collection.dsr prompting you to
select or supply a

62
3 DESIGNING A SESAME APPLICATION

Designer (.DSR) filename. This is the file you will work on during your design or
redesign. (See Figure 4.)

Once finished and tested, you will be able to convert the Designer file to an active
application file or reconcile it back to an existing application. This allows you to work
on a copy of your application or design while it is still in use. When redesigning an
existing Sesame application, the DSR file will start out with the complete structure and
data (to facilitate testing your design changes) of the current application. It is
essentially a working copy of your application.

Terminology

Databases & forms


Q&A
If you come from a background in Q&A for DOS, there is a new concept in
Sesame. In Q&A for DOS, the form = the database = the application. A Q&A
"application" is just a loosely integrated collection of individual databases that
interact with each other via XLookup and XPost programming commands,
supplemented, perhaps, with a custom menu system designed to help you
switch between your databases.

A Sesame application is comprised of one or more databases, each containing multiple


forms with alternate views of your data. A Sesame application is comprised of two files
Filename.db. and Filename.dat. The .dat file contains the applications data, and the
.db file contains the rest of the application information.

With this approach:

You don't have to cram all your fields into a single form and make it many
pages long. You can have several smaller forms that are task-related.

If you need to enhance your application with programming, you program the
form, not the database. Each form has its own Program Spec (and Restrict
Spec, and so forth). Figure 5 below shows the relationships between the
various components of a Sesame application.

See Figure 5 below.

63
3 DESIGNING A SESAME APPLICATION

Figure 5. Application design demonstrating use of multiple databases and forms.

Some definitions

DB file extension and DSR file extension


A Sesame application consists of two files. The working application that you use to
enter records, run reports, and work with your data is made up of a .db file and .dat
file pair. The copy of the application that you use in Sesame Designer to make design
changes is made up of a .dsr file and .ddt file pair. You dont directly work with .dat
files, but you do work with .dsr files.

64
3 DESIGNING A SESAME APPLICATION

Database
A Sesame application consists of one or more databases. Basically, a database is all
the records of a particular type and all the forms and reports that show these records.
For example, an Orders database might consist of all the order records, the Orders
form and the Orders By Month report. For a detailed explanation of a databases
structure, see the Advanced Concepts appendix.

Layout
A layout is a form or a report. It defines how you will look at and use the parts of your
information. Since Sesame is form-based, you will create your databases by building
and editing layouts, which are essentially forms.

Layout Element
A layout element is anything you put on a layout or form. A layout element can:

Be purely cosmetic, such as a line or a box.


Display data from your database records.
Display the result of a calculation.

As youll see, Sesame offers a comprehensive selection of layout element types for you
to use when designing your forms and reports.

Field
A field is a component of a database and is where Sesame actually stores your data.

Record
A record is a logical collection of fields. A form displays data from the fields in one
record at a time.

For example, an Orders record may have fields for OrderDate, CustomerName and
ShipToAddress. It is rare in Sesame that you will work with an actual field. Normally,
you will work with layout elements. A layout element that displays the value from a
field is said to be bound to that field. The only time that you need to deal with an
actual field is if you change its data type or its name.

Fields and layout elements

Q&A
When you add a field in Q&A for DOS, you are adding a field to the
database and simultaneously adding a "thing" on the form to display the
contents of that field. This "thing" is called a field in Q&A.

In Sesame Designer, anything you put on a form, be it a text box, a label or a graphic
line, is called a layout element. Layout elements can be text boxes bound to data
fields, placeholders for fixed text (labels, headings, and the like), frames to display
pictures, or devices such as combo boxes to display pick-lists. The layout element

65
3 DESIGNING A SESAME APPLICATION

ordinarily used to display data is called a text box its the type of layout element
you will be using most.

When you add a text box to a form in Sesame Designer, by default you are adding
both a field to the underlying database and a layout element to display the contents of
the field. The layout element is said to be bound to the underlying field. That means
that the two are linked. The element shows the data in that field.

A field can have many layout elements on many forms bound to it. But a layout
element can only be bound to single field.

It is possible to add a layout element and not have it bound to a field. These could be
used for calculated totals, for example. Conversely, you can have fields in your
database that do not currently have any layout elements bound to them.

Summary

An application, which is comprised of two files application.db and application.dat,


can have one or more databases each with one or more forms and subforms. Forms
display groups of data from databases. These groups of data are called records. Forms
and subforms are both comprised of layout elements usually bound to fields, where
the data is stored.

Fields are displayed on forms via the use of layout elements, which can be thought of
as place holders on the form.

A layout element is unique to a specific form and a form is defined by its layout
elements.

A field is not unique to a specific form and the same field can be displayed on different
forms, or multiple times on the same form.

Layout elements are bound to the fields whose information they display.

Ways to Start Designer and Use DSR files


From Sesame, you can start Designer in one of several ways:

Select New Application from the File menu on the menu bar.
Open Designer by clicking on the 'New' icon on the icon bar.
Select Design New Application or Redesign Current Application from an open
applications Application Utilities menu tree.

66
3 DESIGNING A SESAME APPLICATION

Whichever way you choose to start Designer, you can:

Create a new DSR file.


Re-use an existing DSR file.

From Designer, your choices are:

File / New Application.


File / Open Application.

In each of these you can:

Create a new DSR file.


Re-use an Existing DSR file.

Once you have completed your design work using the DSR file, you can:

Save the DSR as a new application (.DB file)


Reconcile to an existing application (.DB file)

The DSR file


A DSR file is a copy of a Sesame application. It contains all the "objects" that a
Sesame application contains, including the data. While working in a DSR file, others
can continue working in the original application. When the DSR and the application are
reconciled, the data in the DSR file is ignored. Only design changes are applied to the
original in-use Sesame application. The current data from the application remains
unaffected. Designer is used to do things as simple as changing the color of a form or
reformatting a field, or as fundamental as adding and deleting fields, or even adding
or deleting databases from the application.

67
3 DESIGNING A SESAME APPLICATION

Creating a New Sesame Application

You can create a new Sesame application in several ways

In Designer
from an ASCII file
from an XML file
by translating a Q&A database

The 'normal' way is to use Sesame Designer, described in detail shortly. Briefly, these
are the other three ways

ASCII Database
The ASCII Database command quickly creates a simple application when provided with
only the data from a previous application or database. This is especially useful when
converting a large set of tables of data from a relational database to Sesame.

This command creates an application by reading in a comma/quote delimited text file


containing the data. If the text file has a header line as the first line, and that header
line starts with an exclamation mark (!), the ASCII Database command will use the
header line to name the new fields and layout elements.

The ASCII Database command is available from Sesame Runtime by selecting File /
ASCII Database from the menubar. After selecting the ASCII Database command, a
file dialog requests the filename of the ASCII file to be converted into an application.
After the application is created, a second file dialog appears requesting the filename of
the application to be saved. The application is saved using the .db and .dat extensions.
After being saved, the application is loaded into Sesame.

Here is a header line and some data lines from exporting the Customers.db sample
application to an ASCII file with the header option turned on, the Delimit All Fields
option turned on and an exclamation mark inserted as the first character on the
header line:

!"KEY","First","MI","Last","Company","Add1","Add2","City","State","ZIP","Phone","Ema
il","Position","Live_Prospect","Date_Entered","Hobbies","Numerical","TimeField","Chec
ked","Currency"
"937","Mary","","Wilman","","Route #16 Box 18","","PARIS","VA","77444",
"","","","P","1999/09/06","GOLF","40.73913000","10:39:00","1","244.4400"
"940","Sara","","Footer","","1611 Diane Circle","","PHOENIXVILLE","PA", "15124","215
766-6300","","","","2003/01/20","FISHING;TENNIS","156.66666700",
"02:58:00","","940.0200"
"943,"Margaret","","Kravitz","","P.O. Box 236","","MALVERN","PA", "19499","215 201-
3117","","","P","1999/03/10","","67.35714300", "11:58:00","1","471.5200"

68
3 DESIGNING A SESAME APPLICATION

"944","Mr Arthur","","Lee","","2161 Love St","","BRYN MAWR","PA","35131","215 612-


1110","","","P","1998/06/07","GOLF","314.66666700","03:08:00","1","1888.0200"

Figure 6. Result of creating an ASCII database.

Notes:
The ASCII Export command in Sesame does not place the exclamation mark ("!") on
the header line. This must be done by hand to remain compatible with other programs
that can use the header line but are not expecting an exclamation mark character.

ASCII Database has no way to determine the data type of the values, so all values
must be quote delimited, including numbers. If using the ASCII Export command in
Sesame, select the Delimit All Fields option.
69
3 DESIGNING A SESAME APPLICATION

ASCII Database creates a text box for each field in the ASCII file. It places each text
box directly below the previous text box. They are all the same size, style, and data
type: Text.

As with ASCII Import, problems may occur if there are characters such as double
quote marks or newlines embedded in the data itself.

XML Database
The XML Database command is closely related to the ASCII Database command in that
it also can create an application from an ASCII file. In this case the ASCII file is not a
comma/quote delimited file, but is instead formatted as legal XML. There are three
ways to create a Sesame XML file: The Export Application to XML command on the
Application Menu, the XML commands that appear in SBasic, and hand editing the XML
file in a text editor.

The XML Database command is available from Sesame Runtime by selecting File / XML
Database from the menubar. After selecting the XML Database command, a file dialog
requests the filename of the XML file to be translated into a Sesame application. Once
the XML file has been loaded and translated, a second file dialog requests the name of
the application files, which are saved as a .db file and a .dat file. The application is
then loaded into Sesame.

If the XML input file was created by the XML Export command, the XML Database
command will create a new application identical to the original. The XML format for a
Sesame application created by a XML export is complete and contains, in a readable
format, all of the information contained in a Sesame application.

XML is a "tagged" format, much like HTML. Being a naturally linked hierarchical
format, XML closely resembles the structure of Sesame's own application format, and
is therefore ideal as a portable standards based ASCII file format for Sesame
applications.

Q&A Translation

For full instructions on preparations beforehand and procedures to translate a Q&A


database to Sesame, see the separate Q&A Translation Guide. The notes below
describe new features in Sesame 2.0.

70
3 DESIGNING A SESAME APPLICATION

Q&A Translation Options


There are a number of options you can set when translating a Q&A database to
Sesame. Most of these options allow you to pick and choose which elements of your
Q&A database are brought forward into the new Sesame application. These options are
available from the dialog box that appears after you select the Q&A database to
translate. For a default translation, click Accept without selecting any options.

 Disable Line Draw Characters:


Translates your Q&A form without any
of the special "line draw" characters.
These are the lines created in Q&A by
selecting Draw from the Options menu
while designing a file. Q&A also uses
the line draw characters internally to
define pages and margins. They are
present even if not visible.

 Force Field Types To Text: Ignores the


Q&A Format Spec and creates all fields
in the new Sesame database as Text.
This can be useful if you have a large
number of records with values that are
not valid for the specified data type. For
example: Non-date values entered into
date fields. If needed, field types can be
changed in SDesigner after the data is
corrected.

 Exclude Data: Translates the database


design, including forms, reports and
specs, but does not translate any data
Figure 7. Q&A Translation Options. records. Translates "design only".

 Exclude Design: Translates the data records, but does not create any forms,
reports or specs. After translation, new Forms can be created in SDesigner to
display the translated data. Since Security is contained in the Design, this
choice will result in a database containing all the data, but without Security.
Therefore, a password is required to translate a secured Q&A database with
this option.

 Exclude Form Programming: Ignores all Q&A Basic programming in the


Program Spec.

 Exclude Data Restrictions: Ignores all Restrictions in the Restrict Spec. As


restrictions in Sesame are much more aggressive than in Q&A and are often
no longer appropriate to current data, it is recommended that data restrictions
be excluded.
71
3 DESIGNING A SESAME APPLICATION

 Monochrome: Ignores Q&A color settings and creates a form with a gray
background and white fields with black labels and text.

 Exclude Retrieve Specs in Reports: Translates reports with attached Sort Spec,
but no attached Retrieve Specs. This allows your Report to work with any
records you retrieve. If you normally answer Yes to "Do you want to make
temporary changes to this report?" then this option should be turned on.

 Verbose Mode: Translation progress report is shown in a scrolling popup


window. Same as using VISUAL LOG: ON in the sesame.ini file.

 Exclude Security: If this option is set, the Translator will request a password
before continuing. If that password is allowed to change security settings in
the Q&A database, the Translator does not translate security settings, Users or
Groups.

Managing Q&A Translation Errors


Some Q&A translation errors, such as illegal field names and incorrectly formatted
data values, are errors the user should be aware of before attempting to use the new
Sesame application. These types of errors cause a warning message to appear
encouraging the user to view the Server Administration Log for details. Click Yes to
view the log. This window is called the Sesame Error Logger. You can filter this
window, e.g. for client warnings, and you can print it, by using the menu commands.

If you choose not to view the log at this point, you can still see the translation errors
at a later time by choosing File / Server Administration.

Improved Q&A Report Translation


The Q&A Report Translator is also able to translate features of columnar reports, such
as summaries, sub-summaries, keyword specifiers, custom headings and specialized
date breaks.

Correction to Run-On Q&A Programming imports


Sesame will interpret "run-on" programming (no spaces left between commands and
field numbers) in Q&A such as If#10="OK" then#20="Passed" and translate the field
name with a space in front of it.

72
3 DESIGNING A SESAME APPLICATION

Creating a new application using Designer

The first step in creating a new application is to start Designer. As detailed in the
previous section, you can do this either from Sesame or by starting a separate
instance of Designer. For now, start Sesame from your desktop icon and then select
File / New Application, or click on the NEW button.

The Designer module opens. Click on the NEW button again. The file Select window
opens. You can do one of two things here select an existing DSR file, or type in the
name of a new one, then click on Accept.

Figure 8. Naming a new application.

You don't need to add the file extension. Sesame will add the .DSR.
The capitalization you use will be maintained.
You can use spaces and long file names.

After you have named your design file, Designers application menu will appear. (See
Figure 9.) This is where you will begin your design work. From this menu you can
choose to work on Forms, Reports, or Manage your database or entire application
design.

73
3 DESIGNING A SESAME APPLICATION

Figure 9. Designer application menu.

Creating a new database and form


Because Sesame is form-based, to start, you need to select the Forms option first.
Until you have created and saved your first form you will not be able to enter any
data. The Reports and Manage a Database options will not perform any actions. Once
the Forms option is selected, it will expand to present the following options:

Add New Database


Design/Redesign a Form

In a new design, until the first form is designed and saved, the Add New Database
option is the only usable selection under Forms. (See Figure 10.)

Figure 10. Designer application menu Add New Database.

74
3 DESIGNING A SESAME APPLICATION

When you are designing a new application or adding a new form to an existing
application, you will be prompted for the name of the form before you begin your
actual design. If the form name you select already exists, Sesame will append a
number ("0", then "1" etc) to the name you select. If you are adding a new database,
both the database and the form will be assigned the name you select. If you are
adding an additional form to an existing database, the database name will not be
affected by your form name.

Figure 11. Type a name for your new form.

Laying out a form


When you design or redesign a form, you will be in a new window with the control
panels showing at the left side and a blank form on the right. (See Figure 12.)

You are working on a new form in your new database where you will add layout
elements and fields for your data. In Designer, you are creating both a database and a
form at the same time.

When you place layout elements on the form, you are creating both fields (storage
locations for data in the database) and layout elements (objects that can display data
from a database field).

75
3 DESIGNING A SESAME APPLICATION

Figure 12. Blank Designer screen for creating a new form.

Moving around the form


You can position the cursor anywhere on the blank form using any or all of these
methods:

Clicking with the mouse


Pressing the tab key
Using the arrow keys (left, right, up, down)
Using the arrow key in conjunction with the Ctrl key for fine movement.

With the cursor in a layout element the tab key moves to the next LE, shift-tab moves
you to the previous LE. You must start in an element to use this feature. The tabbing
feature will move you to a tab page but will not continue tabbing through that page
until you select an element on the tab with your mouse.

76
3 DESIGNING A SESAME APPLICATION

The right arrow key moves the cursor 7 pixels while Ctrl + right arrow key moves the
cursor 1 pixel.

Adding and deleting layout elements


Changing the Basic Form Size
If you need to change the basic size of a form at any time during the design process
click on a blank area of the form and use the Shift-Arrow key combinations to adjust
the size.

Shift-Left Arrow = Narrower


Shift-Right Arrow = Wider
Shift-Up Arrow = Shorter
Shift-Down Arrow = Longer

Types of layout elements


There are two main types of layout elements: static and dynamic. Static elements do
not change as you move through your records. These include Static Text, Line, Box
and Static Picture. Dynamic elements, such as Text Box, Radio Button Group and
Image Field, change their displayed values as you move through records. All dynamic
elements can display either a value from a field or the result of a calculation.

Static Text Elements


"Static text element" is the name used in Sesame for text on your form not linked to
any field or data. These can be headings, instructions to users, or the like.

You can add layout elements by


Using the Layout Element Adder
Typing on the form
Using the Element Example Palette
The Layout Element Example Palette will be discussed at a later point in this manual.

Adding static text

Adding static text by typing on the form


Click the mouse on the form where you want the text to appear. Start typing the text.

Figure 13. Sizing a static text element to display all of the text you type.

Press the Enter key to complete the entry. Do not type a colon anywhere within the
static text (Designer takes that as a signal to create a Text Box layout element). The

77
3 DESIGNING A SESAME APPLICATION

static text appears on the form. If not all of the text appears, click on it again and a
box will appear with a sizing handle in the lower right corner. Drag the handle with
your mouse to make the static placeholder large enough to display your text. (See
Figure 13.)

You can also use the Layout Element Adder to create a static text element. This is
covered later in this manual.

Editing static text


Click within the static text element and move within it using the left and right arrow
keys and home and end keys. Use the Backspace key to delete characters to the left of
the cursor. Do Not Use the Delete Key as it will attempt to delete the element (with
user confirmation). You cannot select text within the static text element while you are
first laying it out on the form. This can be done later using the text editor.

Note: If you delete an element by mistake, click on Undo Last Change in the
Commands control panel.

Deleting static text


Click on the static text element so that it becomes highlighted with a box around it.
Press the Delete key. The element and the text within it are deleted from the form.

Adding Dynamic (Data) Layout Elements


In Sesame data is stored in fields. You don't work with data fields directly. Sesame is
form-based you work with data using forms. Data is shown on forms using Layout
Elements. A layout element is anything you place on a layout (a form or a report). A
layout element can be purely cosmetic, such as a graphic line or a box, it can display
data from your database records, display the result of a calculation, or let you change
information simply by clicking or making a selection from a pick-list. The layout
element type you will spend most of your time working with in Sesame is a Text Box.

Text Boxes
Text boxes are the primary layout elements: they display your data. You can add text
boxes in the same ways as static text. You can either type directly on the form, use
the Layout Element Adder tool, or use the element example palette. The first two
techniques are described below.

Adding Layout Elements by Typing on the Form


You can add elements to a Form layout by typing on the form. The types of element
you can add this way are:

Text box, single-line (and create a new text field)


Text box, Multi-line (and create a new text field)

78
3 DESIGNING A SESAME APPLICATION

Static Text

You can also add these LE types using the Layout Element Adder. All other LE types
can ONLY be added using the Layout Element Adder. If you want to create a text box
to store dates or numbers you must do this using the Layout Element Adder.

Rules for naming Layout Elements


Layout Element (LE) names can be any length, but it is advisable to keep them short.
You can use any capitalization. The advisability of having spaces in LE names is
discussed below. Designer will not allow you to create a layout element with a name
that is a Reserved Word. There are over 200 such words, and they include the names
of programming functions, data types etc. Many of these are obscure but there are
some among them you need to pay special attention to such as "width", "height",
"date" and "time". Additionally LE names cannot be a number, or start with a number.
For a list of the reserved words, see Appendix 3 of the Sesame Programming Guide.

Spaces in Layout Element names


LE names can include spaces, but you may encounter problems if you use a LE name
which includes spaces and a reserved word in programming (either form programming
or mass update programming). Examples of such names are "Date of Birth", "Not
Entered" or "Next Step". Unless you are certain that you will never need to refer to
such an element in programming you should avoid spaces in its name by running the
words together (eg DateOfBirth), or by using an underscore (eg Date_Entered), or
using an alternative name such as DOB. It is also more convenient to work in the
program editor with LE names which are concise and do not have spaces. Many
seasoned database programmers avoid spaces as a matter of course.

This applies to the layout element NAME only. There is no reason why you should not
use a safe LE Name and set the label to whatever you like. The LE label is not referred
to elsewhere and can include any characters or even be blank. If you have differing LE
names and labels then you need to take care that you use the layout NAME in
programming, not the label on the form. When programming you can refer to the
drop-down list in the programming editor, which shows you the LE names.

Adding a text box by typing on the form


Click on the form where you want the left hand end of the text box element to appear
(not the left-hand edge of the elements label). This can be done by clicking with the
mouse, or by clicking once and then using the arrow keys to move around the form.
You can press the Ctrl-Arrow keys to position the cursor with fine control.

Type the label followed by a colon (:) and a new layout element will be placed on the
form. The colon tells Designer to make this a text box type layout element, bound to a
new text type data field, with both a name and label as you typed it. (See Figure 14.)

79
3 DESIGNING A SESAME APPLICATION

Figure 14. Adding a text box layout element by typing a label followed by a colon (:). The actual
element begins, and the label ends, where you initially clicked.

If you type a name that is a reserved


word (see above), Designer will retain
that as the label for the element (and
show it on the form) but will change the
name of the underlying field to one in the
LE sequence (LE0, LE1, LE2 etc) so that it
is both legal and unique. To see this, show
the Property Viewer / Other tab as you
work.

If you want to create a series of layout


elements going down the form, typing a
label plus a colon, then pressing Enter
will take you down the form, placing each
successive element directly below the one
above it. (See Figure 15.)
Figure 15. Adding a vertical series of text
box layout elements by pressing Enter from
Adding a multi-line text box element
each element to position correctly for the by typing on the form
next. Designer provides another shortcut for
creating multi-line text box elements. Just
like typing the label and then a colon to
get a single line text box element, if you type the label followed by a less than sign
(<), you will have created a multi-line text box on the form. Designer makes this a
80
3 DESIGNING A SESAME APPLICATION

multi-line text box layout element, bound to a new text type data field, with both a
name and label as you typed it.

LE Naming Rules
See "Rules for naming Layout Elements" and "Spaces in Layout Element names" on
page 79.

If you type a name that is a reserved word, Designer will retain that as the label for
the element (and show it on the form) but will change the name of the underlying field
to one in the LE sequence (LE0, LE1, LE2 etc) so that it is both legal and unique. To
see this, show the Property Viewer / Other tab as you work.

Adding a layout element with the Layout Element Adder


The Layout Element Adder is found in the Control Panel section of Designer to the left
of the form itself. It is the second panel from the top, directly below the Commands
panel. There are four functional parts to this panel:

Select Element Type


Bind Element To
Label
Add Element to Form

The Layout Element Adder allows you to add any of the available types of layout
elements to your form.

To use the Layout Element Adder,


first position your cursor on the
form where you want the new
element to appear. You can press
the Ctrl-Arrow keys to position the
cursor with fine control.

When added by clicking on the Add


Element To Form button, the new
element will appear on the form at
the current cursor position. If the
cursor is not on the form, the new
element will appear at the extreme
upper-left hand corner and will
have to be dragged (manually
positioned with the mouse or
cursor keys) to a new position in
Figure 16. Layout Element Adder. order to see the label.

81
3 DESIGNING A SESAME APPLICATION

Element Example Palette

The Element Example Palette provides


a functional example of each kind of
Layout Element that can be placed on
a Form. You can try the different kinds
of elements to see which behave the
way you want. When you find one you
like, you can drag it onto your Form
design.

To use the Element Example Palette,


open a Form in Design mode and select
Element Example Palette from the
Commands Control Panel. A popup
window appears showing a working
example of each kind of element. If
you click on any of the examples, the
area around the sample element will
highlight. You can click on and type
into the sample just as you would an
actual element to see how they work.
If you click in the area around the
sample, you will get a element of that
type which you can drag and drop onto
your Form. If you decide you dont
actually want to create an element,
release the new element over the
Canvas or the Element Example Palette
itself. A new element will only be
created if it is dropped onto your Form.

Elements created by dragging from the


Element Example Palette are given a
default name and label. If you enter a
value in the Label box on the Layout
Element Adder Control Panel before
dragging the sample element, Sesame
will use that value as the default.

For element types which can be bound,


such as Text Box, they also create a
new underlying field in the database.
The data type of the new field is based
on the type of the element a text box Figure 17. Element Example palette.

82
3 DESIGNING A SESAME APPLICATION

creates a text field, a check box creates a boolean (yes/no) field, and so on. This
underlying field will also be given the default label name unless a value has been
added to the Layout Element Adder before using the Element Example Palette.

The Element Example Palette is not modal. You can leave it up as you work on your
Form and return to it as you need additional elements. To close the Element Example
Palette window, click the X in the upper right corner.

"Word Processor" Capabilities While Typing On Form


The Sesame Form Designer includes a set of features which work with elements as
though they were lines and words in a word processing document. If focus is on the
Form itself, the keystrokes listed below will operate as described.

Key Behavior
Shift+Enter Inserts a blank "line" on your Form. All elements below the cursor
are moved down to make room. If necessary, the Form itself will
increase in height to accommodate the moved elements.
Shift+Spacebar Inserts a blank "space" on your Form. All elements to the right of
the cursor on the same "line" are moved over to make room. If
necessary, the Form itself will increase in width to accommodate the
moved elements.
Shift+Delete Opposite of Shift+Enter. Deletes a "line" and moves all elements
below the cursor up.
Delete Opposite of Shift+Spacebar. Deletes a "space" and moves all
elements on the same "line" as the cursor to the left.

LE Naming Rules
See "Rules for naming Layout Elements" and "Spaces in Layout Element names" on
page 79.

If you use Layout Element Adder to add an element to a form with a name that is a
reserved word, Designer will retain that as the label for the element (and show it on
the form) but will change the name of the underlying field to one in the LE sequence
(LE0, LE1, LE2 etc) so that it is both legal and unique. To see this, show the Property
Viewer / Other tab as you work.

Types of layout elements that can be added to a form


When you want to add a layout element you first select which type you want from the
Select Element Type list. (See Figure 18.)

The default selection is Text Box, which adds a text box type element to the form.
From this list, you can select any of the other types by highlighting them and releasing
the mouse.

83
3 DESIGNING A SESAME APPLICATION

The different types of layout elements that can be added are:

 Static Text Static. No stored value. A


header or title block on a form.
 Text Box Dynamic. Displays any type of
data or value. This is the default type of
layout element.
 Combo Box Dynamic. Displays a user-
defined set of choices in a drop-down list.
Can also accept manual entry of a value
not on the list.
 List Box Dynamic. Displays a user-
defined set of choices in a scrollable list.
The selected value is highlighted.
 Check Box Dynamic. A box that
displays a check mark to indicate "On" or
"Yes". Check boxes are tri-state. They can
indicate Yes (checked), No (unchecked) or
Undecided (raised appearance).
 Radio Button Group Dynamic. A set of
fixed choices selected by clicking on one of
a set of exclusive choice buttons.
 Command Button Static. A button Figure 18. Layout Element Adders
displayed on a form to act as an on- Select Element Type list
element-entry programming point that will
activate only when clicked on with a mouse. It can be used to perform most any
programming function. Command buttons are now activated only by mouse
click. They can be navigated into with tab or enter keys but neither of those will
activate the on-element-entry programming behind a command button.
 Image Box Dynamic. An image viewer for image files stored outside of the
application file.
 Line Static. Line drawing that displays on each record.
 Box Static. Rectangular box drawn on your form. May have static text inside,
such as a form title.
 Static Picture Static. Displays a fixed image such as a logo.
 Tabbed Pages Static. A multiple page separator allowing data and elements
on a single form to be accessed in separate views by clicking on the tab dividers.
 Subform an element that allows a separate database to be linked and
displayed as a child of the main form. This is another complete form with all of

84
3 DESIGNING A SESAME APPLICATION

the components of the main form. It can display a single record at a time, or
display multiple records in a table-like format.
 Scroll Region a Scroll Region allows you to create an area on your form that
can hold more elements than could normally be displayed in that amount of
screen real estate. It allows you to create an area on the form where you can
scroll to see elements that are not always visible.
 Page Marker Static. Allows the print form command in Sesame to print one
form across multiple pages and allow form scrolling using Page Up / Page Down.
The page marker bisects the form horizontally.
 Text Editor Element Dynamic. similar to a multi-line text element but has
the addition of scrollbars that allow you to easily see all of the data in the
element by scrolling with your mouse.
 Menu Button Dynamic. Like a combo box but you are only allowed to select
values on the list, not type your own.

The different element types


Static text box, Line, Box, and Static Picture are essentially graphical tools you use to
make your form design pleasing. They are used to draw or place the same static
element (a title, a horizontal line, a rectangular box, or a picture) in the same place on
every record. They do not contain any data. They can all be sized, have their formats
and colors changed, and moved.

A Combo Box is a combination text and list box. It presents a pick-list box with
preset values for selection or data that you type during data entry. Once you add a
Combo Box to your form, you right-click on it to create the list of pre-set choices you
want available in the drop down. Each entry is followed by a carriage return. (See
Figure 19 and Figure 21.)

Figure 19. Adding a Combo Box and right clicking to add values.

85
3 DESIGNING A SESAME APPLICATION

A List Box also presents a list of preset values but all choices are displayed at all
times. The selected choice is highlighted. After adding a List Box to the form, you add
the list choices by right-clicking on the element and typing in a list of entries. Each
entry is followed by a carriage return. (See Figures 20 and 21.)
The same 'Edit Choices' box is used to save value lists for Combo Boxes and Menu
Buttons.

Figure 20. Adding a List Box and right clicking to add values.

Figure 21. Editing values for Combo box, List box, Menu button

86
3 DESIGNING A SESAME APPLICATION

A Check Box is an element


that appears as a rectangular
box on your form. (See Figure
22.) It provides three states of
entry. Yes (click to check), No
(click to uncheck), Undecided
(click to raise box). These
states can be used for
searching and retrieving your
records and for quick data
Figure 22. Adding a Check Box. entry. The check box is bound
to a Yes/No (Boolean) field.

A Radio Button Group


allows you to select any one
value from a preset list of
values, by clicking on a
selection button. Adding a
Radio Button Group involves
multiple steps:

1.Adding the group itself to


the form. At this point there
are no check buttons
selected. The group itself Figure 23. Step 1 - Adding a Radio Button Group add
has a label and is bound to the group to the form.
the type of element you will
place as buttons on the
group (text, number, etc.).
(See Figure 23.)

2.Right-Click in the element


after it is on the form and
select Add Radio Button. A
button entitled NewRB0 will
appear (See Figure 24.)
Repeat this step until you
have created as many
buttons as you will need.

3.Label the buttons. This is


the value that is actually Figure 24. Step 2 - Adding a Radio Button to the group on
saved to the database field the form.
for a bound group.

87
3 DESIGNING A SESAME APPLICATION

In the Control Panel section, directly below the Layout Element Adder is the Property
Editor. You use this control to change properties of the layout elements you have
placed on the form. The Property Editor is also used to change the properties of many
other parts of your design. These features will be addressed later. For now, you will
use it to change the labels on your radio buttons. The Property Editor does not display
the current settings of an item. It is only used to change them.

1. In the Property editor, click on the Other tab.


2. Make sure that the Options For dropdown says Selected Elements.
3. Click on the first radio button on your form, making sure that the button is
highlighted.
4. Type a Label for the button and click on the Set Element arrow. (See Figure 25.)
5. If your label is incorrect, click on the radio button again and repeat this step.
6. Repeat the step above for each radio button on your form.

Note that you can


select ALL the
elements within a
radio button group
by right-clicking on
a blank area of the
group and then
clicking on Select All
Radio Buttons.

Figure 25. Step 3 - Labeling the Radio Buttons using Property Editor.

The Text Editor element is similar to a multi-line text element but has the addition of
scrollbars that allow you to easily see all of the data in the element by scrolling with
your mouse. If the text can fit in the available element space, the scrollbars will
disappear. If the text exceeds what can be displayed, the scrollbars automatically
appear. Like a multi-line element you cannot use the Enter key to navigate out of the
element. It just creates another line of data in the text editor element.

The text editor element is directly added to a form design with the Layout Element
Adder.

88
3 DESIGNING A SESAME APPLICATION

The Menu Button layout element is similar to the combo box layout element in that it
provides a menu of choices for you to select from that appear when you press the
menu button with the mouse or the spacebar. Unlike the combo box, it does not
provide a the ability to type in any values not currently included in the dropdown list.
You are limited to the choices provided on the menu. Once a choice has been made,
that choice will appear on the menu button as its title. A separate static text could be
provided in the form design to give a menu button its own (unchanging) label.

Once a menu button is added to the form, you can create the dropdown list for it by
right-clicking on the element and selecting 'Edit Choices'.

Figure 26. Adding choices to Menu Button.

Note: A menu button cannot be left blank and will always have a value. Because of
this, the first choice in the Menu Button list will only appear at the retrieve spec screen
and you will have to select one of the values i.e. the menu button has to be part of
the retrieve. To avoid this, add ".." (two dots) to the top of the list. This will not
appear as an entry but at the retrieve spec will allow the Menu Button to be excluded
from the retrieve (".." means any valid entry).

A Command Button is an
element that will allow you
to run programming or a
macro when it is clicked on
with the mouse or "pressed"
with the spacebar. As
created on the form it will
have no function. It is a
holder for an On-Element-
Entry Programming
statement. (See Figure 27
and the Sesame Figure 27. Adding a Command Button.
Programming Guide.)

89
3 DESIGNING A SESAME APPLICATION

Image labels for Command Buttons


A command button can be given a picture rather than text as a label. These Image
labels can be used by specifying "[image]:" before the path to a supported image file.
So, for example, if you want to display "diamond.jpg" on a command button, you
would set the command button's label to: [image]:Pics/diamond.jpg. Images can be
used on every labeled element type as their label. If the image is not fully contained
within the element, it will overflow. It will not be cropped or resized to accommodate a
smaller space.

Sesame accepts URLs (web addresses) as the path to image files. This facility is in
both image layout elements and layout elements using image labels. In Sesame
runtime, to specify a URL in an image layout element, double click on the image
element. When the image browser dialog appears, type the URL to the image as the
file name. Include the full address "http://www.lantica.com/images/lantica2.jpg". In
Sdesigner, type the full URL in the label of any static image. To use a URL in an image
being used as a label on a layout element, type the following as the layout's label

"[image]:http://www.website.com/ImageName.jpg."

substituting the name of the website and image in the applicable spots. The image will
appear in Sesame runtime after the application file has been saved.

Sesame supports GIF images as one of its accepted image formats. Sesame should be
able to accept and display most GIF formats, including transparency. But Sesame
cannot display animated GIFs with motion, and will only display the first frame of the
animation.

An Image Box is a dynamic element that displays an image specified by the path and
filename stored in the database field. When the record is displayed, Sesame displays
the image in the confines of the image box you create. The image will be scaled to fit
inside the box. (See Figure 28.)

Figure 28. Adding an Image Box.

A Static Picture is an image that always stays the same. It is added to the form
using the Layout Element Adder. From the Select Element Type pulldown menu, select
90
3 DESIGNING A SESAME APPLICATION

"Static Picture". For a Form, fill in the Label text box for the Static Picture with the full
path to that image file. Example:
Label: C:\MyPictures\MyCompanyLogos\logo_12.bmp
For a Report, the image file must exist in the Application Image Path. Fill in the Label
text box with the path to the image file, relative to the Image Path. Example:
Label: MyCompanyLogos\logo_12.bmp
Then press the Add Element to Form button. After the Static Picture has been added,
it can be moved or resized.
Tabbed Pages ("Tabs")
Tabs enable you to place many layout elements on a single form and have access to
them by clicking between tabbed sections rather than having to scroll down a long
page. Creating Tabbed Pages is described in Section 4.

Subforms
A Subform is a form within a form. Subforms are a way to display related records from
a second database on the form of a master database, so that you can see records
from both databases at the same time. A good example of this would be an Invoice
application where each record is the master invoice for a customer and the subform on
the record displays the individual line items for each item purchased on that particular
invoice. For details on subforms, see the Creating Subforms section in this guide, and
also Building an Application with Subforms in the Sesame Tutorials Guide.

Static Scroll Region


A Scroll Region allows you to create an area on your form that can hold more elements
than could normally be displayed in that amount of screen. It allows you to create an
area on the form where you can scroll to see elements that are not always visible.

Figure 29. Adding a Scroll Region.

91
3 DESIGNING A SESAME APPLICATION

As an example, consider you have an intake form where you need to ask the applicant
many questions and record his/her answers. You do not have to see all of the answers
at once, but you do need to be able to review them, include them in reports, calculate
results based on them, etc. what you really need is to see one question and answer at
a time and be able to easily scroll to any other area of the intake interview.

To start making a Scrollable area on your form, first choose Scroll Region from the
Layout Element Adder control panel.

A scroll region is added to your form. Temporarily, make its size large enough to
accommodate all of the elements you will want in the region in your final design (make
sure to enlarge your form with the Shift-Arrow keys to give you enough space for the
scroll region and you elements).

To add elements to your scroll region, they must already exist on the main form or
they need to be added to the main form. Drag some or all of the elements onto the
scroll region.

Using the scroll region's sizing handle in the lower right-hand corner, size the region to
appear as you will want it on you final form. As you change the size of the region to be
less than that of all the elements within the area, horizontal and vertical scroll bars will
appear as necessary. See Figure 30.

Figure 30. Scroll bars appearing as scroll region is sized.

If you later need to add additional elements to the scroll region, you can make sure
that no elements are selected inside the region and then scroll down to the bottom or
out to the right.

92
3 DESIGNING A SESAME APPLICATION

Note: If you have an element, or elements inside the scroll region selected and you
use the horizontal or vertical scroll bars, the selected elements will also be scrolled in
relation to the rest of the scroll region. To avoid this, click outside the scroll region
before moving the contents with the scroll bars.

Then you can use the sizing handle to increase the size of the region to allow you to
add the additional elements. When you are finished, resize the region back to the final
size you want. Don't forget to resize you overall form back down using the Shift and
Arrow keys.

Be aware that in use the region will scroll from the top of the highest LEs text box to
the bottom of the lowest LEs text box not including the labels.

Page Marker
The page marker element allows the print form command in Sesame to print one form
across multiple pages. The page marker bisects the form horizontally.

It appears in SDesigner as a line that is the full width of your form with a diamond on
the left-hand side.

Figure 31. Page Marker as it appears in SDesigner.

You cannot assign a label or a name to this element and it cannot be bound to a data
field. The diamond acts as a handle to allow you to easily select and move the page
marker on your form design. Clicking on the diamond will then allow you to move it
with the mouse or the Ctrl-Arrow keys. The page marker can only be moved vertically.

In Sesame runtime, the page marker appears as a thin, dotted line that is the full
width of your form.

In Sesame, when the form is printed the page marker layout element tells the print
form routine where one printed page stops and the next page begins.

The page marker is also used by form navigation to control the landing point for the
Page Up and Page Down keys when navigating on a form. If you press the Page Down
key Sesame will scroll your form and display it with the next page parker being at the
top of the display window. Pressing the Page Up key, will scroll back to the previous
page marker. You can essentially make your forms into 'multi-page' layouts in this
manner.

Page markers can be set in a blank area of the form or even to bisect other elements.
If a form is printed using page markers bisecting elements, those elements will be
divided between pages. If a form is scrolled using Page Up/Page Down with a page
marker bisecting an element, that element will also be split as you scroll.

93
3 DESIGNING A SESAME APPLICATION

Binding layout elements to database fields


When you add a dynamic element using the Layout Element Adder you have the
option of binding it to a data field. Remember, the field holds the data, the layout
element displays the field data on a form. An unbound dynamic element does not
display data from fields. By default, when you create a new layout element, Designer
also creates a matching data field, of the same name, and attempts to set a default
Bind Element To choice in accordance with the following rules (if you have selected a
valid bound to type of field in a previous LE creation, designer will maintain that
selection. Default rules only apply to the first selection of a new element on a form.):

New Layout Element Type Default Bound To

Static Text Unbound

Text Box New Text Field

Combo Box New Text Field

List Box New Text Field

Check Box New Boolean Field

Radio Button Group New Text Field

Command Button Unbound

Image Box New Image Field

Line Unbound

Box Unbound

Static Picture Unbound

Tabs Unbound

Subform Unbound

You can have multiple forms in a database and may want to display some of the same
data fields on more than one form. Binding is what allows this. Once a data field has
been created, it will appear in the list of binding elements so that you can attach it to
new elements on the same form or on other forms in the same database.

You can also use Bind Element To for determining the data type of the new data field.
That is, you can bind a Text Box to the following:

New Text Field


New Number Field
New Date Field
94
3 DESIGNING A SESAME APPLICATION

New Time Field


New Boolean (Y/N) Field
New Keyword Field
New Image Field
Unbound

Your choice will determine how Sesame handles and formats the data placed in the
fields.
Note: Anything can be typed into a data field, but depending on the type of
field it is, Sesame will attempt to convert it to a proper format, as listed in
each description below, on leaving the field. If it cannot be converted (for
example, "Next Sunday" in a date field) the result will be a blank entry.

Text A place to store anything that can be typed from the keyboard. Numbers (0-
9), alphas (a-z), or symbols (!,@,#,$,%,&,_,-,+,*, etc.) are all acceptable in a text
field.

Number Only numeric characters (0-9) and the +, -, (,) can be typed in these
fields.

Money Only numeric characters (0-9) and the +, -, (,) and currency symbols can
be typed in these fields. Sesame will format the typed values as money based on your
system or custom settings.

Date Only date values will be accepted in these fields. Dates can be entered using
"/", ".", "-", ",", or even spaces as separators. For the current year, you need only
enter the day and the month. Sesame internally stores the dates in the format
yyyy/mm/dd.

Time Stores time of day in HH:MM:SS format. You do not need to type the
seconds. As well as being able to display time in both 12 and 24 hour formats (2:30
PM and 14:30), Sesame 2.0 will now accept entries in military format such as "1430"
and convert the entry to the selected display parameters.

Boolean These fields store Yes/No values. These values can also be entered as
Y/N, 1/0, T/F, Yes/No, True/False, On/Off.

Keyword These fields store more than one entry in a field. These entries are
separate values, separated by semicolons, each of which can be retrieved as if they
were the only value in the field. Keyword fields can also be used to find records with
more than one value in these fields. Keyword fields essentially give you the ability to
store lists of entries in a single data field. A good example of this is a list of hobbies. A
person could have movies, art, and reading as hobbies while another has movies,
skiing, and football. Searching this field for movies would return both peoples records.
See more in the section on Retrieving Records.

95
3 DESIGNING A SESAME APPLICATION

Image A field used to store links to image files and then display that image in a
layout element when the record is retrieved.
The image file must be a jpg, bmp, or png type image. Progressive jpg files are not
supported.

In summary, you can:

Leave a new element unbound.


Bind it to a new data field of a specified type.
Bind it to an existing field.

Designer Layout Tools

Moving Between Elements in Designer


You can use Tab and Shift-Tab to navigate from element to element in Designer,
similar to the way you do in Runtime. If focus is on an element, Tab will move you to
the next element. If focus is on the Form, Tab will move the cursor across the Form
until it intersects an element. At that point, the element will have focus and Tab will
move you to the next element.

This feature moves from element to element in geographic order. It does not use the
Navigation Order settings that apply in Runtime or respect GOTO or ThrowFocus()
commands that may be in your SBasic programming.

Resetting Navigation Order


If you used the Set Navigation Order dialog to change your navigation order, you can
quickly reset your Form back to "natural" navigation order by clicking the Reset button
in that dialog. Natural order is the order in which the elements were originally placed
on the form.

Scoot Mode
When Scoot Mode is enabled, adding elements to your Form or moving elements
causes existing elements to move (scoot) themselves out of the way to make room for
the newly created or repositioned element.

The Scoot options are available from Design Mode by selecting Editing Controls from
the Commands Control Panel.
Scoot Vertically Elements scoot down to make room.
Scoot Horizontally Elements scoot right to make room.
Scoot Margin Minimum number of pixels that must exist between elements before
they scoot to make room.

Default settings for Scoot Mode are controlled by the sesame.ini file.

96
3 DESIGNING A SESAME APPLICATION

Snap To Grid
When Snap To Grid is enabled, a grid appears on your Form which is only visible in
Design Mode. If an element is added or moved, the element adjusts its position so
that its upper left corner "snaps" to the nearest grid intersection.

The Snap To Grid options are available from Design Mode by selecting Editing Controls
from the Commands Control Panel.

Snap To Grid Sets whether Snap To Grid is enabled.


Grid Width Sets the width in pixels of each grid unit.
Grid Height Sets the height in pixels of each grid unit.
Snap All Now Enabling Snap To Grid does not change the positions of existing
elements. Clicking this button causes every element on your Form to snap to the
current grid.

Default settings for Snap To Grid are controlled by the sesame.ini file.

Right Click Menu

Once you place layout elements on your form


you can make adjustments to a single element,
or a group of elements, by selecting them and
right-clicking with your mouse. The right-click
menu has six separate design functions you can
use. These are described below.

Figure 32. SDesigner Right Click Menu

Make Like Me
Designer provides a context
sensitive capability called "Make
Like Me." This is a way of copying
properties from one existing layout
element to one or more other
layout elements.

If you want to actually create a


new layout element which is like
another, then consider using
DUPLICATE ME, which is described
in this section on page 99.

To use Make Like Me, after


Figure 33. Using Make Like Me to transfer
selecting the elements you want to formatting from irst Name element to Company,
change, you right-click and release Add1, Add2, City, and State elements.

97
3 DESIGNING A SESAME APPLICATION

on the master layout element (your template) and you will see a Make Like Me menu
choice. Placing your mouse on the choice will open a submenu with the choices All,
Color, Text, Look. Clicking on one will apply the applicable changes to all selected
elements.

Example: To format Last Name, Address, City elements to be the same as First Name:

1. Select the Last Name, Address and City elements.


2. Right-click on First Name.
3. From the Make Like Me menu, select the attributes you want to copy.

Selecting:
Color Changes Label, Text, and Fill colors to match the master element.
Text Changes Label and Text (data) font face, size, and style.
Look Changes Box style, fill, shape, and label alignment.
Size Changes Width and Height to match the master element.
All Changes all of the above settings.
To recap:

1. Select a layout element (Layout element A) and set its properties until it looks like
you want it to be.
2. Select another layout element or group of layout elements. These are the layout
elements that will be changed to match Layout element A.
3. Right-click on Layout element A. Select from the Make Like Me menu to change
the properties you want to copy. The selected layout elements will be changed to
match Layout element A.

Make Like Me will do its best to figure out what you want, but you will get the best
results with the same type of layout elements (text to text, list box to list box, and so
forth).

Move Up Layer/Move Down Layer


This selection will move an element up or down one layer in the list of selection layers
set in the form design. See the section on Advanced Selection Control Panel and
selection layers.

Relabel an element
This choice allows you to easily change the label of the element that is displayed on
your form. Right-Click on a Layout Element and selecting Relabel to display a query
box with the element's current Label. Change the label as you wish and click on OK.

98
3 DESIGNING A SESAME APPLICATION

Figure 34. Relabel Query Box.

Use as Example
This selection allows you to set a temporary default Layout Element design for use
with any/all additional elements you will add to the form.

Set the properties of a


single element so that it
appears as you want it
on your form. Include
setting the color, text,
look, and size. Right
click on that element
and select Use as
Example.
A new command button
will appear in the Layout
Figure 35. Use as Example Element Adder
command area (see
Figure 35). On the left of that button there will be an indicator showing whether it is
active. Clicking the button toggles whether it is active or not. A tool tip will show what
layout element on the form is being used as the example element.
While the button is active, any element added to the form via the Layout Element
Adder will have the same set of properties as the element you set to be used as
example.

Duplicate Me (copy a layout element)


You can also "copy and paste" layout elements (LE's) on a form in Designer. To do so,
click on the form where you want the new LE, then right-click on the LE you want to
duplicate. From the shortcut menu select "Duplicate Me". The new element appears at
the cursor position, or at the top left of the form if you did not put the cursor on the
form beforehand.

The new layout element is identical to the one duplicated, except for field binding.

99
3 DESIGNING A SESAME APPLICATION

Rather than binding to the same field, the new element will bind to a new field of the
same type. The name of the new field will be the name of the original field, with a
numeric suffix added. The label will be the same as the original.

For example:
LE Name LE Label Bound to Field
Original City City City
First Duplicate City0 City City0
Second Duplicate of original City1 City City1

All the attributes of the original field apart from name, position and programming are
copied. This includes formatting, restrictions, custom help, initial values etc. However,
programming attached to the original element is not copied.

The new field is created in the database on saving the form. A new field is not created
if you delete the duplicated LE before saving the form. A new field is not created if you
bind the duplicated LE to a pre-existing field before saving the form.

If the original element is Unbound, the duplicate will also be created as Unbound.
Duplicating a list box or combo box also duplicates the choices. Duplicating a Radio
Button Group also duplicates the radio buttons in that group. Subforms, Tabs and Tab
Groups cannot be duplicated. Duplicates are not in any way linked to the original
element. You can only duplicate one LE at a time.

If you don't want to create a new layout element, but want to copy the attributes of
one layout element to others, then use MAKE LIKE ME which is described in this
section on page 97.

Duplicate Selected Elements


Duplicate Selected Elements copies Layout Elements from one Form to another
position on that Form, or to a different Form in the same Application. Duplicating
elements works very much as if you had added them manually, one at a time. They
are given unique names based on the original names. They create new fields in the
database with names based on the original field name and of the same data type.

To duplicate a group of elements:


1. Select the elements you want to duplicate.
2. If you want to copy them to the same form, right click where you want to place
them and choose Duplicate Selected from the right-click menu.
3. If you want to copy them to a different Form, open that Form in Design mode.
Right-click on the target form where you want the new elements placed. Choose
Duplicate Selected from the right-click menu.

100
3 DESIGNING A SESAME APPLICATION

Deleting layout elements


To remove a text box, or any other layout element, from a form, simply select it/them
and press the Delete key. You will be asked if you are sure you want to delete the
element. Click on Yes to confirm and finish the delete. This does not delete the
underlying field which stores the data. There might be other forms with layout
elements bound to this field! If the layout element just deleted was the only one
showing that field, then you get the option of deleting the underlying field, with its
data, when you reconcile. Reconciling will be covered later.

Note: If you delete an element by mistake, immediately click on Undo Last


Change in the Commands control panel.

Undo

If you make an error or delete


something by mistake, you can easily
undo your action. Designer has two
types of Undo.

The first is Undo Last Change found


on the Commands Menu which
undoes the last action. For most
users and actions, this will suffice.
You can click repeatedly on this to
'roll back' multiple actions.

Figure 36. Undo Last Change


There is also a complete Change Log
/ Advanced Undo section in the Control Panels which allows you full control over all of
your actions. This will be covered later.

Working with multiple layout elements


Designer offers three ways to select multiple layout elements.

Method 1: Click on an element to select it, then hold down the Shift key and click on
another. The elements don't need to be adjacent to one another. Clicking the label will
not select the element. You must click on the element itself.

Method 2: "Rubber-banding." Use your mouse to draw a rectangle around the form
elements you wish to select. Its called "rubber-banding" because it's like taking a
rubber band, expanding it with both hands and placing it around several objects. You
don't have to completely enclose the layout elements. As long as any part of an

101
3 DESIGNING A SESAME APPLICATION

element is "touched" by the selection rectangle, it will be included in the selection.


(See Figure 37.) You cannot rubber-band elements on a tab page see method 3.

Figure 37. Rubber-banding to select First, MI, Last, & Company.

Selecting Multiple Groups of Elements With Shift-Rubber-band


Just as you can use left-click and drag (rubber-banding) to draw a selection box
around a group of elements, you can use Shift-rubber-band to add a group of
elements to an existing selection. If you already have elements selected, hold down
the Shift key while rubber-banding around the next group of elements to select. When
you release the left mouse button, the elements in your rubber-banded selection will
be added to the already selected elements.

Method 3: To select ALL elements on a


form, or on a tab page, right-click on a
blank area of the form or tab page. Click
on "Select All" on the shortcut menu to
select ALL elements.

Figure 38. Right-click to Select All


Moving layout elements
Designer has a host of tools to help you improve the look of your form. The tools for
moving, resizing and arranging layout elements are particularly comprehensiveand
easy to use.

All the techniques below describe moving just one layout element. However, the same
techniques are equally applicable to working with several layout elements at the same
time.

You can move a layout element in two ways:

102
3 DESIGNING A SESAME APPLICATION

Use the mouse to drag it to a new location on the form once it has been
selected. You have to drag the element a certain amount before it actually
moves. This is to prevent accidental moving of an element when you only
intended to select it.
There are times when you may need more control: here the keyboard
techniques are preferable.

You can use the keyboard. Click on the layout element (to select it) and use
the keyboard to move the field using the following key combinations:

Keystroke Combination Resulting Element Movement

Ctrl + Left Arrow Fine movement to left

Ctrl + Right Arrow Coarse movement to right

Ctrl + Up Arrow Fine movement up

Ctrl + Down Arrow Coarse movement down

As you move the element, either with the mouse or keyboard, the coordinates (X, Y)
of the new position are shown just above it. You are also told where the element is
being positioned - on the form or off the form (on the canvas):

To precisely position an element, use both the


coarse and fine movements: Coarse to move to
the approximate position and then Fine to
precisely position the element.

Fine movement is one pixel. Coarse movement is


dependent on default font sizes and varies from
Figure 39. Moving element -
coordinates shown. system to system. The size of a pixel depends
upon your screen resolution. If your screen is set
to 800x600 then a coarse horizontal movement is approximately 1/80th of the screen
and fine is 1/800th of your screen width.

Resizing layout elements

To Resize a layout element you can use one of two techniques:

Mouse method: When you select an element, it displays a sizing handle at the lower
right. (See Figure 40.) Click on this and the mouse pointer turns into a broad four-
headed arrow. Drag this to resize the element. In addition, the Ctrl and Shift keys will
also help control the movement. Ctrl and mouse changes only the height. Shift and
mouse changes only the width.

103
3 DESIGNING A SESAME APPLICATION

Figure 40. Resizing the State Element using the sizing handle.

Keyboard method: Select the element with the mouse. Use the key combinations to
resize the element as follows:

Shift + Left Arrow make narrower.


Shift + Right Arrow make wider.
Shift + Up Arrow make shorter.
Shift + Down Arrow make taller.

The left and top sides of the layout element stay in place. They are the anchor points
as you perform keyboard resizing.
By selecting multiple elements, you can perform resizing on all selected elements at
the same time.

As you resize the element, either with the mouse


or keyboard, the new dimensions (X, Y) of the
element are shown just above it:
Figure 41. Resizing element
These are the two most common ways to move
- dimensions shown.
and resize layout elements. There are two other
advanced techniques.

You can use the Property Editor / Position tab to move and resize layout elements.
This gives you extremely fine control. This method is described in the section Using
Property Editor to Move, Resize and Space Layout Elements later in this guide. You can
also control the size and position of layout elements with programming statements.
(See the Sesame Programming Guide). With programming, fields can become visible
or invisible, grow or shrink or even move on the form depending on the data.
Resizing the form
To resize the form itself, click on a blank area of the form. Hold down the shift key and
use the arrow keys to change its size. You cannot make the form too small to contain
the layout elements on it. If you find it will not become smaller then it is often because
there is a wide layout element (typically a static text element) which has the same
background color as the form, or you have not removed Q&A drawing characters from
a translated form. (See note below.)

As an alternative to the technique described above, you can use the Property Editor to
set the height and width for the Form.
104
3 DESIGNING A SESAME APPLICATION

Q&A
To remove all the Q&A line draw characters from a translated Q&A
form, right-click on a blank area of the form and select "Delete Q&A
drawing characters".

Figure 42. Right-click on form to delete Q&A line draw

It is recommended that you do this even if there are no Q&A drawing


characters apparent. This is a one-time procedure.

Off the form the "canvas"


Designer has a "holding area" or a place you can put layout elements you don't wish
to place just yet. You can drag LEs to the area off the form, which is called the canvas.

Any layout elements on the canvas will not appear on the form. If you place a text box
on the canvas, then that element will not show in Sesame at all. Not in any list of
fields. But, it is retained in the application, and if put back onto the form in Designer,
it immediately becomes available and an active part of your design.

When you move a layout element off the form you will see the legend "Parenting to
Canvas (Ghosting)". (See Figure 43.)

Figure 43. A layout element moved to the canvas area.

Previewing the application


Designer provides a means to test your
design before you either save it as an
active Sesame application by reconciling
or saving as a new application. This is
the Preview mode.

To use Preview Mode, first click on Save


Layout Design or press ALT-S so that
you are previewing the latest design,
then click on the Preview Application
button on the toolbar:
105

Figure 44. Preview Application button


3 DESIGNING A SESAME APPLICATION

You don't need to close the form design tab to use Preview mode, however you cannot
work in the Design Menu while Preview Mode is open. You can alternatively select
Application Utilities / Preview Application from the menu tree. It is a good idea to use
this feature as you move through your design efforts to check your progress and save
your design in stages.

Preview mode opens the Designer file (.DSR) in Sesame in a separate window. When
in Preview mode, you will see a different window with "Preview Mode" in the window
title bar and an Exit Preview button. (See Figure 45.) While this window is open, the
Designer window is disabled. The Preview mode is for testing only. In Preview you can
do almost of what you can do in Sesame. You can browse; you can add and delete
records; almost all programming will work; you can mass update, import, export, and
so forth.

Preview mode operations are exactly the same as they are in any Sesame application.
For information on specific functions / operations, see the applicable section in this
Users Guide.

Note: The data you are working with in Preview Mode is for testing
purposes only and will be lost if you reconcile the design to an existing
Sesame Application. It is retained if you save the Designer (DSR) file as a
new Application (DB).

Can use X commands in Preview Mode


All programming can be executed in the preview mode of SDesigner including external
lookup commands (X commands and XResultSet commands). Your application
programming can be tested without the need to reconcile or save the design to a
runtime db file. Care should be taken when testing designs that could affect actual
data. If the X command specifies the actual name of a runtime file such as
MyDatabase.DB, changes could be made to that file during testing.

When you are finished working in Preview mode, close the application, click on the Exit
Preview button (See Figure 45.) and you will be back in Designer. Any data you have
added to the database in the DSR file in Preview mode is saved with the DSR file.

106
3 DESIGNING A SESAME APPLICATION

Figure 45. Exiting Designer Preview mode.

To this point we have covered the basic Designer features needed to design a new
application. The following sections cover other features and capabilities of Designer
which you can use during initial design or during redesign of a previously saved
application.

107
3 DESIGNING A SESAME APPLICATION

Saving Your Design as a Sesame Application

In order to use your new design as a completely operational Sesame application, it


must be converted from a Designer DSR file to an application DB file.

The steps to do this are as follows:

1. In Designer, from the Application Menu select Application / Save As New


Application.
2. Type the file name, for example, MyFirst.DB.
3. Click Accept. (See Figure 46.)
4. If the filename already exists you will need to confirm to overwrite the file. Or,
you can save it as any new filename. You do not need to type the .DB file
extension. Designer will add it.

Your new application is created and is ready to be used in Sesame. Any subsequent
changes to this application will not affect your Designer file which is maintained on the
system with its DSR extension.

Figure 46. Saving design as a new Sesame application.

108
3 DESIGNING A SESAME APPLICATION

Changing the Appearance of Forms

Form redesign
If you will be working with a previously saved application, you will need to open it for
Redesign:

1. Open the DSR file in Designer.


2. Select Forms / Redesign/Customize A Form.
3. Select the Database (there may be only one).
4. Select the form (there may be only one).

Figure 47. Opening an application for redesign.

Control Panels
Control Panels, located on the left side of the Designer window (See Figure 48.) give
you the ability to perform many design and control functions.

 In the Control Panels, when you see a dropdown with an arrow like this it
signifies that the action will be immediate on making the selection from the
list.
 A set button like this requires that you click on it to apply any changes
made in its section.

Table 1 (below) lists the available commands and the Control Panels where they can
be found.

109
3 DESIGNING A SESAME APPLICATION

Panel / Function Where


Show Control Panels Selector
Select Panels to Display

Commands Panel
Switch to Design Menu
Close Design Tab
Save Layout Design
Undo Last Change
Program Layout Program Editor
Change Program Execution Order Set Programming Order
Change Navigation Order Set Navigation ('tab') Order
Open Attributes Table
Relink Form
Export Form to XML
Element Example Palette
Editing Controls

Layout Element Adder Panel


Select Element Type
Bind Element To
Label an Element
Use Example Element If selected in Right-Click Element Menu
Add Element to Form

Property Editor Panel


Set Colors for Label, Text, Element, Form Color Tab
Set Label or Text Font, Font Size, Style, Text Tab
Alignment
Set Element Box style, shape, fill and Label Look Tab
alignment
Set Element width, height, position, alignment, Position Tab
spacing, size, and selection layer
Set Display format for data Format Tab
Set Element Label, Name, Bound to, Initial Value, Options for Selected Elements, Other Tab
Read Only, Visibility, Restriction, Tool Tip,
Custom Help, and Template

110
3 DESIGNING A SESAME APPLICATION

Panel / Function Where


Set Current Layout Name and Autocalc Options for Layout, Other
Set Current Database name Options for Database, Other Tab

Property Viewer Panel


View current colors, fonts, sizes and alignments View Settings for Selected Element,
for Elements and Layouts, Color/Text Tab
View Current General information on Database View Settings for Database or Application
and application
View Current alignment, position, size, box type View Settings for Selected Element,
of element, and selection layer Look/Position Tab
View Element Data Display format View Settings for Selected Element, Format
Tab
View Element Current Name, Label, Binding, View Settings for Selected Element, Other
Initial value, Restriction, Read Only, Visibility, Tab
Custom Help, Tool Tip, Entry Template
View Layout colors & font View Settings for Layout, color/text tab
View whether a text element is multi line View Settings for Layout, color/text tab
View Layout Current width and height View Settings for Layout, Look/Position Tab
View Current Form Name, Autocalc, and data View Settings for Layout, Other Tab
formats
View Current Database Name View Settings for Database, Database Tab
View Current Name, Formats, Image Paths for View Settings for Application, Application
Application Tab

Advanced Element Selector


Action Type - New, Add to Existing, or Delete
Selection
Select By - Element, Bound To, Property,
Position, Label
Property Based on selection of Select By above
Criteria based on selection of type of Property
Perform Selected Action Command Bar
Turn Selection Layer on or off
Flatten (permanently remove all prior selection
layer settings)

111
3 DESIGNING A SESAME APPLICATION

Panel / Function Where


Message Log Panel
View Status messages from Designer concerning
progress/ actions

Change Log / Advanced Undo


Advanced Undo (all actions in current session)
Table 1. Control Panel commands.

The Control Panels present numerous tools for


working with your design. They convey
information and allow you to make changes.
There are more panels than can fit on the
screen so there is a vertical scroll bar as well
as the ability to select which panels you want
to be visible (The Show Control Panels drop
down).

Property Editor vs. Property Viewer


Designer displays current settings for an item
(element, layout, database, application) in one
control panel the Property Viewer, and
allows you to change them using another
control panel the Property Editor. Property
Editor values reflect the last set of changes
made so that they can be applied again to
another item. If you want to see the current
settings, you use Property Viewer.

Property Viewer
The Property Viewer displays the current
settings and values of the item of which you
are viewing the settings. Like other control
panels, the Property Viewer has multiple
sections. The first section is the View Settings
For dropdown. Once you have selected an item
in the main Designer screen, you need to tell
the control panel what you want to see the
selected element, the layout, the database, or
Figure 48. Control Panels. the application.

112
3 DESIGNING A SESAME APPLICATION

The next section is the Tab area at the bottom of the panel. This tells Property Viewer
what category of information you want to see about the item you selected in the View
Settings list.

The last section is the actual display window where the values you are interested in
are displayed. (See Figure 49.)

Figure 49. Property Viewer Control Panel section.

View settings for


Selected elements Current settings for the layout element you have selected, or
multiple layout elements if you have selected more than one. For a multiple selection,
Designer shows those settings that are common to all the selected elements. In this
case there is an asterisk (*) next to that setting. If only one element is selected, all
have asterisks as all apply.

Note: Selecting a single element is done by clicking in the element (not the
label) or by moving the cursor with the arrow keys until it is in the element.
Selecting multiple elements was described earlier.

Layout Current settings for the form itself such as color, font, size, name and
position.

Database Current settings for the Database are limited to one its name.
The names of databases are seen under, for example, Add Data in Sesame, and under
Redesign/Customize a Form in Designer.

Application Current settings here are the name of the application which is seen at
the very top of the application menu in Sesame and in Designer, as well as its data
display formats and image path.

113
3 DESIGNING A SESAME APPLICATION

Property Editor

You use the Property Editor to set or change properties of selected items. It is used in
conjunction with the Property Viewer which displays the current settings of the
selected items.

With Property Editor you can


change colors, fonts, etc. for
layout elements, forms,
applications, and databases.

When you set a property for


an item, the value is
retained by the Property
Editor, so you can click on
another element and apply
the same values for that
second element. You can
even set multiple values
(say for width and height
and horizontal position) and
apply them all by clicking on
Apply All Settings an easy
way to achieve consistency.

Note that Property Editor


does not display current
settings. Property Viewer
does that.

Any values displayed in the


Property Editor are not
necessarily the properties
for the selected item. They
can be the default properties Figure 50. Property Editor and Viewer displaying settings for
set in the Property Editor for First Name data element.
that item, or the last
settings used in a prior selected item. They are the properties that will be applied to
one or more elements if you choose to do so. In Figure 50, you can see that the Label
Font is Arial bold 13. Clicking on the drop down in Property Editor, selecting a font,
and releasing the mouse will change the Label Font. That change will be reflected in
Property Viewer. However, in many parts of the Property Editor you will find that
pressing F5, when in a setting box, will load the current value. In addition, pressing F6
will expand your window to make it easier to type long values into dialog boxes.
It is recommended that you use both of these Control Panels together.

114
3 DESIGNING A SESAME APPLICATION

The Property Editor has six tabs. Each one will be covered in turn.

Property Editor - Color tab


This tab allows you to change the color of just about anything on your form. Set a
color by clicking on it.

To change the color of an item on the form:

1. Select the item.


2. In the Set window choose Label, Back/Fill,
or Text.
Label sets the color of the label.
Back/Fill sets the background color
of the selected element.
Text sets the color of text within
the layout element.
3. Click on the color you want the item to be.

To change the color of the form, click on a


blank area of the form, change the Set control
Figure 51. Property Editor: Color tab.
to Back/Fill, then click on the color of your
choice.

Color palettes
Initially the color palette is set to Default with 32 popular colors. You are not limited to
these. Click the Colors dropdown and you see a list of alternative color palettes:

 Fancy gives you a choice of 32


different colors.

 Form shows just those colors that


are already used on this form. At
first the palette of colors might be
limited to two or three. As more
colors are used on a particular
form the palette will become more
populated.

 Custom allows you to create any of


16 million colors using Red, Green,
and Blue slider bars. To apply the
custom color, click on the square
Figure 52. Property Editor Custom Color
Set Color button which also
tool.
previews the color.

115
3 DESIGNING A SESAME APPLICATION

Property Editor - Text tab


You use this tab to set font, size, characteristics, and alignment of labels and text
(data). You can also set whether your data entry should be right or left justified in the
field, and whether it should be displayed as a single or multi-line element. Change any
of these settings by clicking on them in the drop down lists.

Property Editor - Look tab


Sets the shape, style and fill of your
layout elements as well as the position of
their labels. Make a selection, and set it for
the selected item by just selecting it from
the dropdown. The act of selecting also sets
your choice. Note: The three Box settings
work in combination. Changing any one of
them will cause the new box type to be the
combination of all three current settings.

Note: For REPORTS, the Look Tab / Label


Alignment is used to set the alignment of
Figure 53. Property Editor: Look tab. text in layout elements, not the Text tab

Label Alignment Options


An element's label can appear in one of 12
positions around the label (left-top, left-center,
left-bottom, bottom-left, etc.) or centered in
the element (center-center). These positions
can be set in the Property Editor's Look tab for
the element (see figure) by using the
dropdown menu or by clicking on the desired
position on the chart.

Label position can also be set from the


keyboard. If you select an element you can use
the Alt-Right Arrow and Alt-Left Arrow
Figure 54. Setting Label Position
keystroke combinations to cycle the element
with Property Editor.
label through it positions. Alt-Right Arrow
cycles the label positions in an ascending order (01-13) and Alt-Left Arrow in a
descending order (13-01) starting from the current label position.

Property Editor - Position tab


Allows full control over position, relative alignment, and spacing of elements on the
form. Using this tab, you can set an elements Width and Height. You can set the
size of an element in pixels directly (as an alternative to sizing elements using the
mouse or keyboard techniques described earlier in this section).

116
3 DESIGNING A SESAME APPLICATION

To set a value, you type the numerical value, and then click on the Set width or Set
Height arrow to the right of the value. You may also type differential values. If you
want to change the height or width of one or more layout elements, you can type for
example -1 to make it 1 pixel smaller, or +2 into the appropriate box and apply it.
See example in Figure 55.

You can also change X Position and Y


Position. Use these boxes to set the position
on the form (as an alternative to moving
elements using the mouse or keyboard
techniques described earlier in this section).
You specify position in the form of X & Y
coordinates. (0,0) is the Top Left of the form.
The X axis defines horizontal measurements
across the form from left to right starting at
the left edge of the form. The Y axis defines
vertical measurements down the form from
top to bottom starting at the top edge of the
form. You may also type differential values. If
you want to move the X position to the left a
bit, you can type -10 (to the right, +10) into
the X-Position box and apply it. The same
applies for the Y position. You see the result
instantly. Coordinates are measured in pixels.

Property Editor / Position is used to change ..

 Horizontal Alignment of multiple Figure 55. Property Editor: Position tab.


elements relative to each other
 Vertical Alignment of multiple elements relative to each other
 Horizontal spacing between multiple elements
 Vertical spacing between multiple elements
 Relative width/height of multiple elements
These settings allow you to align/arrange multiple layout elements. You must have
more than one element selected for these settings to work.

The Horizontal Alignment choices are:

No change Don't change this setting when "Apply all" is set

Left Align all to left-most selected element

Center Center all selected elements on their "common"


center

117
3 DESIGNING A SESAME APPLICATION

Right Align all to right-most selected element

Center on parent Center element(s) on parent eg. form


element

Vertical Alignment works similarly for lining up fields arranged left to right across
the form.

Horizontal and Vertical Spacing means adjusting the space between layout
elements. Spacing them out, closing them up, or spreading them out evenly by
selecting Equal.

Horizontal Space / More will leave the left-most selected element where it is but
increase the horizontal space between each of the elements to its right, moving them
to the right.

Horizontal Space / Less will leave the left-most selected element where it is but
reduce the horizontal space between each of the elements to its right, moving them to
the left.

Vertical Space / More will leave the top-most selected element where it is but
increase the vertical space between each of the lower elements, moving them down.

Vertical Space / Less will leave the top-most selected element where it is but
decrease the vertical space between each of the lower elements, moving them up
towards the top one.

Size to Match is similar to alignment, but instead of lining up the multiple layout
elements, it makes all the selected layout elements the same size in height or width.

Selection Layer Assignment Allows you to select and set elements into different
selection layers (1 through 5) for ease of design and selection.

Apply all settings


If you set more than one value, for example width 200 and height 18, you can apply
each setting to any element by clicking on its appropriate Set button. If you desire,
you can apply all of the settings made on this tab to all of the selected elements by
clicking on the Apply All Settings button.

The Apply all Settings button is useful for lining up a group of layout elements, all with
the same X position (for a column of layout elements), or all with the same Y position
(for a row of elements on one line). Be aware that using Apply All Settings to both X &
Y positions, to multiple elements, will result in the elements being stacked on top of
one another.

118
3 DESIGNING A SESAME APPLICATION

Property Editor - Format tab


This tab allows you to control how the data is displayed in the various elements of
the form. This controls, for example, what date format you wish to apply to a date
element (1/1/07 or 01 January 2007 or Jan 01, 2007 for example), how you want
numbers expressed (commas, # decimals, negative display, and so forth). Display
formats for elements can be set globally, as a selected group, or individually.

If you simply want to change the formatting for a layout element, jump straight to
Setting formats for a layout element on page 120.

This panel has two basic dropdown lists


Apply Format To and Display Format.
Each of these then expand to allow you
to select multiple choices:

Apply Format To Selected Elements


Layout Defaults
Display Format System Settings
Application Settings
Layout Settings
Custom Format

You use this panel to specify where


Sesame should pick up the format
settings for either selected element(s) or
Figure 56. Property Editor: Format tab. the entire layout (the form you are
working on).

For each of these you can specify that Sesame use:

 Operating system settings (System Settings).


 The application default display settings available to all databases and forms in
the entire application (Application Settings).
 The default display settings available to all Layout Elements on this specific
form (Layout Settings).
 Fully customized settings which you set in this panel (Custom Format).
 Formats are applied and assigned in a cascading order as follows:
 If a Custom format is specified for a particular layout element, it will be
applied.
 If Custom is not set, then Layout Settings formats are applied.
119
3 DESIGNING A SESAME APPLICATION

 If the Layout settings are not specified, then Application Settings are applied.
 If the Application settings are not specified, then your Operating system
defaults are applied.
All but your System Settings can be set within Designer. These, for example, are set in
the control panel Regional Settings in Windows.

Setting formats for a layout element


To set the display format for a specific dynamic element, you first select it on the
form. You can also make multiple selections and apply formatting to all selected
elements at the same time. In the Property Editor / Format tab select:

 Apply Format to: Selected Elements.

 Display Format: Custom Format.


When you do this, an extra set of choices, appropriate for the type of data field
selected, appears. As you click on layout elements of different types you will see the
choices change.

For a selected Text element there is a single dropdown Text Format. Choices are:

The data will be changed to the selected mode after it is entered in the element and
the user exits the element. The data will be displayed, stored, and exported in the
format selected.

For a selected Date element there is a single dropdown Date Format. Choices are:

 System Short Date (as defined up in your operating system, e.g. Windows)
 System Long Date (as defined up in your operating system, e.g. Windows)
 20 Custom formats, some of which are shown in Figure 57.

120
3 DESIGNING A SESAME APPLICATION

Figure 57. Format / Custom / Dates.

For a selected Time element there is a single dropdown Time Format. Choices are:

Figure 58. Format / Custom / Times.

For a selected Boolean (Yes/No) element, including checkboxes, there is a single


dropdown Boolean Format. Choices are:

121
3 DESIGNING A SESAME APPLICATION

Figure 59. Format / Custom / BooleanWhen you select a Number element,


the number of dropdowns increases to four.

These 4 dropdowns are:

 Group Digits (comma separators or not)


 Number of decimal places
 The decimal symbol to be used
 Negative number format: -1.50 or (1.50)

Figure 60. Format / Custom / Number

When you select a Currency element, the number of dropdowns increases to six.

These are the 4 shown above for number


elements, plus:

 Currency symbol (Type a $, or , or


etc, or none if you wish)
 Symbol placement (currency symbol
follows the amount in some countries)

Figure 61. Format / Custom / Currency

122
3 DESIGNING A SESAME APPLICATION

Formatting multiple layout


elements together

If you have multiple layout elements


selected you can format them at the
same time. If the selected elements
are of different types, then the options
shown will be the all that can apply to
the mix of element types. When this is
the case, the tab at the bottom of the
control panel is shown in yellow.
(See Figure 62.)

Figure 62. Mixed element types selected. In this


case Number and Boolean (checkbox). Note the Note: Settings for Number and Money
yellow tab. work together. Changing any one of
them causes Designer to look at all the
current settings to assemble the new display format.

Setting default formats for a layout (form or report)


To set a layout default for any particular type of data element that can be used in your
design, select:

Apply Format to / Layout Defaults


Display Format / Custom Format

Then set your formats as desired. This works essentially the same as setting layout
elements. Make the desired settings in Property Editor / Format / Layout Defaults, and
they will then become the settings for all elements bound to fields of the affected type
(unless a specific element has had individual settings applied. See precedence of
settings in the Format tab section). (See Figure 63.)

123
3 DESIGNING A SESAME APPLICATION

Figure 63. Property Editor setting layout defaults.

Setting default formats for an application


To set default display formats for the entire application you must leave the form
design area. This will be covered in the next section.

124
3 DESIGNING A SESAME APPLICATION

Property Editor - Other Tab


The Property Editor / Other tab is frequently used.
It is used to define characteristics of the layout elements such as Element Label,
Name, Bound to, Initial Value, Read Only,
Visibility, Restriction, Tool Tip, Custom Help
and template. You can also Name/Rename
your database and layout (form or report), as
well as set the autocalc status for the layout.

You begin by selecting whether you want to set


the options for:

Selected Elements
Layout
Database

The dropdown list at the top of the tab is


where you make this choice. (See Figure 64.)

Selected elements
Allows you to change settings, listed above,
for the selected element or multiple selected
elements. In addition, there is a special setting
R for range. Table 3 shows what each setting
Figure 64. Property Editor Other tab
for Selected Elements.
does. They are then described individually.

Setting What it Does


Label Sets the Label for the element (the text that appears beside it). Labels
do not need to be unique.
Name Sets the Name for the element (used for programming. Etc.) Element
names must be unique.
R Sets the Starting Value for a Range of layout element names.
Bound To Specifies which field a layout element is bound to.
Initial Value Sets initial value for this field for new records (this form only).
Read Only Makes this layout element Read-only (this form only).
Visibility Controls whether this layout element is visible (this form only).
Restrictions Sets restrictions for this layout element (this form only).
Tooltip Sets what will appear as a tooltip as you move mouse over element on
form. (Press F6 for expanded working window.)
125
3 DESIGNING A SESAME APPLICATION

Setting What it Does


Custom Sets what will appear when you press F1 for help in this data element
Help on this form. (Press F6 for expanded working window.)
Template Allows Setting a field Template for Data entry.
Table 3. Settings for selected elements and what they do.

Property Editor / "Other" tab settings

Label See "Changing a layout element's label" under Customizing Forms on page
133.

Name See "Renaming a Layout Element" under Customizing Forms on page 134.

"R" See "Renaming a series of layout elements - the "R" setting under Customizing
Forms on page 136.

Bound To See "Binding layout elements to database fields" on page 94.

Initial value An initial value is a text or numeric value that you wish to appear in a
data element, on each new form, without requiring manual data entry. The value can
be anything you can type from the keyboard but cannot include Sesame functions
such as @Number, @Date, @Time, @UserID, or the like. To make Sesame functions
an initial value on a form, you must use the programming capability of Sesame and
assign these functions to a layout element On-Form-Entry. See the Sesame
Programming Guide for more information.

Restrictions Sesame uses restrictions to determine both that something must be


entered in the layout element and what may be entered. A restriction list is very
strong in Sesame. If a layout element has a restriction, Sesame will display a warning
and require confirmation if any value which does not meet the restriction is entered.
This is called an Optional Restriction. If the restriction is preceded by an exclamation
mark (!), it is considered mandatory and Sesame will not accept non-compliant values,
even with confirmation. The restriction is checked when saving the record. Restrictions
are also checked while browsing, not just when adding a new record, so they can also
affect older records if a new restriction is added. If you are going to include
restrictions, and also want the ability to leave the field blank, include a "=" as one part
of the restriction list. Restrictions are entered as individual values separated by
semicolons (;).

Q&A
Restrictions should not be used to create pick-lists. This was actually a
misuse in Q&A. Sesame provides both Userselect/@Userselect and
@PopupMenu or @PopUpChoiceList features to accomplish this. See the
Sesame Programming Guide.

126
3 DESIGNING A SESAME APPLICATION

On this tab, each setting is applied individually by clicking on the Set arrow on the
right side of each property.
Indexed Fields
Q&A
There is no need to create individually specified indexed fields
("Speedy Fields") in Sesame as there is in Q&A. In Sesame, fields are
indexed as needed without user intervention.

Property Editor/Other/Options for LAYOUT


Allows you to change settings for the layout (form or report) itself.
You can:

Change the name of the layout.


Change the Autocalc option for the form.

Autocalc is a feature that is provided for


Q&A compatibility. With Autocalc set to
YES, all On-Form-Change programming
is executed whenever any layout
element has its value changed.
With Autocalc set to NO, On-Form-
Change programming is only executed
when the user presses F8 or selects
Record Commands / Calculate.
Figure 65. Property Editor / Other tab /
Options for Layout It is recommended that you leave
Autocalc set to Yes unless you have a
very specific reason for turning it off.

Property Editor/Other/Options for DATABASE


Settings for the database are limited to one, its name. When you first design a new
database, Designer will prompt for a database name. The database names are seen on
the menu trees when you Add Data in Sesame, Redesign/Customize A Form in
Designer, and perform similar actions. You can change the database name in this
control panel. (See Figure 66 below.)

Figure 66. Property Editor / Other tab / Options for Database

127
3 DESIGNING A SESAME APPLICATION

Important Note: Property Editor / Other tab is where you:

Rename a layout element


Rename a layout (form)
Rename a database

You can also rename a layout using Layout Manager.


You can also rename a database using Database Manager.

Selection Layers

Selection layers are used to separate the elements on your Form into distinct groups.
This gives you the ability to tell Sesame that you want to work with only the elements
in one of those groups, and it should temporarily ignore the elements in any other
group.

The Selection Layers menu and the Flatten button in the Advanced Element Selector
work in concert with the Selection Layer menu on the Position tab in the Property
Editor. If you have elements selected and choose a selection layer for them in the
Property Editor, SDesigner puts those elements in the specified selection layer. Up to
five selection layers can be populated with elements. Choosing a selection layer in the
Advanced Element Selector, tells Sesame that you only want to be able to select
elements in that particular layer. This is especially useful with tab pages or boxes,
where elements can be stacked on top of each other, but you want to be able to
rubber-band without selecting the "container" elements. You can put the box or tab
page on one layer and the elements contained by it onto a different selection layer.
Then, if you set the Selection Layer in the Advanced Element Selector to the layer
where you put the individual elements, it will be impossible to accidentally select the
underlying box or tab page.

For example, in the sample Customers database you select Company, Add1, Add2,
and City and place them in layer 2 using the Selection Layer menu on the Position tab
of the Property Editor. Then, if you select layer 1 from the Selection Layer menu on
the Advanced Element Selector, you will see that these elements you placed in layer 2
have been grayed-out to indicate that they are now not selectable. To cause them to
become selectable, you can choose layer 2 or Off from the Selection Layer menu. If
you no longer have any use for layers on any element, you can click the Flatten
button, which will delete all of the layer assignments.

Layer assignments are sustained between sessions and are saved with the application
files. They do not need to be removed to preview or run an application.

128
3 DESIGNING A SESAME APPLICATION

Set Selection Layer


In the Property Editor there is a Selection Layer menu that lets you assign up to five
different layers to the elements on your form. This ability is to allow you easier
management of the elements on your forms. For example, you could set all static
elements to be in one layer, single line text boxes in another, and multi-line elements
in a third. Then, if you wanted to make formatting changes to just the static elements,
you would select their layer and all other elements on the form would be excluded
from any changes you then made. This can also be helpful when you want to put box
or line elements on the form and do not want to select then when you select elements
inside, or adjacent to, them.

Selection layers are set in the Property Editor position tab by first selecting an
element, or group of elements, on your form and then selecting a layer number from
the drop down menu (see Figure 67) for those selected elements. See the section on
Advanced Element Selector for easy ways to make multiple element selections. Any
element not specifically set will have a default selection layer of 1.

Figure 67. Setting Layer Level in Property Editor


Setting the selection layers in the Property Editor will have no effect until you tell
Sesame which selection layer you wish to have active. This is done in the Advanced
Element Selector control panel (below the Property Viewer). In the Advanced Element
Selector panel Selection Layer drop down menu you select the layer you want to work
with. If you wish all selection layers to be active, you select 'off' from this drop down
menu. Selection of the layer or turning layers off requires nothing more than clicking
on the appropriate selection in the menu. See figure below.

129
3 DESIGNING A SESAME APPLICATION

Figure 68. Activating Selection Layer Level

Once you have set elements in a specific layer and turned that layer on, you can either
work with all elements in that layer by selecting them all (one method would be with
Sesame's right-click 'Select All Elements on Form') or with any one or several
elements in that selection by individually selecting the ones you want.

If you wish to change Selection Layer assignments, you can do them individually with
the Selection Layer setting in the Property Editor or you can set all elements on the
form back to level 1 by clicking on the 'Flatten' button in the Advanced Element
Selector panel.

Once selection layers are applied, they will stay with the application. Selection Layers
affect the drawing order of elements in Runtime. Elements on a lower selection layer
draw before elements in a higher selection layer.

130
3 DESIGNING A SESAME APPLICATION

The Advanced Element Selector Control Panel

The Advanced Element Selector control panel lets you select elements based on
characteristics of those elements. This can be very useful when trying to select many
elements that have features in common but may not be near one another, or appear
on tab pages, or have some other geographical impediment.

The Advanced Element Selector control panel appears near the bottom of the control
panel frame, between the Property Viewer and the Message Log.

Examples of using Advanced Element Selector

Figure 69. Selecting all Date elements Figure 70. Deselecting elements over 95 wide.

The Action pulldown determines the action SDesigner should take with the selected
elements. The choices are:

 New Selection: deselects any previously selected elements and creates a new
selection group
 Add To Selection: adds the elements next selected to the existing selection
group
 Remove From Selection: removes the elements next selected from the current
selection group

The Select By and the Criteria pulldowns work together to determine which elements
should be subject to the action determined by the Action pulldown menu. The choices
on the Select By pulldown are:

 Element Type
 Bound To Type

131
3 DESIGNING A SESAME APPLICATION

 Element Name
 Bound To Name
 Property
 Size and Position
The choices for Criteria change based what is selected from the Select By list.

Select By Choice Criteria Options Notes


Element Type List of Sesame Element Select all text boxes or all
types command buttons.
Bound To Type List of Sesame Field types Select all elements bound to
Money fields.
Element Name Text box to enter name to Accepts search criteria. "M.."
match. selects all elements whose
name begins with "M".
Bound To Name Text box to enter name to Accepts search criteria. "/="
match. selects all bound elements. "="
selects all unbound elements.
Property A separate list of Properties Select all read-only elements.
is offered. Criteria offers Select elements that have
choices appropriate to the Restrictions set.
selected Property.
Size and Position Controls appear to specify Select all elements wider than
size and position criteria. 100 pixels. Select all elements
more than 230 pixels from the
top of the form.

Once you specify the selection Criteria, click the Perform Selected Action button to
cause Sesame to examine the elements against the criteria and find the elements that
meet the criteria. Sesame then performs the action selected in the Action menu on
those elements, either creating a new selection group (deselecting the old one),
adding the elements to the current selection group, or removing the elements from
the current selection group.

132
3 DESIGNING A SESAME APPLICATION

Customizing Forms

There are a variety of enhancements you can add to your form designs to make them
easier to use and to simplify data entry. Included in this group are data entry
restrictions that help you control the information added to databases through your
forms. These custom enhancements are all accomplished in Sesame Designer using a
combination of the Property Editor and Property Viewer. None of these changes made
in Designer will be reflected in the actual application until they are reconciled to the
application or saved to a new application and you can always use Designer's
Preview Mode to check your work before reconciling.

This section covers the following form/layout customizing options:

 Customizing layout element labels.


 Setting initial values for layout elements.
 Making the contents of layout elements uneditable from the keyboard.
 Hiding layout elements altogether.
 Restricting the data entered into layout elements.
This chapter does not cover changing Navigation Order, programming forms, or
security. These can all be found in Other Form Customization later in this section.

Changing a layout element's label


A label is what you place next to a layout element to describe it. When you add a new
element to a layout, you give it a name. By default, that name becomes both the
layout element name and its label. But they do not have to be the same. An element
does not have to have a label it can be blank. The label is not used in programming.
There may be times when you want a label to differ from the name of the element it
describes.

You can change an element's label using the Property Editor's Other tab.

1. Select the element with the label you want to change.


2. Open the Other tab on the Property Editor if it isn't already open.
3. In the Label box, type in the new label text.
4. Click on the Set Element Label arrow to apply the change. (See Figure 71 below)

Note: You can use the special keystrokes F5 and F6, or the right-click context
menu, to assist you in the Property Editor. In the above example, placing your
cursor in the Label box and pressing F5 will insert the selected element's current
label. Pressing F6 will open an expanded window where you can more easily edit
the text of a lengthy label. F5 and F6 can be used in any Property Editor box that
requires typing.

133
3 DESIGNING A SESAME APPLICATION

Figure 71. Changing the label for Addr1 element to "Address"

You can also use a picture as the label for an LE. This is particularly suitable for
command buttons. See "Image Labels".

Renaming a Layout Element


When you create a new layout element on a form, by default the name you specify
becomes both the layout element name and its label. But they do not have to be the
same. An element does not have to have a label but it must have a name. The name
is very important as it is used in programming.

To change an element's name:

1. Select the element whose name you want to change.

2. Open the Other tab on the Property Editor if it isn't already open.

3. In the Name box, type in the new name.

4. Click on the Set Element Name arrow to apply the change. (See Figure 72
below)

134
3 DESIGNING A SESAME APPLICATION

Figure 72. Renaming a Layout Element

Note: You can use the special keystrokes F5 and F6, or the right-click context
menu, to assist you in the Property Editor. In the above example, placing your
cursor in the Name box and pressing F5 will insert the selected element's current
name. Pressing F6 will open an expanded window where you can more easily edit
the text of a lengthy LE name. F5 and F6 can be used in any Property Editor box
that requires typing.

Invalid LE names
Designer will not allow you to rename a layout element to one that is a Reserved
Word. There are over 200 such words, and they include the names of programming
functions, data types etc. Most of these are obscure but there are some among them
which you might wish to use such as "width", "height", "date" and "time". Additionally
LE names cannot start with a number. They can include spaces, but you would be wise
to avoid spaces if you intend to use the LE name in programming use an underscore
or run the words together, eg Home_Phone or HomePhone, or end them with a
number such as "Width1".

For a list of the reserved words, see the Appendix in the Sesame Programming Guide.

135
3 DESIGNING A SESAME APPLICATION

Renaming a series of layout elements - the "R" setting


Designer allows you to name multiple elements with a sequential name sequence like
Color 1, Color 2, and Color 3, where the numeric is the last part of the name. This is
the name of the element, the identifier that is used in programming, mass-updates,
reports, and the like. It is not the label, the identifier that appears on the form. In this
case, the label for all three data elements could be "Color." It can be of value to set
your own numerical sequence of names for your later programming. The R setting
allows you to decide where to start the sequential numbering. A "3" would create Color
3, Color 4, and so on. This is only applicable when multiple elements are selected.

To use this feature:

1. Select multiple layout elements


2. Enter the layout element name which is common to all the elements in the
Name box
3. Enter the starting value (numerical) in the R box
4. Click on the Set Element Name button

The elements are numbered in the order in which they appear on the form (top left to
bottom right), not the order in which they were selected.

Setting a layout element's initial value


Initial values are data elements you want filled in automatically in every new record
you add to a database. For example, if most of your clients are from Massachusetts,
you may want the State element pre-filled with "MA". If 90% of your orders are
shipped via UPS Ground, you might want your Ship By text box to contain "UPS
Ground" as its default entry.

To set calculated initial values such as @Date, @Time and @Number in a layout
element, use Designer's Program Editor. (Select Program Layout from the Commands
panel to open the Program Editor).

For example, you might have a DateAdded element on your form that is bound to a
date field in the database. For each new record, you want to auto-fill the element with
the current date. In the Program Editor, you'd select DateAdded from the Element
dropdown, select On Form Entry from the Event dropdown, then type in a program
such as this:

If @Add then DateAdded = @Date

See the Sesame Programming Guide for more information.

Follow these steps to set or change an initial value for a layout element:

136
3 DESIGNING A SESAME APPLICATION

1. Select the pertinent element.


2. Open the Other tab on the Property Editor if it isn't already open.
3. In the Initial Value box, type in the initial value.
4. Click on the Set Initial Value arrow to apply the change.

Pressing F5 with the cursor in the Initial Value box will insert any current initial value.
Pressing F6 will open an editing window.

In addition to setting calculated initial values, programming can also auto-fill fields
based on conditions you specify.

Making a layout element read-only


When an element is read-only, it means that the value in the element can be seen but
not manually changed. You cannot navigate into the element. Data in read-only
elements can be altered only by programming, mass updates or initial values. A read-
only element can be grayed out (so that the value in it is visible but not prominently)
or not grayed out (normal appearance).

Programming can not only read and change the contents of a read-only element, it
can also tell you its current read-only status
and even temporarily change that status.
The SBasic programming function likewise
has three states so you can control whether
the element is grayed out or not. See
@ReadOnly() and ReadOnly() in the
Sesame Programming Guide.

Follow these steps to make an element


read-only:

1. Select the element.


2. Open the Other tab on the Property
Editor if it isn't already open.
3. Click on the arrow to the right of the
Read Only box, highlight Either Yes-
Figure 73. Changing the Read Only Grayed Out or Yes- Not Grayed Out,
property of an element and release the mouse.

To make the element editable once again, change the setting back to No.

137
3 DESIGNING A SESAME APPLICATION

Making a layout element unique


When an element is set to "Unique" Sesame will check as you add new records to
make sure that the value you are placing in that element has not been used in any
previous records. If you enter an invalid (non-unique) value in a new record, Sesame
will pop up a message warning that the value cannot be retained and will clear the
offending value. You set uniqueness by selecting "Unique" from the Property Editor
Read Only drop down (see Figure 73 above).

Making a layout element invisible


In the Property Editor of SDesigner you can set the visibility of any of the elements on
your form. You have five different options you can set:

Yes Always Visible

No Never Visible but still can be programmed and hold data

Only When Printed Element will only appear in printed output but not at any other
time. This could be used to print special messages on the printed output that you do
not want to see all the time.

When Not Printed Element is visible while working in the form but does not print.

Secret This option is only valid for single line text elements. The field will store the
data typed in the element but the element will only display asterisks (*) on the form.
The true data can be used in programming. The true data will be visible when the form
is exported, or when the F6 layout element editor is used, but not when printed.

Secret Input
You can make elements display only asterisks (*) instead of the true data. This
capability is set in the Property Editor Other tab Visible options list (see Figure 75
below). The true data can be used in programming. Records can be retrieved based on
the true data in secret elements but the retrieve
spec will only display asterisks.

Secret Input is not a way of securing data.


Pressing F6 to open the layout element editor, or
exporting the data to a text file will display the
true data in the secret formatted elements.
Secret input is especially useful for unbound
password input boxes whose contents are Figure 74. Secret format in use.
processed then immediately cleared.

Programming can not only read and change the contents of an invisible element, it can
tell also tell you its current visibility status and temporarily change that status. See
@Visibility() and Visibility() in the Sesame Programming Guide.

138
3 DESIGNING A SESAME APPLICATION

Figure 75. Visibility Settings for Elements

Adding data entry restrictions


Circumstances or your company's business rules may require that you restrict data
entry to an acceptable list or range of values. For example, you might want to limit the
amount that can be entered for a single customer support call charge. Or, you might
want to prevent a record from being added to the database unless certain elements
are filled. Restrictions help prevent data entry errors and help ensure that the data
saved to the database meets your requirements.

Sesame's strict data typing is your first line of defense against offbeat data being
added to your databases. If you try to fill a date field with something like "Next
Sunday," Sesame blanks the field. If you try to type "No Charge" or "N/A" into a
money field, you'll get nowhere.

Q&A
Although Q&A has data typing, it does not strictly enforce it. This is why,
in Q&A, you can find text values such as "TBD" or "March 15" (with no year) in
a Shipped Date field. You may never discover that such orders, which were
actually shipped, are not appearing in your Orders Shipped by Date report and
why Q&A doesn't retrieve these records when you run searches on the Shipped
Date field.

Your second line of defense against non-conforming data consists of data restrictions.
These help you standardize your data entry, keep it "honest," make it conform to your
company's business rules.

139
3 DESIGNING A SESAME APPLICATION

Sesames restrictions are rigorously enforced. If you have specified one or more
mandatory restrictions for an element, it means that you can count on seeing one of
your permitted values in any saved record. In a restricted element, leaving the
element empty is not acceptable unless that is one of the allowed restrictions.

When entering data, you can see (but not change) the restrictions that are listed in
the Restrictions window.

Figure 76. The Restrictions window showing the data entry restrictions for various layout
elements. The Auth By restriction is mandatory, indicated by the large red dot next to it.

Q&A
In Q&A, a list of permitted values for a field can be displayed by pressing
Alt-F7. Sesame does not support this. However, you can program a Sesame
form to display a list of values that matches your restrictions in a way that you
can simply click on a selection to place it in the restricted element. See
Programmed Restrictions below.

Follow these steps to specify restrictions for a layout element:

1. Select the element whose values you want to restrict.


2. Open the Other tab on the Property Editor if it isn't already open.
3. Type your restriction or restrictions in the Restriction box. (See the table of
restriction expressions below.) Separate each restriction with a semicolon (;).
Precede your restriction list with an explanation mark (!) to make it mandatory.
4. Click on the Set Restriction arrow to apply the restriction(s)

While in the Restriction box, you can optionally press F5 to insert the current
restriction(s) for the selected element. You can also press F6 to open an expanded
window for typing.

When you save a record in Sesame, the data in the form is checked against your
restrictions. If it does not meet them, Sesame will display either a warning box or an
error box, both of which provide details on the affected elements and their
restrictions:
140
3 DESIGNING A SESAME APPLICATION

In the case of optional restrictions not met, a warning message will prompt you to
confirm: "Do you want to save this record and continue?"
In the case of mandatory restrictions not met, an error message will inform you
that the data "must be corrected before this record may be saved."

Supported restrictions are listed in Table 4.

Expression Meaning Example

X Equal to X Entry must be X

=X Equal to X Entry must be X

/X Not X Must not be X

= Empty Must be left empty

X;Y;Z Or Entry must be X or Y or Z only

>X Greater than X If X is a numeric value such as 20, then value must
be more than 20. If a text value like D, then value
must start with D with at least one more letter, or
start with a letter higher than D.

<X Less than X If X is a numeric value such as 20, then value must
be less than 20. If a text value like D, then value
must start with A, B, or C.

>=X Greater than or If X is a numeric value such as 20, then the value
equal to X must be 20 or more. If a text value like D, then the
element must contain data that starts with D or any
other letter in the alphabet higher than D.

<=X Less than or If X is a numeric value such as 20, then the value
equal to X must be 20 or less. If a text value like D, then the
value must be D or start with A, B, or C.

>X..<Y From greater If X is 20 and Y is 30, then the value must be more
than X to less than 20 and less than 30. If X is C and Y is F, then
than Y the value can be any word beginning with C, D, or
E, but not the letter C or Y alone.

>X..<=Y From greater If X is 20 and Y is 30, then the value must be more
than X to less than 20 and equal to 30 or less. If X is C and Y is F,
than or equal to then the value can be any word beginning with C,
Y D, or E, or the letter Y alone.

141
3 DESIGNING A SESAME APPLICATION

Expression Meaning Example

<X; >=Y Less than X or If X is 20 and Y is 30 then the value must be less
Greater than or than 20 or equal to 30 or more. If X is C and Y is F
equal to Y then the value can be any word starting with A or B
or a word starting with F or a higher letter or the
letter F itself.

? Any single Any character, but only one character.


character

?? Any two Any two characters, but the entry must be two
characters characters.

???R Four characters Must be a four character entry where the last
ending with r character is an R.

S.. Begins with S Any length entry that begins with the letter S.

..R Ends with R Any length entry that ends with the letter R.

S..E Begins with S Any length entry that begins with the letter S and
and ends with E ends with the letter E.

..S.. Contains S Any length entry with letter S anywhere in entry.

..A..B..S.. Contains A, B, Any entry that contains a, b, and s in that order,


and S in that such as "Database."
order

/= Entry requested An entry is requested. If you do not place anything


in the field, Sesame will notify you of the restriction
when you save the record, but will allow you to
continue and save.

! Entry required An entry is required (mandatory) If you leave the


element empty, Sesame will notify you of the
restriction when you attempt to save the record,
and will not let you save until the element contains
data.
Table 4. Sesame data restriction codes and what they do.

Programmed data entry restrictions

For restrictions that cannot be specified using the available restriction options in Table
4 above, you can use programming.

142
3 DESIGNING A SESAME APPLICATION

For example, you might want to require that any follow-up date entered be within 30
days from the current date, or need a restriction placed on element "B" depending on
the contents of element "A". For these kinds of situations where calculations are
required, you can use the NotifyForm() programming command in conjunction with
restriction-oriented programming statements to prevent the record from being saved if
your programmed restrictions for one or more elements aren't met.

In conjunction with restrictions and a read-only element, you can use programming to
display convenient pick-lists populated with acceptable values. For example, if a field
required an entry of S, M, or L (for small, medium, large), you could display a pick-list
containing S, M, and L when the user arrives at the element. The selected item would
be copied into the element. The UserSelect, @UserSelect, @PopUpChoiceList and
@PopupMenu commands are ideal for this.

Another good reason for using programming to enforce restrictions is the


instantaneous feedback it can provide. You can use On Element Exit programming to
check the value in an element as the user moves off of it. If the value isn't within the
range permitted by the programming, you can return the user to the element and
display an instructive message to that effect. The Sesame Programming Guide
contains a wealth of functions and commands, and numerous examples, along these
lines.

Setting an Element to Store Unique Values

Sesame will allow you to make text, number, date, and time fields so that they will
only accept unique values. If unique values is set, Sesame will compare any new value
entered in a record, whether in add or update mode, with the values in that field in all
other records in the database. If the new value has been previously entered in another
record, Sesame will display an appropriate warning and a message similar to:

Warning: Text Field cannot be retained with a non-unique value [value]

When you acknowledge the warning by clicking on the OK in the message box, the
non-unique value will be deleted and the element will be empty. You cannot override
this warning and enter a non-unique value. Note that it is the field value in the
database that is checked and made unique, not just the specific layout element on a
specific form. Once made unique, any element on any form, in that database, that is
bound to the field will inherit the unique value status.

To set an element on a form to only store unique values, you will use Sdesigner's
Property Editor. Select the element, or elements, you want to set as unique. On the
Other tab, for a selected element, drop down the Read Only menu choices and select
Unique.

143
3 DESIGNING A SESAME APPLICATION

Figure 77. Setting a field to only accept unique values

The elements and their bound fields will be set and the Property Viewer will display
"Unique" under the Read Only settings.

If you want to unset the Unique Value setting, set the Read only characteristics of the
element to be Yes or No. An element cannot be set to be Read Only and Unique at the
same time.

Data Entry Templates


A template is a way to aid data entry and improve formatting by designating how the
data should be entered into text fields. Data entry templates allow you to control what
may be entered into any single line text element. The selected entry template will
appear in the element as users input data to inform them of the type of data the
element will accept. The template types are:

@ - Any AlphaNumeric Character (A-Z, a-z, 0-9)


# - Any Numeric Character (0-9)
* - Any Character on the keyboard
> - Stop templating

Any other characters, other than the above four, entered in a template are to be
displayed as entered but not are not editable, when adding or updating a record.

144
3 DESIGNING A SESAME APPLICATION

For Example, an element templated as (###) ###-#### will format a telephone


number field to allow the user to only type up to 10 digits that will appear in the
record as (202) 555-1234. The cursor will skip over the () and -.

Data entered in templated fields will be displayed as templated in both form and table
view. It will also appear in its templated form in reports, printing and exported data
files.

If the Stop Templating symbol (>) is not added at the end of a template, you will
restrict a user to entering only as many characters as you have entered into the
template. If you want to be able to enter other data after the template, end it with the
> as shown in this template:
Phone: (###) ###-#### is for: >
Will create a final data entry that could look like:
Phone: (202) 555-1234 is for: George C
A partially completed field with an entry template will contain the remaining special
template characters. A restriction or SBasic programming can be used to prevent
partial completion.

To create a data entry template for an element, you will use Sdesigner's Property
Editor. Select the element you want to template. On the Other tab, for the selected
element, type in the desired template and click on the Set Entry Template arrow.

Figure 78. Creating a Layout Element Template for Phone Number

145
3 DESIGNING A SESAME APPLICATION

Creating User Help Screens

Sesame has three types of help facilities to assist in all areas of the program: context-
sensitive help, custom help, and custom tool-tips.

Sesames built-in context-sensitive help displays information about the


particular task you are performing. The information displayed pertains to the
area of the program in which you are working. Context-sensitive help displays
when you press the F1 key.

Custom help allows you to define a special user message for any layout
element on any form. When you press F1, Sesame will first display your
custom help message, if any, for the current element. (See Figure 79.) If you
close the custom message screen and press F1 again, Sesames built-in
context-sensitive help will display.

Figure 79. Custom help for Call Date. Displayed by pressing F1.

Close a custom help screen by clicking the "X" (close window button) in the far right
corner of the help windows title bar, or by pressing F1 a second time to bring up
Sesames context-sensitive help screen.

You can resize the custom help screen by dragging its borders, or by using the title
bar buttons to minimize or maximize it.

Note: You can use programming to automatically display an existing custom


help message for any form element. See the @Help function in the Sesame
Programming Guide.

146
3 DESIGNING A SESAME APPLICATION

You can also create a custom tooltip for any element you place on a form.
These display your custom messages in small pop-ups whenever the mouse is
positioned over the element. (See Figure 80.) Tooltips are ideal for brief
messages or instructions.

Figure 80. Custom tooltip for the Salesperson field.

Sesame sizes tooltips to show their entire content. They display automatically as you
hover the mouse over the element to which they are attached, and self-close as you
move the mouse off the element. You have no control over the display of tooltips,
other than mouse movement.

Creating custom help screens


You attach custom help to layout elements on a form during form design or redesign
in the Sesame Designer module. Custom help screens have no effect on any data the
elements contain, and they can be changed or removed without affecting your data.

To create a custom help screen in Designer, open the appropriate form, then use the
Other tab in the Property Editor. Follow these steps to create custom help for a layout
element:

1. Select the layout element for which you want to display a custom help message
when F1 is pressed from that element.
2. In the Property Editor, select the Other tab. Type your help text in the Custom
Help field, then click on the Set Custom Help button. (See Figure 81.)

147
3 DESIGNING A SESAME APPLICATION

Figure 81. Adding a custom help screen for the Call Date element using the Custom Help editor.

3. Repeat steps 1 and 2 to add custom help to other layout elements.

Note: When editing an existing help message, press F5 to display the message
text. If you need a larger editing window, press F6. These options are also
available by right-clicking in the Custom Help entry field. When you are finished,
select Editor / Save and Close from the editors toolbar menu. (See Figure 82.)

4. When finished, save your layout. You can now either Reconcile, or save your
Designer file as a new application. See Saving your Design in the Sesame Designer
section of this Guide.

148
3 DESIGNING A SESAME APPLICATION

Figure 82. Working in the Custom Help Editor.

Creating custom tooltips


Like custom help, you attach tooltips to layout elements on a form during form design
or redesign in the Sesame Designer module. Also like custom help screens, tooltips
have no effect on any data the elements contain, and they can be changed or removed
without affecting your data.

You add tooltips using the Other tab in the Property Editor. With the appropriate form
opened in Designer, follow these steps to add a tooltip:

1. Select the layout element for which you want display a tooltip when the mouse is
hovered over that element.

2. In the Tooltip field on the Other tab of the Property Editor, type the text of the tip
as you want it to appear, then click on the Set Tooltip button.

Note: When you are editing a previously created tooltip press F5 to display the
previous text. If you need a larger editing window, press F6. These options are
also available by right-clicking in the Tooltip entry field. When you are finished,
select Editor / Save and Close from the editors toolbar menu.

3. Repeat steps 1 and 2 to add tooltips to other layout elements.

4. When you have finished, save your layout. You can now either Reconcile, or save
your Designer file as an application.

149
3 DESIGNING A SESAME APPLICATION

Other Form Customization

Other menu items found on the Commands menu (See Figure 83) when you are in the
form design window are:

Program Layout
Change Program Execution Order
Change Navigation Order

Figure 83. Form Design Commands

Program Editor
In Sesame you program a form or a report, not a database. A database can have
many forms and reports, and each has its own Program Spec. So you could have
forms with programming optimized for data entry, and others programmed for
browsing and editing.

In Sesame, programming is accessed on the Commands panel of Designer by selecting


Program Layout.

The Program Editor opens in a separate window.

For all the details concerning programming a form as well as Sesames programming
language and syntax, see the Sesame Programming Guide.

Change Program Execution Order


On the Commands panel of Designer, directly below Program Layout is the selection
Change Program Execution Order. (See Figure 84.) This is where you control in what
order Sesame will execute On-Form-Change programming statements in separate
layout elements. This does NOT control the order of moving around the form see
Navigation Order below.

150
3 DESIGNING A SESAME APPLICATION

For example, suppose you have three lines


that calculate a Line Total on each line based
on what appears in other layout elements on
the line, and then a Form Total based on the
sum of each of the Line Totals and a discount
factor based on the magnitude of the total on
Line three only.

In this case you would want to make sure


that any programming that calculated the
Figure 84. Selecting Change Program Line Totals was finished before the Form Total
Execution Order from the Commands value was calculated.
panel.

Sesame programming is based only on layout


element names. You need a way to tell
Sesame in what order the elements need to
be calculated. If you are careful with your
programming structure and placement, you
may not need to use this feature, but it is
there for you.

Selecting this choice on the menu opens the


Set Programming Order dialog box. Listed in
the dialog box, in their default order, are all of
the elements, including the form itself, in
which you can place On-Form-Change
programming. The order of calculation is from
top-to-bottom. To change the order of
calculation you only need to change the order
of the layout element names in the list.

This can be done by:

Using the arrow keys on the keyboard


to highlight the element name you
want to move.
Holding the Shift key and using the
arrow keys to move the selected
element name to its new desired
position. (See Figure 86.) The
movement of element names up and Figure 85. Set Program Execution Order .
down the list can also be done with
your mouse using a click-and-drag technique.
Click on Apply Changes or Cancel Changes to finish the operation.

151
3 DESIGNING A SESAME APPLICATION

These changes are not incorporated


back into the live Sesame application
until you Save Layout Design / Close
Design Tab and then perform a
Reconciliation.

Figure 86. Set Program Execution Order dialog


Numerical and Checked moved to below Add2.

Change Navigation Order


Navigation Order is the sequence in which the cursor moves between layout elements
when you press the tab key. To set Navigation Order, in Designer select the menu
item Commands / Change Navigation Order. The Set Navigation Order dialog is
displayed.

To change the navigation order (the


sequence of layout elements that the
cursor follows when you press tab),
simply drag the element names up
and down the 'ladder' until it is as you
want it, then click on Apply Changes.
You can still control navigation in
programming by using the
ThrowFocus command if you wish.
Navigation Order is a simpler option.
Note .
Q&A
You should not use the old
Q&A GoTo command, as this
can adversely affect
programming. Use
ThrowFocus instead.

Notes:- Navigation Order

Navigation is set for an Element


Group. This would be the form
itself, and each tab page of a
tab group. Figure 87. Set Navigation Order dialog

152
3 DESIGNING A SESAME APPLICATION

Programming (eg ThrowFocus) takes precedence over navigation order.


Form navigation might be affected by read-only fields.

Resetting Navigation Order


If you used the Set Navigation Order dialog to change your navigation order, you can
quickly reset your Form back to "natural" navigation order by clicking the Reset button
in that dialog.

Directional Navigation
At times you may want to avoid navigating through your forms in the order you set to
move through the elements. Sesame allows you to do this with a feature you establish
in the Sesame.Ini file. The entry in the ini file is "DIRECTIONAL NAVIGATION: [ON |
OFF]". If it is set to on, the Up and Down arrow keys will to move up and down
through your form based on element geography rather than order. The default ini
setting is OFF.

Other Control Panels When Designing A Layout

The Message Log


This is the Control Panel that provides feedback on what you are doing and passes
status messages like "Layout Saved."

Change Log/Advanced Undo


This control panel is not shown by default. To show it, select Change Log/Advanced
Undo in the Show Control Panels List. The log will
appear as the last of the control panels at the
bottom of the left-hand pane.

Designer has two types of Undo. The first is the


standard Undo Last Change found on the
Commands Menu. It undoes the last action. This is
cumulative and will continually, sequentially undo
your actions as long as you keep clicking on it.
Each click undoes one more action. For most
instances, this will suffice. Make a mistake, click
Undo and you are back to the previous position.
Once you save the layout you cannot then undo
actions performed before the save.

Sometimes there will be a need to undo multiple


actions that are not sequential. This is where the
Change Log/Advanced Undo Control Panel comes Figure 88. Control Panels
in. It keeps a Change log and Advanced undo Change Log/Advanced undo.

153
3 DESIGNING A SESAME APPLICATION

window which allows you to review and undo almost every action you took since the
last time you saved your Layout. Undo cannot undo the creation of a new element.
You must use the delete function for this.

As actions occur in Designer, they are recorded and grouped in the Change
Log/Advanced Undo window. Every action, from creating fields to changing labels to
changing colors, is recorded and listed as numbered transactions. Actions which
require more than one change, like moving a field (horizontal and vertical components
are changed) are grouped together in the list as a numbered transaction. Designer
allows you to address the changes as individual items (horizontal or vertical change,
for example) or as complete transaction sets.

1. You review the description of the change(s) and highlight the one to undo by
clicking on it with the mouse. In a grouped transaction, you can click on any one
of the group.

2. Next, you select the type of action you want to perform from the Action drop down
list. Your choices are:

Undo Selected Line.

Undo Selected Transaction (a grouped set indicated by the same


transaction number on the left). For example, selecting a field move
transaction with this action will undo both the horizontal and vertical
components of the move.

Undo From Selected Line to End. This action undoes the selected item and
all line items with a transaction number higher than the selected item (all
items above the selected item in the list).

Consolidate Change Log. Cleans up all items which were previously undone
and regroups / renumbers the remaining items if necessary.

3. The undo action is completed when you click on the Perform Selected Action bar.

Once a change is Undone by clicking on Perform Selected Action, the descriptive lines
in the list will appear with lines drawn through them and the change will be reflected
on the form.

154
3 DESIGNING A SESAME APPLICATION

Form Management features

Switch to Alternate Form


The Switch to an Alternate Form commands on the command trees of both Add and
Update modes allow you to select a different form to view the same record. When
opened, the command presents a list of alternate forms that may be selected. To
qualify as an alternate to the current form, a form must be attached to the same
database. An alternate form may present the same fields as the original form, present
fields that have been omitted from the original form, or present a combination of
unique and shared fields.

When an alternate form is opened, the original form is automatically closed and the
alternate form is automatically opened showing the same record. If there are any
uncommitted changes on the original form, you are warned that the form has been
changed and that proceeding will discard these changes. If you opt to proceed, any
changes that have been made to the original form are discarded when the original
form is closed. Because the original form is closed, no SBasic exit programming is run.
If you are automating the switch to an alternate form, it is important that you commit
any changes to the original form and explicitly run any exit programming before the
switch.

Relink Form
Relinking a form or report causes that layout to get its data from a different database
or from different fields in its current database.

The Relink Form dialog box is invoked by selecting Relink Form from SDesigner's
Commands control panel. The Relink Report command is on the Report Commands
control panel. If the form or report has not been saved, an alert will prompt you to
save your work before continuing.

The Relink dialog box lets you change the data source database for an existing form or
report, or change the data sources for individual elements to other fields within the
same database.

You relink to a different database by selecting that database from the Database menu
at the top of the dialog. Doing so will repopulate the list of fields that appears in the
left hand panel. To relink individual elements, drag the element from the right hand
panel to the left hand panel and line it up with the field name you want that element
to be linked to.

If you change your mind about an individual element, drag that element back to the
right hand panel. If you change your mind about all of the elements you have already
linked, click the Clear button or the Cancel button at the bottom of the dialog box.

See Figure 89 and Figure 90.

155
3 DESIGNING A SESAME APPLICATION

If the element names match the field names, you can click the Match Names button,
and the elements with names matching fields on the left will automatically be moved
to the left hand panel.

Figure 89. Relink dialog - before. Figure 90. Relink dialog - after.

Once you have selected the correct fields for those elements you want to relink,
clicking the Relink button will cause those elements to be bound to the field named
directly to the left of that element. Any elements that remain in the right hand panel,
that are not already linked to the same database, will become unbound elements.

Startup Form
A startup form is presented immediately after Sesame finishes loading the application.
It appears in the same position as the splash screen. Because it is loaded without a
mode, it cannot act as a search form or an add data form, but it will run On Element
Entry SBasic event programming for command buttons on the form. This allows the
startup form to act as an application menu.

A startup form can be specified from the command line using the "-start_form" startup
switch followed by the name of the form. If the form name contains spaces, it must be
delimited with double quotes:

sesame -start_form "Main Form" Customers.db

156
3 DESIGNING A SESAME APPLICATION

A startup form can be specified in the sesame.ini file using the "START FORM:"
command followed by the name of the form. In the sesame.ini file, the form name
should not be delimited with double quotes. Note, if a start form is specified in the
sesame.ini file, that particular .ini file should be limited in use to applications that
contain that form.

A start form can also be set for a specific application in the Application Property
Manager in SDesigner, by selecting the appropriate form from the Startup Form
dropdown.

Figure 91. Setting a Startup Form

157
3 DESIGNING A SESAME APPLICATION

Setting Properties for an Application

The properties for an application are set from the Designer menu tree.

Figure 92. Designer Menu tree Application Property Manager for setting default Application
properties.

If you have any tabs open in design mode, you must first save and close the design
tabs in order to use this feature. These two
actions are both performed from the
Commands menu. Designer will give you
warning messages if you try to proceed to
the Application Property Manager without
first saving and closing your form.
When you save your layout, you will see a
message in the Message Log control panel,
that the save has been completed. You can
also save the layout design by pressing or
press Alt-S.
Figure 93. Designer Commands menu.

Application Property Manager

Once you select Application Property Manager from the Application menu tree (Figure
92), you will be presented with a dialog box as shown in Figure 94.

158
3 DESIGNING A SESAME APPLICATION

Figure 94. Application Property Manager Screen.

This dialog box is "modal" (must be the active window) and must be closed before
returning to Designer proper.

There are six settings that can be changed for your application:

The Application Title. (The name that appears at the top of the menu trees,
not the filename.)
The path to your Image files. "." means in the current directory from which
you run Sesame. Sesame does not store images themselves in image fields.
Instead it stores filenames for images. Image Path allows you to use just the
filename, rather than the whole pathname by telling Sesame where to look for
your image files.
The starting @Number value for automatic numbering using programming.
See the Sesame Programming Guide.
The default display format for each data type stored in the application.
The Startup Form
Program Application.

159
3 DESIGNING A SESAME APPLICATION

Setting values
Using the Application Property Manager involves:

Typing in a new Application Title, if desired.


Typing in a new Image Path, if desired.
Typing a new starting @Number value (your current setting, the highest
number used in the application to date, will be displayed), if desired. Set the
@Number starting value to one less than the next value you want. For
example, if you want the next number returned from @Number to be 100,
then set this property to 99.
Selecting the data type change, and the desired format.
Selecting the applicable startup form (If any)
Applying application-wide programming, if desired.
Reviewing and saving your changes by applying individual formats and then
clicking on Save Changes.

Application Programming is covered in the Sesame Programming Guide.

The data types for which you can set display formats are as follows:

Text
Number
Money
Date
Time
Boolean (Yes/No)

For each data type, you will be given a set of options you can change and individually
apply with the Apply New Format button. You will also see a sample of your data
display format as it was before the change and as it will be after you apply the
change. Setting a default data display format for the application has essentially the
same settings and process as setting data display formats for individual layout
elements.

A default data display format set here takes precedence over your operating system
settings but does not override your layout, or individual layout element settings.

These changes have been made to the DSR file. To apply them to the live database,
either reconcile, or Save the DSR with its data as a new Sesame Application.

160
3 DESIGNING A SESAME APPLICATION

Managing a Database

Designer provides a tool for high level management of your data fields and layouts at
the database level. At this level, you can manage all of your fields or your layouts
attached to a specific database. From the Designer Application menu select Manage a
Database. Select the database you want to work with, then select Manage Fields or
Manage Layouts.

Managing fields
Field Manager is a module within Designer that allows you to make structural changes
to the design. This includes adding,
deleting and renaming databases and
fields, and changing data types (text,
number, etc.). Field Manager works on a
"Transaction" basis. A set of tasks are
prepared and then run as a batch. The
changes are implemented at that time.

Select Manage Fields. A dialog box opens


with the list of all fields and their bound
elements in the database and a series of
dropdown screens for managing them.

The screen is broken into three parts


Fields / Bound Elements, Transaction
Builder, and Transaction Batch
Summary. (See Figure 96.) Figure 95. Designer menu tree Manage a
Database
The process is to build a list of what you
want Designer to do and then process that list. You can perform actions such as:

Adding a new field (to which layout elements can later be bound).
Deleting a field.
Changing a field name.
Changing a field type (for example, from Text to Date.
Renaming the database (The name that appears in the menu trees and is used
by programming).
Deleting the entire database from the application.

The process is similar for all of the above actions:

1. You use the Fields / Bound Elements section on the left to see which forms will be
affected by your changes. You cannot change anything here but you can expand
each field to see what layouts (forms) they are attached to. Remember, a field can
be bound to more than one layout element on more then one form. By clicking on

161
3 DESIGNING A SESAME APPLICATION

the plus(+) to the left of each field, you will be able to see the links for each
field/form/layout element (in this format).

Figure 96. Database Field manager

2. In the Transaction Builder section you:

Select the action you wish to perform from the Action dropdown.
Select the field you want to perform the action on from the Field Name
dropdown.
Set the New Name (type it) or change the Field Type (dropdown).
Click Add Transaction to Batch.

3. Repeat Step 2 until you have completed all of your required actions. They will
appear in the Transaction Batch Summary window and may often provide you with
information as to what a particular transactions effect will be.

4. Click on Run Batch, and then Close.

Your changes will all be incorporated into your design. (See Figure 97.)

These changes have been made to the DSR file. To apply them to the live database,
either reconcile, or Save the DSR with its data as a new Sesame Application.

162
3 DESIGNING A SESAME APPLICATION

Figure 97. Database Field Manager Changing Live_Prospect field from Text to Boolean (Y/N)
data type.

Note: You cannot rename the Application (DB) file within Sesame or Designer. This
you would have to do outside of Sesame, in Windows Explorer for example. Take care
to rename the DB and the DAT file pair (Sesame runtime files) or the DSR and the
DDT file pair (Sesame Designer files) identically.

Managing Layouts
Select Manage Layouts. A new dialog box opens with the list of all layouts and reports
in the database and a set of dropdowns for managing them. The screen is broken into
three parts Layouts, Transaction Builder, and Transaction Batch Summary.

Figure 98. Database Layout Manager.

163
3 DESIGNING A SESAME APPLICATION

The process is to build a list of what you want Designer to do and then process that
list. You can do such actions as:

 Renaming a layout...

 Copying a layout. (Make a similar form or report in your database with the
same programming and layout elements.)..

 Deleting a layout..

The process is similar for all of the above actions:

1. You use the Layouts section on the left to view the current layouts and reports.
You cannot change anything here.

2. In the Transaction Builder section you can:

Select the action you wish to perform from the Action dropdown.
Select the layout you want to perform the action on from the Layout Name
dropdown.
Set the New Name, if appropriate (type it).
Click Add Transaction to Batch.

3. Repeat Step 2 until you have completed all of your required actions. (They will
appear in the Transaction Batch Summary window.)

4. Click on Run Batch, and then Close. Designer will apply all changes. The changes
are not necessarily made in the order in which they appear. Some transactions
may be skipped if overridden by a prior change. For example, it does the deletions
first. (If you had said you wanted to rename a field, and also delete that field, it
will delete it first and ignore the rename action.) If you deleted the whole
database, this would be the only valid action.

If you want to manually prevent any transaction from running, uncheck the checkbox
alongside it in the Transaction Batch Summary.

To cancel all the transactions, click on the Close button at the bottom of the Field
Manager window before running the batch.

Your changes will all be incorporated into your design. (See Figure 99.)

These changes have been made to the DSR file. To apply them to the live database,
either reconcile, or Save the DSR with its data as a new Sesame Application.

164
3 DESIGNING A SESAME APPLICATION

Figure 99. Database Layout Manager Copying form Appointments to New Appointments.

Attribute Table
The Attribute Table presents a "spreadsheet" view of the properties of the Layout
Elements on any one Form. The Attribute Table is accessed by opening the Form in
Design Mode and selecting Open Attributes table in the Commands Control Panel.

The Attribute Table appears in a popup window. The columns can be sorted by clicking
on the column header. The visible rows and columns can be printed by selecting Print
form the File Menu. Note that many of the values shown in this table are for internal
use. Values may also appear in a rawer format than they way they are shown in the
Property Viewer.

Application Documenter

The Application Documenter produces an HTML file (web page) summarizing all the
elements of your design and their properties. This feature is used to quickly produce
an overall view of your application design which can be used for internal
documentation or for reference while doing other tasks that relate or refer to elements
of your application, such as writing an X-Command. The Application Documenter is
available in the Sdesigner module of Sesame.

To run the Application Documenter, select Document Application from the Application
branch of the Designer Menu. A dialog box appears asking you where Sesame should

165
3 DESIGNING A SESAME APPLICATION

save the summary. Enter or select a filename and click Accept to create the
application summary and display it in your browser.

The resulting summary is organized into sections. Each section contains information
about a different portion of your application.
Application Values Shows application settings such as Name, Unique Number,
Image Path and Application Filename.
Start Up Programming and Form Shows startup form and indicates whether this
application has any programming in the On Application Open event.
Global Values Lists Global Values and their current values.
Groups Lists Security Groups, the User IDs in the groups and an indication that
they have passwords.
Databases Lists the databases in your application. Each database shows a list of
the fields in that database including its properties, such as name and data type.
Forms summary Lists the Forms in your application. Each Form shows its name
and the database to which it is bound. To jump directly to the detail section for any
Form, click its name.
Reports summary Lists the Reports in your application. Each Report shows its
name and the database to which it is bound. To jump directly to the detail section
for any Report, click its name.
Forms Detail Detailed documentation for each form including elements, element
properties, programmed events, saved specs, and security settings.
Reports Detail Detailed documentation for each report including sections, section
properties, elements, element properties, programmed events, attached specs, and
security settings.

The summary page defaults to a particular look-and-feel, however all these settings
use CSS (cascading style sheets). If you want to change colors and fonts, you can do
so easily by creating a CSS file and placing it in your current working directory.

1. Run the Application Documenter and create a summary.


2. Use the View Source function of your browser or a text editor to look at the source
of the underlying page.
3. Near the top is a section that begins with <style> and ends with </style>. Copy
everything between those style tags and paste it into Notepad or the text editor of
your choice.
4. Save the file as application_doc.css.

You can now edit the styles in application_doc.css to suit your color and font
preferences. If the Application Documenter finds a file called application_doc.css in the
current working directory, it will use the styles defined in that file.

Other Application Menu Tree Options

Delete All Data Records

166
3 DESIGNING A SESAME APPLICATION

If you want to turn your current Designer files into a new Sesame Application, you will
want to remove all of the records you have used as a test base during Preview of your
design. You must have already saved your layout design and closed the design tab.

Selecting this choice will warn you that you are about to permanently remove all of the
records from all of the databases in the application, and ask if you want to proceed.
The records that will be removed are only those in the DSR or Designer file. No
records in a live Sesame application will be deleted.

Security Manager
See separate section on Securing Your Applications.

Temporarily Disable Security


When working in an application with security, you are prompted for a login each
time you enter Preview Mode so you can Preview your application as different
security settings would cause it to behave. If you want to disable the login prompt
for the current Designer session, you can do so by clicking the Temporarily Disable
Security button on the Application tab of the Security Manager. Click the button
again to re-enable security.

Security is disabled only for the current Designer session. The next time you open
your Application, security will behave normally. This setting does not affect
Runtime, even if you Reconcile with security temporarily disabled. There is no
need to re-enable security before closing the Application.

Global Values List Manager


See the Sesame Programming Guide for a discussion of application Global values. This
menu tree choice allows you see and delete your Global values.

Export Design to XML


Allows you to export your entire design to an XML file. You can then use Sesame's File
/ XML Database to open this as a new application with all of your forms, reports, and
programming with no data.

Merge Application
Allows you to merge other Sesame applications into the current application. The
resulting application will contain all of the databases, forms, programming, and reports
from both applications. This is the way you can combine multiple database translations
into a single Sesame application.

When performing the merge, the application to be merged cannot contain databases,
forms or reports of the same name as those in the current application. If they do,
Sesame will present a warning message that the merge cannot be accomplished.
Change the duplicate names in one of the applications and retry the merge.

167
3 DESIGNING A SESAME APPLICATION

Making Design Changes to a Sesame Application

Working with Designer files


There are two ways to make changes to the design of an existing Sesame application
(.DB) You can either:

Start Designer and open the Designer file you used to create, or last modify,
the application (.DSR the Designer file). When finished re-designing, you
apply the changes back to the application (.DB) by reconciling.
or
From the Sesame menu tree, after opening the application, select Application
Utilities/Redesign Current Application and Sesame will start Designer.

Sesame will create a Designer (.DSR) filename matching your application


(Customer.DB will create a Customer.DSR) if a file of the same name does not exist If
it does, you will be asked if you wish to overwrite it. Answering "No" will cause
Sesame to prompt you for a new designer (DSR) file name. (See Figure 100.)

Figure 100. Creating a new DSR file. Note the source filename of the application is stated.

168
3 DESIGNING A SESAME APPLICATION

You can select the same DSR filename, or create a new one in order to maintain
historic versions. If you use the same name, you are asked to confirm that you want
to replace the DSR file, which you can do by clicking on the Yes button.

Designer opens the specified DSR file in design/edit mode. After making changes, save
the layout design and close the layout design tab.

You can then either:

Save as a new application.


Reconcile to an existing Sesame application (DB).

To save as a new Application, see Saving the Design as a Sesame Application.

Saving Your Design as a Sesame Application

In order to use your new design as a completely operational Sesame application, it


must be converted from a Designer DSR file to an application DB file.

The steps to do this are as follows:


1. In Designer, from the Application Menu select Application / Save As New
Application.
2. Type the file name, for example: MyFirst.DB. (You do not have to supply the DB
extension.)
3. Click Accept.

Figure 101. Saving design as a new Sesame application.


If the filename already exists you will need to confirm to overwrite the file, OR

169
3 DESIGNING A SESAME APPLICATION

save it as any new filename. You do not need to type the .DB file extension. Designer
will add it.

Your new application is created and is ready to be used in Sesame. Any subsequent
changes to this application will not affect your Designer file which is maintained on the
system with its DSR extension.

Reconciling Designer Changes

What is Reconciling?
Reconciliation is the process of applying the design of a DSR (Designer) file to a DB
(application) file. When you reconcile a DSR, you specify to which DB you want it to
apply. It does not need to have the same name. Reconcile abandons the data in the
DSR, and applies all design changes made in the DSR to the DB.

Important Note All users must be out of the application and it must be
closed. Designer requires unrestricted access to the target application in order
to perform a reconcile.

If a field is added to a database in the DSR, it is added to the DB.

If a layout element is added to a form in the DSR, it is added to the DB.

If a form is added to a database in the DSR, it is added to the DB.

If a field's data type is changed in the DSR, it is changed in the DB. (This can
affect current data).

If a database is added to an application in the DSR, it is added to the DB.

If a database is deleted from an application in the DSR, it is deleted from the


DB. (This can affect current data.)

If a field is deleted from a database in the DSR, it is deleted from the DB. (This
can affect current data.)

If a layout element is deleted from a form in the DSR, it is deleted from the
DB. (This can affect current data.)

If a form is deleted from a database in the DSR, it is deleted from the DB.
(This can affect current data.)

Reconcile also applies Application Settings, Security, Global Values.


Reconcile is a very high impact process. The internal structure of the DB and the DSR
are compared and altered until they match. Certain types of changes, such as field

170
3 DESIGNING A SESAME APPLICATION

type, will cause data in existing records to be permanently altered. Certain types of
changes, such as deleting a database will cause existing records to be permanently
deleted. Backup copies of applications should always be made before
reconciling.

Note: Reconciling to the wrong application will overwrite that application with
the design and data characteristics of the DSR.

For example, if you have an application with a database named "Customers,"


and you reconcile a different DSR to it which does not have a "Customers"
database, Sesame will see that the database "Customers" is no longer required
and delete it! You will be warned that there are apparent conflicts but, if
you choose to proceed, Sesame and Designer will allow you to perform these
actions.

Steps to reconcile
First make a backup of the target application!

1. Save your work and close any design tabs that are open.
2. From the Designer Application menu, select Application / Reconcile Existing
Application
3. A select file dialog opens, listing the .DB files. Select the proper application to
reconcile to and click Accept. All users must be out of the application and it must
be closed. Designer requires unrestricted access to the target application in order
to perform a reconcile.
4. The Reconcile Application Options dialog opens. (See Figure 102.)
5. Answer the four questions concerning the options available. These are discussed
below.
6. Click on Reconcile Now. Designer performs the reconcile and leaves you at the
Designer menu.

Reconcile Options
The options when reconciling are described on the dialog alongside each. Read the
descriptions carefully, but most of the time the defaults will be what you want.

The five options (see Figure 102) are described below

Delete a field if there are no layout elements now bound to it?


The default is No don't delete it. You can have a database with multiple forms. Each
form has elements bound to data fields. Assume that your second form has a layout
element on it that is bound to a data field called Location2. No other form or report
has an element bound to Location2.

171
3 DESIGNING A SESAME APPLICATION

If you have redesigned this form and removed the element bound to the Location2
data and then reconcile it to your live application with the answer to delete field...
set to Yes, all Location2 data will disappear from the application DB file. It is no longer
needed and cannot be displayed without an associated layout element.

If you answer No, the data is retained and you can rebind it to a new layout element
in a later design.

Answer Yes delete the field only if you are certain that you want to permanently
get rid of the field as well as any data in it. This is not the recommended choice.

Note that if you answer Yes to this question, then there will be a difference between
the structure of the DSR and that of the DB file. The DSR Designer file will still have
the field (and its data), the DB file will not.

Replace @Number?
The default is No don't replace it. Note that in Sesame there is only one @Number
for the entire application. This appears restrictive, but in fact @Number is only
supported for backward compatibility with Q&A. With Sesame you can have as many
@Numbers as you want by using Global Values. (There is an example of this in the
Sesame Programming Guide.)

172
3 DESIGNING A SESAME APPLICATION

Replace Global Values?


The current status of all the
Global Values can be seen by
selecting Global Values List
Manager from the Application
menu.

Replace Saved Specs?


If you choose Yes, then the
saved specs in the DB file will
be the same as the saved
specs in the DSR file. So not
only will specs be
overwritten, but any added
to the DB since the DSR was
created will disappear. The
default is No do not
include saved specs in the
Reconcile process. Although
specs are created in Sesame
runtime, not in Designer per
se, you can create saved
specs in Designer's Preview
mode. This can be very
handy when preparing
reports.

Replace Security
If you have used the Server
Administration to change
passwords in the runtime
application with the User
Management tab and wish to
maintain these settings, Figure 102. Reconcile Options dialog.
select the default "No"
setting in the area that asks if Sesame "Should reconcile replace the Security in the
target application". If you are making security changes in the designer file and you
wish these to be reflected in the runtime application select "Yes".

173
Section 4
Tabbed Pages
TABBED PAGES enable you to place many layout elements on a single form and have
access to them by clicking between tabbed sections rather than having to scroll down
a long page. They also make it easier for you to segregate your information.
This section will demonstrate how to add tabbed pages to a form. The steps shown are
in the form of a tutorial.

Tabbed pages consist of a TAB GROUP element which contains one or more TAB
PAGES.

Note:
TABBED PAGES as described here, "USER TABS", should not to be confused with
"Sesame Tabs" which appear at the bottom of the Sesame window indicating forms
open, and/or a Search/Update tab and an Add Data tab open for the same form.

There are no limits to the elements that can be put on a Tab Page. In the examples
below new layout elements are created and added to tab pages. You can also drag
existing elements from you current form onto tab page(s).

Tab pages are defined, for the user, by their label that appears on a tab extension at
the top or bottom of the group. See Figure. Tab labels may also be hidden (do not
appear). In this case the tabs are controlled via programming.

A Tab Group with tabs at the top

175
4 TABBED PAGES

Once your tab pages are designed, you navigate between the different tabs in your
runtime application by clicking on the tab name with your mouse or by using the
keystroke combination Alt + (plus sign) or Alt (minus sign) to switch tabs to the
right or left, respectively.

Once you have tab pages created in designer, you can place elements on them by
dragging them individually, or in groups, from the basic form onto the tab. You cannot
add a new layout element directly onto a tab page you must create it first then
reposition it on a tab page.

For illustration purposes let's assume you have a basic form design with the elements:
Salutation, First, Last, Address, City, State, Zip, Phone

Adding a Tab Group


To the left of the form is a series of Control Panels. The second one down is the Layout
Element Adder. To add a tab group:

Figure 1. Using the Control Panel to add a tabbed page to a form.


176
4 TABBED PAGES

1. Click on the form where you want the tab group to be.
2. Select Element Type and choose Tabs.
3. Leave the Bind Element To selection as Unbound, which is the setting for tabs.
4. Type a Label to be used for the new layout element in this case, Spouse. The
label is also used as the Name of the tab group element
5. Click on the Add Element to Form button. A new tab group layout element appears
on the form with the tab title Spouse. (See Figure 1 above.)

Adding a Layout Element to a Tab Page

New layout elements cannot be directly added to a tab page. They must be created
elsewhere on the form and then dragged into position on the tab page. To do this:

1. Click on the form in the space below the State element.


2. Type SF_Name followed by a colon (:)
3. Place the mouse pointer inside the new element. Click and hold the left mouse
button. While holding the left-button, drag the element onto the tab page. As you
move the element onto the tab page you will see a message along the top of it
that says Parenting To: Tab Page, and showing the destination coordinates. (See
Figure 2.)

Figure 2. Moving a layout element onto a tab page by clicking and dragging with the mouse.

4. Repeat the above steps to create the following two additional elements:

SL_Name, and place it on the tab page.


S_Phone, and place it on the tab page.

177
4 TABBED PAGES

You now need to add another text box. But this one needs to have its data type
changed as you add it. You cannot do this by using the type-on-form-add-colon
technique.

1. Using the Layout Element Adder select the Element Type Text Box.
2. Select what you want the text box Bound To. Choose New Date Field.
3. Type a Label to be used for the new Layout Element: S_DOB.
4. Click on the Add Element to Form button.
5. Click, hold and drag the element onto the tab page.
You need to add one more element a multi-line notes field:
6. Click on the form again below the Zip element.
7. Type S_Notes followed by the less-than sign (<) and press Enter. This creates a
multi-line field for notes.
8. Click, hold and drag it onto the tab page. (See Figure 3.)

Note: All layout elements, including tab pages, can be sized or moved. This will be
covered later. Layout elements on the tab page or the tab page itself must be
sized so that each elements text box is fully contained within the tab boundaries.

Figure 3. Completed Tab page with added layout elements.

Note: At this point stop and save your work. Click on Save Layout Design in the
Commands portion of the left-hand Control Panel or click on the Save button on
the main toolbar.

178
4 TABBED PAGES

Adding additional tab pages


A single tab page isnt much use. If a form is to have tab pages at all, it needs
multiple tabs. Lets add a second tab page for another relative of the primary contact.

5. Right-click on the tab page (anywhere on the gray area of the page or on the
actual tab title). Do not right-click in one of the elements on the page.
6. From the menu that appears, select Add New Tab Page. A new page, entitled
TabPage0 appears (See Figure 4.)

Figure 4. Making multi-tab pages using the Add New Tab Page menu.

7. Right-click on the new tab page.


8. From the menu that appears, select Add New Tab Page. Another new page
entitled TabPage1 appears.
9. Click on the TabPage0.
Repeat the five steps you just performed above on the Spouse tab page to place five
layout elements on it, except name them differently to indicate they are for Relative
#1:

R1F_Name
R1L_Name
R1_Phone
R1_DOB (Use the layout element adder for this date field.)
R1_Notes (Make this one a multi-line element.)

179
4 TABBED PAGES

Next, click anywhere on the TabPage1.

Repeat the exact steps you just performed above and on the Spouse tab page to place
five elements on this tab page, except that you must name them differently to indicate
they are for Relative #2:

R2F_Name
R2L_Name
R2_Phone
R2_DOB (Use the layout element adder for this date field.)
R2_Notes (Make this a multi-line element.)

Note: Nows a good time to do another interim save. Click on Save Layout Design
in the Commands portion of the left-hand Control Panel.

Renaming Tab Pages


Now rename the tab pages so theyre more meaningful.

1. Click on the tab entitled TabPage0.


2. Right-click on the tab to display the short-cut menu.
3. From the shortcut menu select Relabel.
4. Type Relative #1 in the Label box, then click on OK.
The title of TabPage0 becomes Relative #1. (See Figure 5.)

Figure 5. Changing tab page labels.

5. Click on the tab entitled TabPage1.


6. Change the label to read Relative #2.

180
4 TABBED PAGES

7. Save your design. Click on Save Layout Design in the Commands portion of the
left-hand Control Panel or click on the Save button on the main toolbar.

Aligning layout elements


Unless you were really careful when placing your layout elements on the tab pages,
they will not be aligned. Lets fix that now:

1. While holding down the Shift key, click once in each element on a tab page. This
will select all of them. Alternatively, right-click on the tab and click on "Select All
Elements on this tab". See Figure 4.
2. In the Property Editor Control Panel, click on the Position tab.
3. In the Align Horizontally box, drop down the list and choose Left. All the
elements on the tab page should now be left-aligned side. (See Figure 6.)

Figure 6. Aligning elements using the Property Editor.

Save your design. Click on Save Layout Design in the Commands portion of the left-
hand Control Panels.

Changing Order of Tab Pages


If you want to change the order in which the tabs appear you can easily do that with
the Tabs Right-Click Tool. Click on the Relative #2 tab (not in an element on the tab,
but on the tab itself) to select it and then Right-click on it. The shortcut menu appears.

181
4 TABBED PAGES

Select <<Move Tab Left. The Relative #2 tab and the Relative #1 tab change
positions. (See Figure 7.)

Figure 7. Moving Tabs with the Right-Click Tool

You can rearrange any of your tabs in this manner. You can move them right or left,
one tab position at a time.

Deleting a Tab Page


To delete a tab page together with all the layout elements on it Right-click on the
tab page (not in an element on the tab, but on the tab itself) to select it. The shortcut
menu appears. Select Delete This Tab Page.

Selecting Elements on a Tab Page


You can click on any element on a tab to select it. You can hold the Shift key down
and select multiple elements by clicking on them individually. If you want to select all
the elements on a tab, you can use the Right-Click Tool which displays a shortcut
menu. Right click on the Tab itself and choose Select All Elements On This Tab. All
elements will be selected (you cannot use rubber-banding on tab elements).

Changing Tab Colors


Each tab can have a different color. Click on the Tab itself. Use the color section of the
Property Editor to set Back/Fill color. The entire tab will change to the color selected.
Using the Label selection in the Property Editor color section will change the color of
the selected tab page Title. Each Tab Page can be set individually. (See Figure 8.)

182
4 TABBED PAGES

Figure 8. Changing Tab Page colors with the Property Editor

Sizing Tab Groups


The entire Tab Group can also be sized easily. Click on the Tab Group itself and note
the sizing handle on the lower right corner. Click on that handle and the mouse pointer
turns into crossed arrows (see Figure 9). Drag to resize the entire Group element. You
will see an indicator at the top of the form indicating the size of the group as you
change it. You can also size the Tab Group (after selecting it) by using the Shift-Arrow
keys on your keyboard. (See Figure 9 below.)

Figure 9. Sizing the Tab Group. Notice the sizing mouse pointer,
and dimensions shown above the element
183
4 TABBED PAGES

Moving Tab Groups


The entire set of tabs can be moved around the main form easily. Click on the Tab
Group itself and hold down the left mouse button. Drag the set of tabs to the position
you want on the form. You will see an indicator at the top of the element indicating the
position and that it is being parented to the form design. You can also move the Tab
Group (after selecting it) by using the Ctrl-Arrow keys on your keyboard.

Deleting a Tab Group


To delete an entire tab group, simply select it and press delete.

Save Your Design


When finished, and at points during your design efforts, make sure to save your
design by clicking on Save Layout Design in the Commands section of the Designer
Control Panel.

Selecting Position of Tab Labels


Right-click on the tab group background to call up the shortcut menu. Select Align
Labels Top or Align Labels bottom or Hide Labels to make them disappear completely.
The default is tabs at the bottom.

184
Section 5
Creating Subforms
Subforms are a way to view the records from a second database from the form of a
master database, so that you can see records from both databases at the same time.

Typically, you use subforms to display records where there is a one-to-many


relationship between the master or parent records and their child subrecords. For
example:

One company can have many departments.


One department can have many staff members.
One car can have many services.

The main form displays a record on the one side of the relationship, and the subform
displays records on the many side of the relationship.

A good example of this would be an Invoice form where each record is the invoice for
a customer, and the subform displays the individual line-items purchased on that
particular invoice.

You need at least two databases in an application before you can create a subform.

In Sesame, you do not need to create relationships between databases before using
subforms. The relationships are created for you when you add a subform to a main
form. There is no "Relationships" dialog where you view or modify the "links" between
databases in Sesame.

Subforms are dynamic you are not limited to just viewing your data. You can edit
data in a subform. You can delete records in a subform. You can add records in a
subform.

This section describes how to create subforms, and the concepts involved. The steps
outlined assume a reasonable level of knowledge of Sesame Designer. If you are not
familiar with Designer, we recommend you read the Designing a Sesame Application
section in this Guide first. For an introduction to adding a subform to a form, see the
Quick-Start Tutorials booklet in the Sesame documentation package, particularly
Exercise 5. Building an Application with Subforms.

To learn about using subforms, refer to the Working with Subforms section later in this
Guide.

185
5 - CREATING SUBFORMS

Setting up a simple subform is straightforward in Sesame. You do not have to get


directly involved in the structure of the database or application. You will see this in the
first example below, which uses the default options throughout.

Sesame also supports additional advanced options for subforms. These alternative
options are for more experienced users. You can set up and use subforms without
them.

Terminology
First, let's define some important terms:

Field A storage unit or "cell" for a single piece of data.

Record A collection of data stored in fields in a particular database.

Database A collection of Field Definitions that determines the structure of a


particular type of record. It provides the "template" for the records. It is also
referred to as a "Record Definition" in the Advanced Concepts appendix of this
Guide.

Field Definition Stores the properties of a particular Field, including Name,


Data Type, Subrecord properties, and the like.

Form Displays data from records based on a particular database.

Layout Element Normally displays data in a particular field.

Subrecord A record which is the natural or relational child of another record.

Subform A type of layout element that can be placed on a parent form to


display the subrecords (child records) for the record shown in the parent form.

Form view subform A subform like the parent form, which shows data in
layout elements arranged on a form. You see only one record at a time.

Table view subform A subform with the appearance of a table or


spreadsheet, which shows data in rows and columns. You see multiple records
at the same time.

Data Source For a form, the full name of the database whose records it
displays. For a layout element, the name of the field whose data it displays.

Natural Link Automatically attaches subrecords to a parent record without


the need for matching key fields. This is the usually way to use subforms in
Sesame. There are no visible links.

Relational Link Locates subrecords by matching field values in the parent


and child databases.

186
5 - CREATING SUBFORMS

Creating a subform
To create a subform, you must already have two forms, each based on a different
database in the same application.

In this example, you will see how to create a main form with a subform as in the
Countries.db sample application on the Sesame CD. The starting point will be the
application with one database Countries and a simple Countries form. (See Figure
1.)

Figure 1. Countries form. No subform.

The first step is to create a new database for the subform. There is currently only one
database and one form in the application. (See Figure 2.)

187
5 - CREATING SUBFORMS

Figure 2. Countries database and Countries form only.

You want a database of Cities for storing the name and the population of the city. This
has to be created in the Countries.db application. The process of creating a new
database and a new form to go with it is covered in detail in the Designing a Sesame
Application section of this Guide. The steps will be covered briefly, below.

To add the Cities form, select Forms / Add New Database. You are asked for a name
for this new database & form. Type CITIES (capitalization is not important).

This opens a new, blank form. Use the Layout Element Adder to add two layout
elements, one bound to a new text field named City and the other bound to a new
number field named Population. (See Figure 3.)

Figure 3. Adding layout elements to the new form.

188
5 - CREATING SUBFORMS

These are the only layout elements needed. Save the form by clicking on Save Layout
Design or the Save button on the menu bar. You now have both a new database and a
new form both named CITIES. Close the design tab.

The menu tree shows the new database


and its new form at the same level as
Countries. (See Figure 4.) The Cities
database is directly underneath
Countries and not indented. This shows
that the two databases are
independent.

Note that although the name of the


form is the same as the name of the
database, they do not have to be so.

Figure 4. Cities database and Cities form added.

The next step is to add the Cities form to the Countries form as a subform.

Open the main form Countries in Designer (Redesign/Customize a Form). Click


on the form where you want the subform to be positioned.

In the Layout Element Adder, select element type Subform. The Bind Element to
must remain Unbound. (See Figure 5.)

Figure 5. Using Layout Element Adder to add the subform.

For the Label, type Cities in this Country, or the text of your choice. This appears as
text next to the subform. By default it appears above the subform, but you can move
it. Or, you can choose not to have a label at all.

189
5 - CREATING SUBFORMS

Click on the button marked Add Element to Form.

Sesame displays the Subform Settings dialog. (See Figure 6.) This dialog consists of
five sections representing steps 1 through 5 which control the way the subform
and the underlying linking mechanisms are established.

In the case where you just want an invoice with line-items on it, you can accept the
default choices. The choices get more complex if you select some of the options
designed to accommodate more sophisticated applications.

The Subform Settings dialog


The Subform Settings dialog contains a number of options. Following is a brief
discussion of each of them.

Step 1: Select a Form

Figure 6. The Subform Settings dialog. Cities form selected to be the subform.

In our example, the only form available is Cities. (See Figure 6 above.)
190
5 - CREATING SUBFORMS

You see a drop-down list of all eligible forms in the database. The rule for whether a
Form is eligible to be a subform is that it can't cause recursion. That is, the subform
cannot be the parent form or contain the parent form at any level. That would cause
an endless loop when Sesame tried to retrieve your records or display your forms.

Step 2: Select Subrecord type


This chooses the link type. It tells Sesame how to decide which records in the
database are considered children of the parent record. The two choices are:

Automatic (Natural Links): This is the default. For simple applications you will
want to use this. There is no matching of key values, no bookkeeping, no
programming. By simply adding a record using the subform, Sesame
automatically makes it a child of the currently displayed parent record. Each
parent record knows exactly which records in the database are its children
without having to look at any other records.

Matching Field Values (Relational Links): With this choice, Sesame goes
through all the records in the database and displays the ones where a
particular field value matches a particular field value in the parent record
which you define in Step 4. This gives slower performance than natural links,
and you are responsible for bookkeeping during data entry that is, for
making sure that the values that are supposed to match, do match.

You will see an example of using relational links later. For now, choose the default
option Automatic (Natural Links). The cities added in the subform will automatically
become attached to the parent country.

Step 3: Select records to display


For both Natural and Relational links, you get three sets of choices:

Make Natural Child Records: This is likely to be the option of choice for most
users. Records in the subform are automatically linked to the corresponding
record in the main form. The correct child records will appear in the subform
based on the settings you use.

If Relational Links is selected, this first option changes to Show Related Child
Records. In this case, the same logic applies.

The child records can also be accessed by opening the subform form by itself.
In this case all the records Cities, for example are shown mixed together.

Show Existing Natural Child Records: If the parent database already has
subrecord database(s) with appropriate linking, they will be listed in a
dropdown selection list. If one of these is selected, the same records from the
database will be shown as in the subform that initially created the existing

191
5 - CREATING SUBFORMS

field definition. In other words, Sesame will use a pre-existing relationship, as


would occur if another subform had already been created.

Create a new Database with Shared Template: This choice is different from the
others. If selected, it clones the selected form and database, but without any
data. This can be useful when you need to add a form as a subform, which
does not already exist.

The records added using this subform will not mix with records added using
other subforms, even though the subforms look identical.

The shared template part means that all databases/forms that share a
template will be kept in synch. So, if you add a layout element to one form, all
forms will have that element.

Step 4: Set subform properties


You must assign a field name to the subform and, if applicable, pick the matching
fields for a Relational link. For this example type the name Cities_Subform.

Step 5: Select a view


Select whether to display records in Table or Form view in the subform. Form view has
layout elements arranged on the form just as it was designed in layout design. (See
Figure 3.) Table View, which is more commonly used for subforms, shows records in a
spreadsheet-like view in rows and columns so you see multiple records at one time. If
there are more columns or rows than can be seen at one time, scroll bars appear so
you can view all the data.

For this example, select Table view. (See Figure 7.)

192
5 - CREATING SUBFORMS

Figure 7. The Subform Settings dialog completed.

When you click OK, the subform is added to the form. It may not be in the correct
position. For example, if you did not first click on the form where you wanted it to
appear, it will appear at the top left of the form. If the subform will not completely fit
on the form, it may appear underneath the form. In both cases resize the form if
necessary and drag the subform where you want it. (See Figure 8.) Save the layout
design.

193
5 - CREATING SUBFORMS

Figure 8. The subform added.

In the menu tree the Cities database is now indented under the Countries database
rather than being directly underneath it. (See Figure 9.)

Figure 9. Cities database now indented under Countries.

To complete this redesign, reconcile or save the Designer file as a new application.
Then open it in Sesame.

194
5 - CREATING SUBFORMS

In Sesame, the Countries form looks as shown in Figure 10.

Figure 10. Countries form with Cities subform.

Any records now added to the subform are automatically parented to the correct
record the main form record. You can also import records into the database by
using a hierarchical import as covered in the Advanced Concepts appendix of this
Guide.

Creating a subform using relational linking


Although natural linking is the preferred way of using data in Sesame subforms, there
may be times when you wish to use relational linking. This might be because you are
using imported databases that contain appropriate fields with values that lend
themselves to such linking and you find it more convenient, or more comfortable, to
use relational links. You may have complex data and you would like the flexibility to
set up relationships other than one fixed one. Or, you may need to "re-parent" a
subrecord, meaning that you change the value in the key field for a child record so
that it matches a different parent record.

Relational linking, while not being the preferred method to use for permanent
relationships, can be employed if you want to look at certain data in alternative ways,
perhaps even temporarily.

195
5 - CREATING SUBFORMS

For example, if you were to build an application to keep track of your music collection,
you might use natural linking to build a subform showing the songs on each album.
That subform might have elements for the songs title, the authors of the song, and
the length of the song in minutes and seconds. In almost every case, that song would
be unique to that album. The record for the album would point directly at the records
for the songs on that album.

While it may make sense to use natural linking to attach a song to a particular album,
you may want to look at your songs by genre instead. Since you may change your
mind about how to categorize a song, you probably want to use the more flexible
relational linking. Relational linking is slower that natural linking, because it has to
match key values. However, you can easily change the parent record to which any
particular child record belongs simply by changing the key value in the child.

For example, if you create a parent form and record definition called Genres (with a
field named GenreName), you can then add a field to Songs called Genre. When you
create your subform, tell Sesame that the relational link exists between
Genres!GenreName and Songs!Genre. When you view the Genres records, the songs
tagged "Jazz" will show up under the Jazz record, the songs tagged Classical will show
up under the Classical record, and so on.

Relational linking, while slower, is more flexible. An appealing feature of Sesame's


relational linking feature is the ability to match values using wildcards rather than a
simple match between two fields. The parents key field acts as a "Retrieve Spec" and
can use the same syntax as the retrieve form uses for that field type. You can use this
capability to have a song appear under more than one genre. If, instead of simply
tagging a song "Classical", you tag it "Classical, Italian, Opera", then it can show up
under three different Genre records having the key values "..Classical..", "..Italian.."
and "..Opera..", respectively. (See Figure 11.) This way, you can use the same record
for all three genres, rather than having to create three separate records.

Also, because the same record appears as a child under each parent, if you correct the
spelling of the song title in the record, it will automatically appear correctly under each
parent record.

196
5 - CREATING SUBFORMS

Figure 11. Relational linking allows the same record to appear under more than one parent
record.

There is a more detailed discussion of natural vs. relational linking in the Advanced
Concepts appendix of this Guide.

In the relational linking example details below, you will see how the same main form
and subform can be set up using an imported database of cities. For this to work,
there must be matching fields in each database. That is, a field in the Cities database
whose values are compared against a field in the Countries database. The field names
don't matter it is the values in the fields in each record that are compared, not the
field names nor the layout element names.

The starting point is the same: an application with just one database: Countries. It has
fields named Country, Capital, Population, and so forth.

In the following example, the subform data will be provided by importing a database
named Cities.

197
5 - CREATING SUBFORMS

Importing subform data


The data for the Cities subform is not in Sesame. It is presumed to be a delimited text
(ASCII) file exported from another application. It needs to have a Sesame database to
receive it.

For this example, the Cities database has these three fields:

City
Population
Country

The ASCII file to be imported has the following structure:

"Adelaide",1115900,"Australia",
"Brisbane",1535300,"Australia",
"Cairns",0,"Australia",
"Canberra",0,"Australia",

The Country field is essential. Without it there can be no relational linking.

Create a new database and a new form with these three fields. Name the form Cities.
See the Designing a Sesame Application section of this Guide or the Quick-Start
Tutorials booklet if you do not know how to create a database.

Import the data into this database. (See the Import Data section of this Guide for
more information.)

Adding the subform to the form


The steps for adding the subform are the same as covered earlier in this section, up to
where the Subform Settings dialog is opened and the Cities form selected as a
subform.

At Step 2, the Matching Field Values setting is used. (See Figure 12 below.)

At Step 3, the Show Related Child Records setting is used.

At Step 4, the subform is named assign a suitable name and the two matching
fields are defined.

198
5 - CREATING SUBFORMS

Figure 12. The Subform Settings for Cities using Relational Linking.

The Fields lists show the data types as well as the field names. This is because you
should select fields with the same data types. You can select mismatched field types,
but the results may be unpredictable, depending on the combination.

In this case, it is the field named Country in both databases. But this need not be the
case. The field names can be different it's the data that matters.

When the subform is added, and the layout saved and reconciled, the form in Sesame
looks like it does in Figure 13.

The results appear to be identical. The Cities database is indented under Countries in
the menu tree. The subform looks the same. However, the data is being matched in
the Country field. So, if you display the record for Brussels and change the value in
the country field from "Belgium" to "Australia", then Brussels will appear on the list of
Australian cities as shown in Figure 13.

199
5 - CREATING SUBFORMS

Figure 13. Countries form with relational Cities subform. Note the record for Brussels.

Note: Although it is necessary for the Country field to be in the Cities database for
this relational linking, it is not needed on the subform in this case. The best solution is
to create another form just for the purposes of the subform, with only those layout
elements on it that you will want to show as columns in the subform. You will still have
the opportunity to pick the Country field as a matching field. It has to exist in the
database but it does not need to be on the form.

To learn about using subforms, see Working with Subforms later in this Guide.

200
Section 6
Adding and Editing Data
Once you have created an application, it is time to start adding data to it. You can do
this by typing in the data, by importing it, or by copying records into it from another
database. The alternative methods are covered in the Import, Export, and Copying
Records section of this User Guide. Below, you will learn how to add new data to your
application using Add Data mode, and work with that data in Search/Update mode.

This section covers the following data entry-related tasks:

Adding (entering) data.


Using and navigating forms.
Using the Field Editor.
Using special form elements.
Data entry shortcut keys.
Navigating from record to record.
Deleting records and duplicate records.
Using the Windows clipboard.
Copying fields and records.
Making corrections.
Printing records while adding them.
Using Table view.

Introduction
First, here's a reminder about the hierarchy of a Sesame application:

Application (Countries.db, for example)


Database(s)
Form(s)

When you work in Add Data mode, you are storing the data you enter in fields in a
database. However, Sesame is form-based, so you do not have to deal with the
underlying database directly. Instead, you enter and view data through layout
elements on forms. In most cases, layout elements are bound (linked) to fields in the
database, so in the context of data entry, the two terms (fields and layout elements)
are generally interchangeable and will be treated as such in the discussions that
follow.

Data types
Sesame uses strong data typing. This means, for example, that only valid dates can
be entered into a date field. You can type anything into a layout element on a form
and, depending on the type of database field it is bound to, Sesame will attempt to
convert it to the proper data type when you move out of that element. If it cannot be

201
6 - ADDING AND EDITING DATA

converted (for example, entering "Next Sunday" in a date field), Sesame will blank the
field or place a zero (0) in it, depending on the field or element type.

Q&A
Q&A employs weak data typing. You can type more or less anything into a
date field or a Yes/No field. You get a red warning message but this is only
a warning. Q&A allows you to proceed and leave something like "TBD" in a
date field or "Yes indeedy" in a Yes/No field. This has negative consequences.
An invoice with a date a user insisted on leaving as "February 30, 2003" would
not appear in a result set for a defined date range. This is the reason Sesame
insists on strong data typing.

Following are the types of layout elements you can add to a Sesame form:

Text Anything that can be typed from the keyboard. Numbers 0-9, alphabetical
characters A-Z, and symbols (!,@,#,$,%,&,_,-,+,*, etc.) are all acceptable in a text
element.

Number Only numeric characters, 0-9, a decimal point, parentheses for negative
numbers, and the + and - symbols can be typed in number elements. You can type
commas or a decimal point (depending on settings) to separate thousands, but it is
not necessary. Any other character, including the currency symbol, will make the entry
invalid and it will be zeroed.

Money As numbers, but you can also type the currency symbol. If you omit the
currency symbol, Sesame will add it. Only one currency symbol is permitted for each
individual element, but you can have multiple elements on a form and a different
currency symbol for each one. Any other character, including the wrong currency
symbol, will make the entry invalid and it will be zeroed. Sesame will format the typed
values as money based on your system or custom settings.

Date Only valid dates will be accepted in these fields. Dates can be entered
specifying the month as a number or as text June or Jun, for example. Dates can
be entered using any of these separators: / . - , (Forward slash, period, hyphen or
comma), or a space. Invalid entries are blanked.

The way dates are displayed in a layout element can be affected by your operating
system's regional settings, the defaults for the layout, and the formatting applied to
the layout element.

Each date element on your form can have different formatting should the designer of
the form wish it, or rely on defaults which may be set outside of Sesame.

You must take care that ambiguous dates are interpreted correctly when you enter
them into date elements. Ambiguous dates are those that are entered numerically,

202
6 - ADDING AND EDITING DATA

with a day-of-month that is 12 or less. For example: "2/11/2007" is interpreted as


February 11th in the U.S., but as November 2nd in Europe.

For the current year, you need only enter the day and the month. You can omit the
century if the date you are entering is between certain years. This is determined by
your operating system. Settings for determining at least the upper threshold can be
adjusted in Windows Control Panel / Regional Options / Date. The default for Windows
2000/XP is for two-digit years to be interpreted as a year between 1930 and 2029.

Sesame internally stores the dates in the yyyy/mm/dd format. You can see this if you
press F6 to open the expanded field editor when working in Table view. (See Table
View later in this section).

Time Data can be entered in the form of Hours(H), Minutes(M), Seconds(S), and
AM or PM. Times can be entered using any of these separators: / . - , : (Forward
slash, period, hyphen, comma or colon), or a space.

You can also enter 12N or 12M for noon or midnight. Sesame stores time of day in an
HH:MM:SS format.

Boolean These fields store Yes/No values as a numeric 1 or 0. Such values can be
entered as Yes/No, Y/N, 1/0, T/F, True/False, On/Off.

Keyword These fields store more than a single entry. Each entry is a separate
value; entries are separated by semicolons. Each entry can be used in retrieve specs
as if it were the only value in the field.

Keyword fields can also be used to find records with more than one value in these
fields. Keyword fields essentially give you the ability to store lists of entries in a single
data field. A good example of this is a list of hobbies. A person could have movies, art,
and reading as hobbies while another might have skiing, movies and football.
Searching this field for movies would return records for both persons. (See the section
in on Searching and Sorting elsewhere in this Guide.)

Back up regularly
It is important to back up your work regularly. You have a substantial investment in
your data, and it is wise to back it up routinely to safeguard it. You can backup by
selecting Backup Application from Sesame's Application Utilities menu, or by making
use of the Backup Application settings in the SESAME.INI file to back up automatically.
You can also backup using other methods outside Sesame. Consult your system
administrator.

203
6 - ADDING AND EDITING DATA

Using forms
Data can be entered by typing text or numbers into fields on the form. It can also be
entered using any of the special layout elements that Sesame provides, such as combo
boxes, list boxes, check boxes and radio buttons.

Sesame is a customizable and programmable database manager. For this reason, you
might see different behavior as you use the form. You might move between fields in
an unexpected order. Information might be automatically entered into fields for you,
or changed, as you enter data into other fields. This is likely to be because the form
has been programmed or otherwise customized by the person who designed it.

A Sesame application can also have security. You may see fields on a form that your
colleague does not see or vice versa. You might not use the same forms or reports
as another user. This can be because of the security that has been applied to the
application.

To open a form to add data:

1. Open the application you wish to use. *


2. From the menu tree select Forms.
3. Select Add Data to add data.
4. From the Add Data menu branch, select the database you wish to use.
5. Under the database select the form you wish to use. (See Figure 1.)
6. Fill out the form.
7. Save the form to the database as a new record by pressing F10 or selecting
Advance Record from the Navigation menu.

* Note: If you open a database that is read-only, Sesame tells you that it will not
be able to save your edits. This warning is displayed only once, when the
application is first opened. For example, this would apply to files on a CD, or
perhaps copied from a CD and left read-only. Any changes made to data will not
be written back to the application.

Note: A record represents the data in the fields on a single form. When you fill out
a form and save it, you are adding a new record to the database.

Using Record Counter to enter Extend mode


You can type in the record counter, on the toolbar, to go to that record number.
Additionally, if you type a number higher than the number of records in the record set,
you will be taken into Extend Mode ('Add mode' at the end of each result set).

204
6 - ADDING AND EDITING DATA

When you open a form in Add Data mode, a new form is displayed ready for you to
enter data into it. The legend, Entering Add data mode, is shown on the status line at
the bottom of the screen, and the Mode indicator on the toolbar is colored maroon and
says Add Data. Usually, the fields on the form will be blank, but you may see zero
values in number fields, and initial values may appear in fields, such as today's date, if
the form has been programmed to display these.

To open a form to search and optionally update data:

1. Open the application you wish to use.


2. From the menu tree select Forms.
3. Select Search/Update to edit data.
4. From the Search/Update menu branch, select the database you wish to use.
5. Under the database, select the form you wish to use. (See Figure 1.)
6. The Retrieve Spec is displayed, the mode indicator is colored blue and says
Search.
7. Specify and retrieve the records you want to work with. (See the Searching and
Sorting section elsewhere in this Guide.)
8. Modify the data as necessary.
9. Save the record by pressing F10 or selecting Advance Record from the
Navigation menu.

Figure 1. Opening Main Form in Customers database in Search/Update mode.

When you retrieve your records in search mode, a filled in form with the values from
your first record is displayed ready for you to edit the data. The legend Entering
Update mode with n records is shown on the status line at the bottom of the screen,
and the Mode indicator on the toolbar is green and says Update.

205
6 - ADDING AND EDITING DATA

Entering data from the keyboard

Text elements
The final look of the data you enter will depend on the design characteristics of your
form and the layout element itself. Several design features can affect the look of your
data. These include:

Font
Size
Style (Bold, Italic, etc.)
Justification (left or right)
Case (UPPER, lower)
Color

Single line text element


In plain, single-line text elements, you enter data by typing it into the field using the
keyboard. All alpha-numeric characters, punctuation, and symbol keyboard keys are
acceptable inputs in a text element.

You simply navigate to the element you wish to fill, and start typing. (See Figure 2.)
Moving out of the element completes your data entry. In a single line text field,
moving out of the field requires pressing Enter, Tab, Shift-Tab, the Arrow keys, or
clicking in another element.

Figure 2. Typing in a text box. Note the double border around the active element.

If you reach the end of the field and still have more to type, you have two options:

Keep typing Sesame will scroll your typing and allow you to enter as much
text as you need.

Press F6 to open the Expanded Field Editor (See below).

206
6 - ADDING AND EDITING DATA

Autocomplete
If you have set the Autocomplete feature to ON (default mode), as you type values in
a text box element, Sesame will search all other values in that field in all other records
currently in the database and present you with a suggested value that matched a
previous record. To select that value just press Enter or otherwise move from the
element. To ignore the suggestion, just continue typing until your entry no longer
matches a former record value. In databases with very many records, Autocomplete
may slow down data entry as Sesame searches for previous values. You can turn off
this feature using the toolbar view menu or changing the settings in the Sesame.ini
file.

Multi-line text element


A multi-line text element differs from single-line data entry in the way it wraps data
and responds to the Enter key. When you reach the end of a line, typing begins to
wrap to the next line. Pressing Enter allows you to create paragraphs in the field. Tabs
can be inserted by pressing Ctrl-Shift-Tab. Otherwise, the two types of elements
behave the same way. (See Figure 3.)

Figure 3. A multi-line text field illustrating word wrap and carriage returns.

Tabs in Multi-Line Text Boxes


Due to the nature of multi-line text boxes being required to accept and display
multiple lines with hard carriage returns (line breaks) the Tab key is the keyboard key
of choice for navigation out of this type of element. You can insert a Tab character into
a multi-line text box by using the combination keystroke Ctrl-Shift-Tab. While this will
insert a tab character in any given line, it does not maintain tab alignment from line to
line.

LE Auto-selection
The Insert key switches Sesame between auto-selection mode and off again. When
auto-selection is ON, then the complete contents of a layout element are selected
(highlighted) on navigating into it. A replacement value can be entered then just by
typing it. 'Typing-replaces-selection' always applies.

207
6 - ADDING AND EDITING DATA

The Expanded Field Editor


Sesame's Field Editor is a moveable, re-sizeable text editing window. Having pressed
F6 to open it, you can type the text you want to enter into the current field; the name
of the layout element appears on the title bar of the window. (See Figure 4.)

When you are finished, Press F6 to Save and Close, or open the Editor menu and
select Save to Element or Save and Close. Save to Element saves your input, leaves
the editor open, and allows you to work in your records with the editor open. The
editor will reflect the contents of any field you move to, in any record. As you type
changes in the editor, they are reflected in the form element. If you navigate without
saving to the current element, your changes to the current element will still be saved.
Save and Close saves your input to that layout element and closes the editor.

Figure 4. Typing into the expanded Field Editor.

Note: If you need to type a lot of text into a text element such as in a
comments field you should really be using a multi-line text element.
(See above.) By opening the field editor for a single-line text box and
pressing enter to start a new line, you place carriage returns into the
element. These are displayed as ^J when you close the field editor. They
are displayed as new lines if you open the field editor again.

Using special layout elements


Besides "the usual" layout elements, called text boxes (even if they contain numbers
or dates), there are a number of more sophisticated elements that can be used to
enter and display data without necessarily having to type it. These are listed below.

208
6 - ADDING AND EDITING DATA

Using a combo box


A combo box is so called because it is a combination of a drop-down pick-list, and a
text box in which you can type a new value. It can be used with either the keyboard or
the mouse. (See Figure 5.)

To use the keyboard with a combo box,


you can drop down (display) its pick-list
by pressing the Down arrow key, or you
can start typing one of the values in the
list to select that value.

You can then navigate the pick-list with


the Up and Down arrow keys. When the
value you want is highlighted, press Enter.
(See Figure 6.)

Figure 5. Combo box with its pick-list


expanded.

To use the mouse with a combo box, you


can click on the Down arrow to the right Figure 6. A combo box showing its entry.
of the combo box to display the values,
then click on the value you want.

You can mix the keyboard and mouse techniques.

With a combo box, you are not limited by the


choices on the pick-list. If you want a
different value, you can just type it.
However, if you type a different value in a
Figure 7. A combo box showing a combo box, it is not added to the pick-list for
typed entry not on the list.
future use. The choices available in the
combo box are set by the form's designer.

Using a list box


A list box is similar to a combo box but it has significant differences:

It is always "expanded" you see all the permissible values.


Accordingly, it takes up more room on the form.
You can choose only among the values on the list.
The selected value is highlighted.

209
6 - ADDING AND EDITING DATA

A list box can have a "null"


selection to indicate a blank
or no entry in that field.

To clear an entry, simply


click on the currently
highlighted entry to
deselect it. This clears or
blanks the underlying field.
(See Figure 8.)
Figure 8. List box with no value currently selected.

To choose an entry in a list box, simply


click on the one you want. Sesame
highlights it. (See figure 9.)

Figure 9. "Green" selected in a list box.

Using a check box


A check box represents a Yes/No field, also called a Boolean field. A check in the box
indicates Yes, True, On or 1. If the box is unchecked, it indicates No, False, Off or 0.

Sesame check boxes are tri-state, meaning that they have a third setting Unknown.
It is the equivalent of the underlying Yes/No field being null or blank. The distinction is
very important.

Take the case of a field that indicates Blood Test OK? Yes and No are obvious, but a
blank field would indicate Results not in yet or Test not yet taken very different to
Blood Test Failed. Null is also used in searching to indicate "doesnt matter; retrieve all
values" like leaving a text box empty.

Figure 10. Check boxes. Entries shown are No, Yes, and null.

210
6 - ADDING AND EDITING DATA

To make an entry in a check box using the keyboard, press the spacebar. The check
box toggles between the three states. (See Figure 10.)

To make an entry in a check box using the mouse, click the check box. It toggles
between the three states each time you click on it.

Using a radio button group


A radio button group consists of two or more circular buttons with labels, contained
within a rectangle. (See Figure 11.) The buttons are mutually exclusive that is,
selecting one deselects all the others. The radio button group returns a single value to
the field in the underlying database. This value is the label of the button that is
selected. A radio button group can be null (empty) in which case no button is selected
and the field is empty.

Figure 11. A radio button group with three buttons.

You can click on the buttons with the mouse, or you can tab into the radio button
group and then use arrow keys to highlight an option and press the spacebar to select
it. You can click the selected button to turn it off, leaving a null or empty value.

Using an image field


An image field displays a picture when you add or edit a record. However, the image
itself is not stored in the database record. All that is stored is the path and filename of
the image file to be displayed. Any images to be used with a Sesame application must
be stored in a folder, or subfolder, as specified during the design of the application.
Sesame makes it easy for you to enter and edit this data with the Image Editor. You
open the editor by double-clicking in the image field with the mouse or by pressing
spacebar with the cursor on it. (See Figure 12.)

211
6 - ADDING AND EDITING DATA

Figure 12. Using the image editor to select and insert a picture

As you click on the image files shown in the list, they are previewed in the editor's
screen. Clicking on Accept adds the filename to the image field in the database.
However, you see the actual image when you view the record. This process is the
same whether you are adding a new image or changing an existing one.

Navigating around a form


You can use several keys to move between layout elements on a form.
You can move to the next element by pressing Tab 
or Enter 
You can move to the previous element by pressing Shift-Tab.
You can also move between elements using the four Arrow keys:    and .

212
6 - ADDING AND EDITING DATA

The Home key can be pressed repeatedly:

The first press takes you to the start of the field (or start of the current line in
a multi-line field).

The second press takes you to the first field on the form.

Pressing Home again will scroll to the top of the form.

The End key can be pressed repeatedly:

The first press takes you to the end of the field (or end of the current line in a
multi-line field).

The second press takes you to the last field on the form.

The third press takes you to the end of the last field. Continuing to press End
will scroll to the bottom of the form.

Page Up and Page Down allow you to see other parts of the form without moving
the cursor.

Note: Form navigation may be programmed by the form's designer, so you


may see some variations in the above. Form Navigation is covered in greater
detail in the Form Navigation section in this User Guide. Form navigation
commands, such as the GoTo command are detailed in the Sesame
Programming Guide.

Data entry shortcut keys


Table 1 shows the various shortcut keys you can use to work within a form and
perform field-related and form-related tasks.

Key(s) Action

F3 Delete Current Record (following confirmation).

F5 Dittos (copies) into the current field the value of the same field
from the record last entered.

Shift-F5 Dittos (copies) a whole record. It overwrites the entire current


record with the record last entered (with user confirmation).

Ctrl-F5 Inserts the current date into the selected field.

Alt-F5 Inserts the current time into the selected field.

213
6 - ADDING AND EDITING DATA

Key(s) Action

F6 Opens / closes expanded field editor.

Shift-F6 Opens current record set in table view.

Ctrl-F6 Switches from Update to Add mode.

F7 (from Add Switches to Search/Update tab if one is open; otherwise opens


Record) a new Search/Update tab at a retrieve spec. Current Add
record is left open and unsaved.

F7 (from Returns to the retrieve spec. Does not automatically save


Search/Update record. If record contains unsaved changes, you will be
Record) prompted to save it.

Shift-F7 Undo current record. Restores the record to the state it was in
when you opened it.

Ctrl-F7 Undo current field. Restores the field to the state it was in
when you opened the record.

F8 Forces all On Form Change programming to calculate.

F9 Saves record and moves from current record to previous


record. In a subform, moves to previous record in same
subform.

Ctrl-F9 Saves record and moves to previous record. In forms with a


subform, moves to the previous main form record.

F10 Saves record and moves to next record.

Shift-F10 Saves record, and subform if any, and closes form.

Ctrl-F10 Saves record and moves to next record. In forms with a


subform, moves to the next main form record.

F11 Copies current record to buffer.

Shift-F11 Pastes values in buffer to current record.

Ctrl-F11 Copies entire current result set to buffer.

Alt-F11 Pastes records in buffer to result set, overwriting existing data


or creating new records.

Ctrl-A Moves to start of line.

214
6 - ADDING AND EDITING DATA

Key(s) Action

Ctrl-C Copies selection to clipboard.

Ctrl-E Moves to end of line.

Ctrl-K Deletes to end of line.

Ctrl-U Clears contents of field. You don't need to select text first.

Ctrl-V Pastes (inserts clipboard contents).

Ctrl-X Cuts (deletes selection to clipboard).

Ctrl-Z Undoes changes to this field only (before leaving it).

Backspace Deletes character to left of cursor, or selection.

Delete Deletes character to right of cursor, or selection.


Table 1. Data entry shortcut keys.

Using the mouse


A mouse has two, sometimes three buttons. These buttons button 1, button 2 and
button 3, are configurable within your operating system to your personal preference.
For most users, button 1 is the left button, button 2 is the right button, and button 3 is
the center button. This configuration is assumed below. Often, depending on model,
the wheel on your wheel mouse can be depressed. In this case, it is the center button.

The left button operates menus, establishes cursor position, selects text by
holding down and dragging.
The right button displays a shortcut menu with useful commands. (See
below.)
The center button inserts text that was last selected (highlighted). Does not
use the Windows clipboard. If you drag across text using the center button,
the selected text is replaced by the text that was last selected.

The shortcut menu


Right-clicking on a layout element displays the editing shortcut menu. The commands
available are:

Undo Undoes changes to this field only (before leaving it).


Paste Pastes. (Inserts clipboard contents.)
Select All Select contents of field.
Copy Copies selection to clipboard.
215
6 - ADDING AND EDITING DATA

Cut Cuts. (Deletes selection to clipboard.)


Clear Clears contents of field. You don't need to select text first.
Help Displays context-sensitive help.

Having displayed the shortcut menu with the right mouse button, you can click on the
items with either the left or the right mouse button.

Saving a record
Sesame saves changes to a record whenever you move to a different record. This can
be with any of the advance/go back keystrokes F10, F9, Ctrl-F10, Ctrl-F9, and Shift-
F10. You can also move to another record, saving the current one, by using the record
navigation toolbar (see Record-to-record navigation, below).

Note: The Save button on Sesame's toolbar does not save changes to
your current record. It forces Sesame to write the in-memory copy of
your application to disk. This process occurs naturally as you navigate
records and perform other tasks, so there is normally no reason to use
the Save button.

Record-to-record navigation
You can move from record to record in the following ways:

Pressing the F10 and F9 keys (in combination with the Shift and Ctrl keys if
necessary. See Table 1 above). Any changes to a record will be saved.

Selecting Advance Record or Previous Record from the Navigation Menu

Using the Record Navigation Toolbar (See Figure 13.) Allows one-click
navigation between records. The buttons, from left to right as shown in Figure
13, perform the following actions:

o The first record in the result set.


o The previous record in the result set.
o The current record number.
o The total number of records in the current set.
o The next record in the result set.
o The last record in the result set.

Note: The result set contains the records that have been added during the
current Add Data session, or retrieved in Search/Update mode. Result sets
are covered in detail in the section on Searching and Sorting in this Guide.

216
6 - ADDING AND EDITING DATA

Figure 13. The Record Navigation toolbar.

You can type a record number into the current record number box to move directly to
that record number.

Once you have clicked on one of the record navigation buttons, you can repeatedly
press Enter or spacebar to continue activating that button.

Note: The record number shown in the Record Navigation toolbar is


Sesame's own internal record numbering. Think of it as an ordinal number
(first record, second record, and so forth). The number is not permanently
attached to the record. Sort the result set, and most likely a different
record will now be record #1.

Bookmark a Record
Sesame allows you to 'bookmark' a record by pressing the Shift-Home key
combination while the record is on the screen. If you navigate to another record,
pressing the Alt-Home key combination will Toggle between the bookmarked record
and the record from which you pressed the Alt-Home keys. To reset the bookmarked
record, display a new record and press the Shift-Home key again. There will be no
visual indication that a bookmark has been set.

Deleting a record
To delete the current record, either press F3 or select Delete Record from the Record
Commands menu. A confirmation dialog will be displayed. Click on Yes to permanently
delete the record from the database. There is no undo when you delete a record.

You can also delete all records in the result set by selecting Mass Delete from the
Results Commands menu. A dialog displays asking you to confirm that you want to
delete nnn records. (See Figure 14.) Click on Yes to permanently delete all these
records from the database. There is no undo when you delete records.

Figure 14. The confirm mass delete dialog.

217
6 - ADDING AND EDITING DATA

Duplicate Records

In Sesame 1.x there was a remove duplicates facility. This is unchanged in Sesame
2.0. It consists of two commands found on the Results Commands menu:

Remove duplicates From Results


and
Delete Duplicates.

These commands are run on the result set. Remove Duplicates just removes duplicate
records from the result set, but leaves the record(s) in the database. Delete Duplicates
permanently deletes duplicate records from the database. There is no undo.

In Sesame 1.x remove/delete duplicates facility required for a record to be considered


a duplicate it had to be an EXACT duplicate of another record: every field needed to
match exactly.

Sesame 2.0 adds two further means to deal with duplicate records. These two new
methods are more flexible in that you can find partial duplicate records by specifying
just some fields to compare. You can remove or delete records from a result set, or
you can search for duplicate records.

Removing or Deleting Duplicate Records from a Result Set


1. Run a search to obtain a result set
2. In the spec window, show the Duplicates Spec (For full details on using the Spec
Window, see page 46).

Figure 15. Duplicates Spec. City, Last and First will be used to determine duplicates.

218
6 - ADDING AND EDITING DATA

3. Click in the row selector for each layout element you want to be checked for
duplicates. For example, if you want identical values in the CITY field to be
considered duplicates, mark the CITY element. A "D" appears in the row selector
for marked elements, and they appear at the head of the list of layout elements.
See Figure 15 above.
4. Run the Duplicates spec using either the menu tree, or the spec window action
bar.

Using the Menu Tree

To remove duplicate records just from this result set (temporary):


Select: Results Commands | Remove Duplicates From Results
or
To permanently delete duplicate records from the database:
Select: Results Commands | Delete Duplicates

Using the Spec Window

Click on the spec window action bar and from the shortcut menu select Run.

Figure 16. Using the Spec Window action bar

A dialog is shown:

Figure 17. Dialog box remove/delete


219
6 - ADDING AND EDITING DATA

To remove duplicate records just from this result set (temporary):


Click the Remove button
or
To permanently delete duplicate records from the database:
Click the Delete button

Whichever method you use, if there duplicates to be removed / deleted a dialog is


displayed, showing the number of duplicates and asking you to confirm removal or
deletion:

Figure 18. Confirm dialog for Remove From Result Set

Figure 19. Confirm dialog for Delete Records

If there are no duplicates there is no feedback.

NOTES
If the duplicates spec is blank no elements checked it acts as if ALL elements were
checked, i.e. all fields must match for a duplicate record to be flagged. This maintains
consistency with Sesame 1.x.

Blank values are considered when comparing values. So if there are two or more blank
values in a particular field, they will be considered to be duplicates of that field if
included in the duplicates spec. For this reason you may want to omit blank values in
the retrieve spec when removing or searching for duplicates. See examples.

If you select the delete option then records are permanently deleted from the
database. There is no undo.

220
6 - ADDING AND EDITING DATA

If two or more records are considered duplicates one of them is retained and all the
others are removed or deleted. You have no control over which record is retained and
which removed or deleted. If you want to view all the duplicate records, including the
'first', then it is better to use the Search for Duplicate Records facility described below.

It makes no difference in which order you select fields to be considered for matching.
However, after running the duplicate spec the result set is sorted in the order of
elements in the duplicate spec, i.e. it acts like a sort spec.

The result set can be obtained using any retrieve parameters or search methods you
like. Retrieve parameters have no influence on the remove duplicates procedure itself,
only in selecting the records which will be involved in the de-duplication.

The form you are using to delete duplicate records may not show all of the fields in the
database. The whole record though is deleted.

Searching for Duplicate Records


You can also search for duplicate records. This produces a result set consisting only of
duplicate records. There are two modes. You can either retrieve just the duplicates
(retaining the 'first' record), or all the duplicates including the first record
encountered. All records are considered equal which of the duplicate records is the
first record is arbitrary.

Searching for duplicate records is available only at the Retrieve Spec. There are two
ways to run duplicate searches: from the menu tree or via the spec window action bar.

1. In the spec window, show the Duplicates Spec

Figure 20. Duplicates Spec. City, Last and First will be used to find duplicates.

2. Click in the row selector for each layout element you want to be checked for
duplicates. For example, if you want identical values in the CITY field to be
221
6 - ADDING AND EDITING DATA

considered duplicates, mark the CITY element. A "D" appears in the row selector
for marked elements, and they appear at the head of the list of layout elements.
See Figure 20 above.
3. Run the Duplicates search using either the menu tree, or the spec window action
bar.
Using the Menu Tree
To show just duplicate ('extra') records :
Select: Search Commands | Duplicates Search
or
To show all duplicate records, including the first record found :
Select: Search Commands | All Duplicates Search

Using the Spec Window


Click on the spec window action bar and from the shortcut menu select Run.

Figure 21. Using the Spec Window action bar

A dialog is shown:

Figure 22. Dialog - show all duplicates or all but one.

To show just duplicate ('extra') records :


Click the All But One button
or
To show all duplicate records, including the first record found :
Click the All button

222
6 - ADDING AND EDITING DATA

Whichever method you use, the duplicate records are retrieved, or if there are no
duplicates then the message No Records Returned by Query is shown.

NOTES
If the duplicates spec is blank no elements checked it acts as if ALL elements were
checked, i.e. all fields must match for a duplicate record to be flagged. This maintains
consistency with Sesame 1.x.

Blank values are considered when comparing values. So if there are two or more blank
values in a particular field, they will be considered to be duplicates of that field if
included in the duplicates spec. For this reason you may want to omit blank values in
the retrieve spec when removing or searching for duplicates. See examples.

If the "Search Duplicates" / "All But One" option is selected and two or more records
are considered duplicates, one of them is not shown and the others are retrieved. You
have no control over which record is considered the first and is not shown.

It makes no difference in which order you select fields to considered for matching.
However, after running the duplicate search the result set is sorted in the order of
elements in the duplicate spec, i.e. it acts like a sort spec.

Use of Duplicates Search


Being able to search for Duplicate records, rather than removing or deleting them,
adds powerful and convenient functionality to Sesame. In the real world a likely
duplicate records situation is not simple, but involves multiple records for one
customer contact, say, but with the data for that person spread across two or more
duplicate records. There is not the simple situation of one 'master record' and other,
expendable duplicates of it.

By searching for duplicate records and including ALL the duplicates you can see,
together, all the duplicate records not just the 'extras'. You can mass update them
marking them for easy retrieval later; you can browse through them and, significantly,
you can cut and paste useful information between the records before deleting the
unwanted ones.

223
6 - ADDING AND EDITING DATA

Re-using Previous Values

Sesame offers a variety of ways to enter data into fields without typing it. They can be
summarized as "programmed" or "non-programmed".

Programmed elements are combo boxes, radio button groups, list boxes and menu
buttons, and can also include programming attached to normal text boxes which
display a picklist of values from this database or from another external database. All of
these use layout elements that offer a list of values that a developer has entered in
Sesame Designer. To read about using combo boxes and the like see Using Special
Layout Elements on page 208.

The non-programmed ways to re-use previous values are

Autocomplete
Using the Windows Clipboard
Ditto a single field or a whole record
The Memory Menu
Copy a whole record elsewhere
Copy multiple records elsewhere

Autocomplete
When Autocomplete is turned on, as it is by default, when you type into a text layout
element Sesame will show you matching values for that field, based on the values
already in the database.

For example, if you type "B" into the Surname field in the Customers.db sample
application you might be shown the name "Bernard". Then typing an a so you have
typed "ba" might produce the name "Baker", and so on. See the table below.

ba

Bar

Bart

Figure 23. AutoComplete in use.

In each case the letters that Sesame has added are highlighted and will be deleted if
you continue to type. If the value becomes the one you want, just press enter or tab.
If the value selected is not correct just keep typing.

224
6 - ADDING AND EDITING DATA

Autocomplete works in all modes: in Add mode, in Search/Update, and even at the
retrieve spec, so it can be used to easily search for data.

Autocomplete can be switched off and on by toggling the Autocomplete options found
on the View menu on the Sesame Main Menu. Autocomplete can also be turned off or
on by default by settings in the SESAME.INI file. Autocomplete can also be adjusted
programmatically: it can be disabled for an element and the list of Autocomplete
values can be set for an individual element.

Autocomplete works by looking through the existing entries for that field in the current
database. It has to look through all of them. This can make Autocomplete slow on
large databases. What constitutes "large databases" and "slow" depends upon a
number of factors including your hardware. But the performance on a modern
computer is fine on the sample ZipCode database which has 43,000 records.

Using the Windows Clipboard Cut/Copy/Paste


Other tools that can help you during data entry and data editing are the standard
Windows cut, copy, and paste operations. In any text field, you can select data by
dragging over it with the mouse or by holding down the Shift key while pressing an
Arrow key. Selected text can then be cut (removed from the field and copied to the
clipboard) or copied (left in the field with a copy placed on the clipboard). You can
select another field, even in another record, another database, another Sesame
application, or an external application, and paste the text into it.

After data is selected or the target chosen, the cut, copy, and paste operations can be
performed in three ways:

From the Sesame menu bar Edit menu which has all three choices.

Using the standard shortcut keys:

Ctrl-X Cut
Ctrl-C Copy
Ctrl-V Paste

By clicking with the right mouse button to bring up the editing shortcut menu
which has these and other choices.

Q&A
In Q&A 5.0, the F11 and F12 keys copy and paste to/from Q&A's internal
clipboard. Q&A does not use the Windows clipboard.

225
6 - ADDING AND EDITING DATA

Ditto Field/Record
This facility is useful for immediate, local copying.

Edit Commands|Ditto Current Field, or keystroke F5 dittos (copies) the data from
the same field in the previous record to the current field in the current record,
replacing its contents. The previous record is the record that was displayed just before
the current one. There is no undo. This facility works in Add mode, Search/Update
mode, and in Table View.

Edit Commands|Ditto Form, or keystroke Shift-F5 dittos (copies) the previous


record into the current record, overwriting the entire current record with the data from
the previous one. The previous record is the record that was displayed just before the
current one. Sesame prompts you to confirm that all the data in the current record will
be replaced. There is no undo. This facility works in Add mode, Search/Update mode,
and in Table View.

Q&A
In Q&A, ditto works only in Add Data mode. In Sesame, it works in
Search/Update mode as well. However, unlike in Q&A, in Sesame you cannot
switch from Search/Update to Add Data and ditto the last record. Instead use
the F11 copy record command described in this section.

Memory Menu
Pressing Alt-Enter in a text element presents a memory menu showing the last ten
values entered into that element while this form has been open. The menu is attached
directly below the element. Selecting one of the values on the menu will put that value
in the text element. If all the values are wrong, press Escape or click in the layout
element to dismiss the list.

Pressing Alt-Up or Alt-Down will cycle through the values in the memory menu without
displaying the menu.

The memory menu works in Add mode and in Search/Update mode. It does not work
at the retrieve spec.

The memory menu is cleared when you exit from Add mode or from Search/Update
mode, e.g. to run a new search.

Copying fields and records


Sesame has facilities to copy fields and records when you are editing data. These are
in addition to the Copy Records facility which is quite separate and is used for copying
records between different databases this is described in the Import, Export and
Copy Records section of this guide. These are also separate from the Ditto Current
Field / Ditto Form feature described earlier in this section.

226
6 - ADDING AND EDITING DATA

F11 Copy and Paste Records


Sesame has a temporary memory store called the BUFFER. This can be used to store
the values from one or more records and paste them into other records using the
same form or a different form, even into a different database.

The Sesame buffer is independent of the Windows Clipboard, and is also not connected
with the F5/Shift-F5 ditto feature.

The Sesame buffer is retained as long as Sesame is open, and works across multiple
databases and multiple applications.

There are 4 commands for copying and pasting a single record or multiple records.
Each can be used from commands on the menu tree or via keystrokes.

Figure 24. The four menu tree commands for Copy/Paste records

COPY PASTE
One record F11 Shift-F11
Multiple records Ctrl-F11 Alt-F11
Figure 25. The four keystrokes for Copy/Paste records

From any record, you can press F11 to copy all the values on your Form. You can then
go to a new record, or a different record, and press Shift-F11 to paste all the copied
values into the matching elements. These commands work in Add mode and
Search/Update mode.

Copying / Pasting a Single Record

Copy Form to Buffer (F11)


Copies the data from the current record into Sesame's buffer. The copied values are
retained until you close Sesame. This means that you can close the current form, open
a different form, or even open a different application and still be able to paste your
values. If a Copy Spec is current then only selected LE's are copied see below.

227
6 - ADDING AND EDITING DATA

Paste Form to Buffer (Shift-F11)


Pastes the data from Sesame's buffer into the current record. The values stay in the
buffer. If a Copy Spec is current then only selected LE's are copied see below.

One use for this feature is copying the values from an existing record into a new
record. Find the existing record you want and press F11. Go to a new record either by
opening your Form in Add Mode, or by adding a new record to the end of your result
set (extend mode). On your new record, press Shift-F11. Since the copied values are
retained, you can paste multiple times, for example, if you are adding more than one
new record.

As well as pasting into a new blank record, you can also paste a record into an existing
record. You will see a warning message asking to confirm that you wish to overwrite
the existing record.

Copying / Pasting Multiple Records

As well as being able to copy and paste a single record using the Copy form / paste
form, you can copy and paste multiple records using the (plural) Copy Forms to Buffer
/ Copy Buffer to Forms commands. The combination of Copy Forms to Buffer and Copy
Buffer to Forms provides a quick and easy way to move data from many records in
one form to different elements in an entirely different form. Using the copy spec, you
can pick and choose which elements get which pieces of data. Because the buffer is
retained even if the application is closed, this command makes it especially easy to
move data from one application to another.

Copy Forms to Buffer (Ctrl-F11)


The Copy Forms to Buffer (Ctrl-F11) command appears in both Add mode and in
Update mode under the Edit Commands branch of the command tree. It is related to
the command Copy Form to Buffer (F11). Where Copy Form to Buffer (F11) copies the
current form to the Sesame buffer, this command copies the entire result set to the
buffer. Like Copy Form to Buffer, this command can use the copy spec to allow
copying between dissimilar forms. If no copy spec is in use, this command will copy
the layout elements in layout element order, and copy the forms in result set order.
Once the data is in the buffer, it can be "pasted" into forms using Copy Buffer to
Forms (Alt-F11). The buffer persists while Sesame is open.

Copy Buffer to Forms (Alt-F11)


This is the reverse of Copy Forms to Buffer (Ctrl-F11). Instead of copying a set of
forms to the internal "copy buffer", it copies the buffer's contents to a set of forms.
The buffer keeps track of the number of forms needed and will create new records if
required. If any of the forms/records are not new, a warning is presented to the user
indicating that they are about to copy over existing records. If a copy spec is in use,
this command will copy from differing layouts as specified by the spec see below.

228
6 - ADDING AND EDITING DATA

Copying Main Form & Subform Data


You can use the F11 family of commands to copy parent forms as normal. No subform
records are copied with a parent record. Subform records can be copied using the
F11 family of commands as normal.

Advanced Use
In its simplest form, this feature allows you to quickly copy a record where the source
form and the destination form are identical. However, sometimes you need to copy
and paste between forms that are different. You may also only want to copy some of
your values, or you may want to paste your values in a different order. If this is the
case, you can control both the copy and paste behavior of the F11 family of commands
by using the Copy Spec.

Note: To use a Copy Spec for this


purpose, you only have to click the Enable
button for each element, causing a "C" to
appear beside it. You do not need to open
the Copy Spec dialog and match
elements. (See Figure 26.)

Figure 26. The Copy Spec window with just 3


LE's selected.

Since you can have a Copy Spec set for both the source form and the destination
form, advanced record copy has four possible combinations. The behavior for each
combination is detailed below. All examples use forms with the following list of
elements and values:

Source Form Destination Form


Name = Jones Name
Address = 123 Main St Color
City = Anytown Size
State = NY Brand
Zip = 10011 Category

Source: No Spec
Destination: No Spec
F11 copies the values from the source form in the order the appear on the Form. Shift-
F11 pastes the values into the destination form elements in the order the elements
229
6 - ADDING AND EDITING DATA

appear on the destination form. If there are more source values than destination
elements, the remaining destination element values are not changed.

Destination Form Values after Paste:


Name = Jones
Color = 123 Main St
Size = Anytown
Brand = NY
Category = 10011

Source: Copy Spec set


Destination: No Spec
F11 copies only the values from the source form elements specified in the source Copy
Spec, in the order they appear in the Spec. The source values are tagged with the
name of the source element. Shift-F11 pastes each value into the destination form
element whose name matches the source element. Source values without a matching
destination element are ignored. Destination elements without a matching source
value are not changed.

Source Copy Spec


[C] Name
[C] State
[C] Zip

Destination Form Values after Paste


Name = Jones
Color =
Size =
Brand =
Category =

Note that only the Name element was changed, since it is the only one that matched.

Source: No Spec
Destination: Copy Spec set
F11 copies the values from the source form in the order the appear on the Form. Shift-
F11 pastes the values into only the destination form elements specified in the
destination Copy Spec, in the order they appear in the Spec. Destination element
values not specified in the destination Copy Spec are not changed.

Destination Copy Spec


[C] Color
[C] Size
[C] Brand

230
6 - ADDING AND EDITING DATA

Destination Form Values after Paste


Name =
Color = Jones
Size = 123 Main St
Brand = Anytown
Category =

Note that only those destination elements appearing in the destination Copy Spec
were changed.

Source: Copy Spec set


Destination: Copy Spec set
F11 copies only the values from the source form elements specified in the source Copy
Spec, in the order they appear in the Spec. Shift-F11 pastes the values into only the
destination form elements specified in the destination Copy Spec, in the order they
appear in the Spec. Destination element values not specified in the destination Copy
Spec are not changed. When destination Copy Spec is set, source element name
matching is not used.

Source Copy Spec


[C] Name
[C] State
[C] Zip

Destination Copy Spec


[C] Color
[C] Size
[C] Brand

Destination Form Values after Paste


Name =
Color = Jones
Size = NY
Brand = 10011
Category =

Undo

Sesame has two UNDO facilities. The first can be considered 'immediate undo' and
only works while you are still in the layout element you have just edited. The second
works after you have left that element but before you have saved the record. Once

231
6 - ADDING AND EDITING DATA

you have saved a record (for example by advancing to another record) there is no
undo.

'Immediate' Undo
You can activate this in any of three ways:

Selecting Undo from the Edit menu on the main toolbar.

Selecting Undo from the Editing Shortcut menu shown by clicking on the
element with the right mouse button.

Pressing Ctrl-Z.

Any of these will delete any new data typed in a field and restore the original value.
Selecting Undo again will act as a toggle and reinstate the new data in the field. Undo
works only while you are in the field just edited.

Restoring a field or record to original values


If you have made changes to a record but not yet committed these changes (by
moving to another record, or using the Navigation / Save Record command for
example), then you can put an individual field, or the whole record, back to the values
it had when you retrieved it.

To restore a single field/layout element:

Select Edit Commands / Undo Current Field or press CTRL-F7

To restore the whole record:

Select Edit Commands / Undo Current Form or press Shift-F7

Making Corrections
Changes can be made to any field data by selecting the field and typing in new data.

You can delete or replace data in the following ways:

Select all of the text in a field with the mouse or Shift and Arrow keys, press
the Delete key, then type in your new data.

Place your cursor in the text where you want the delete to begin, then press
the Delete key to delete text to the right of the cursor or the Backspace key to
delete text to the left of the cursor.

232
6 - ADDING AND EDITING DATA

Select all of the text in a field with the mouse or Shift and Arrow keys, then
start typing your new text. It will replace the selected text.

Right-click in the field to display the editing shortcut menu. You can then
select Clear to clear the contents of the field without selecting it.

Click in the field and press Ctrl-U. This clears the contents of the field without
having to select it.

Printing Records
Sesame allows you to print individual records, or your complete result set of records.
To print the record you are currently viewing, select your print option from the Record
Commands / Printing Commands menu. To print all the records in the current result
set, select your print option from the Results Commands / Printing Commands menu.
For more information on printing forms, see the Printing Forms section in this Guide.

Using Table view to add/view/edit data

Sesame offers two views of your data for each form: Form View and Table View. When
you open the form you always see Form View. Table view is a spreadsheet-like view of
your data in rows and columns. Each row (horizontal) is a record, and each column
(vertical) a field. Data is editable in table view: you can modify existing data and also
add new records.

The view of the form can now be controlled programmatically, using the
"FormViewType" sbasic command. See the Programming Guide for details.

Switching to Table View


You toggle between form view and table view by either:

Keyboard: Shift-F6
Menu Tree: Other Commands / Toggle Table View (Shift-F6)

The view instantly changes. The form is replaced by the Table view which is embedded
within the Sesame window (unlike Sesame 1.0 where table view was in a separate
window).

In table view you see your data formatted exactly as it is in form view. So you see the
same fonts, font sizes, foreground and background colors, formatting and alignment
as you see in form view. These are set in Sesame Designer.

The column headings are Layout Element names (not field names as in Sesame 1).

233
6 - ADDING AND EDITING DATA

Figure 27. Table view, showing fonts and colors

When you switch to table view the current record is the first record in the form view
result set. When you switch back to form view you see the record you were on in table
view.

Printing Table View


You can print what is displayed on your screen to the printer by selecting the Record
Commands / Printing Commands / Print Form from the menu tree. Or you can create
an HTML copy of your entire table by selecting the Record Commands / Printing
Commands / Print Form to HTML from the menu tree.

Customizing Table View

Changing Columns
You change which LEs (fields) are shown,
and the order of columns, in the Table
View spec. This is shown in the Spec
window in the lower-left quadrant of the
screen. Use the left / right arrow buttons
at the spec window header bar to cycle
through the specs until the table view
spec is showing (shown as "Table" + the
name of the form).

Click on the row selector for a layout


Figure 28. Table spec. Only LEs with "T" will
element to include it.
show.

You can also click on "Select All" or "Clear All" from the table spec header bar. LE
names, once selected, can be re-ordered by dragging them up or down the list (you
can also use shift + up/down arrow keys).

234
6 - ADDING AND EDITING DATA

Click on "Run" from the spec header bar to apply the spec. You can only re-order the
columns in the spec window, not in table view itself.

To change the width of a


column, drag the right boundary
of its column header:
Figure 29. Changing column width

Adding and deleting records in table view


To add a record:
1. Press Ctrl-End to go to the last record in the result set
2. Press Down arrow to go to a new record
3. Fill in the data
4. Move off that record to save it.

To delete a single record:


1. Put the cursor on the record to be deleted.
2. Press F3 or select Record Commands / Delete Record (F3)
3. Confirm to delete the record.

Do delete multiple records:


1. Retrieve the records you want to delete
2. On the menu tree select Results Commands / Mass Delete
3. Confirm to delete all the records in the result set.
Sorting records in Table View
Table view shares the same sorting as form view. This is changed in the sort spec, in
exactly the same way as you would change sorting for form view. (Unlike Sesame 1
which had separate table view sorting in the column headings.)

Saving Table View specs


Specs can be saved and re-used, just like retrieve specs, mass update specs etc.
These are saved, loaded etc using the Spec Manager, just as other specs. You can
save a default table spec. Table specs store which columns are included, and the order
of them, but not column widths.

Summary functions and charts


You can display summary information and charts based on values in numerical fields
displayed in table view. The summary functions available are Total, Average, High or
Low.

235
6 - ADDING AND EDITING DATA

The charts are for visual information purposes only and the types available are:
Bar Chart
Filled Chart
Horizontal Bar Chart
Line Chart
Pie Chart
Sliced pie chart
Spike Chart

These facilities are only valid for numerical fields, or fields which have values which
can be evaluated as numbers, for example Zip codes. You can go through the process
of obtaining a summary or a chart for other fields, but the results will not be
meaningful.

To display a summary

1. In table view, select the desired


column by clicking on the column
heading. The column is highlighted as in
the figure below.

2. Right-click on the column heading. A


picklist is displayed showing the 4
summary functions and the 7 chart types.

3. Select the summary function you


require.

4. The summary value is displayed


adjacent to the column heading. The
value cannot be printed, but you can
select the value and its label and press
Ctrl-C to copy them to the Windows
clipboard.

5. The summary is 'modal' (you cannot


leave it open). When done, dismiss the
Figure 30. To display a summary. summary by clicking on the 'return'
button attached to it.

236
6 - ADDING AND EDITING DATA

Figure 31. Summary displayed.

To display a chart
1. In table view, select the desired
column by clicking on the column
heading. The column is highlighted as in
the figure below.

2. Right-click on the column heading. A


picklist is displayed showing the 4
summary functions and the 7 chart types.

3. Select the chart you require.

4. The chart is displayed in a moveable


window. The window can be maximized or
resized, but the chart does not scale. The
chart cannot be printed.

Figure 32. Displaying a chart

237
6 - ADDING AND EDITING DATA

Figure 33. Bar chart displayed

5. The chart window is not 'modal' - you can leave it open and continue working with
Sesame. You can display more than one chart at a time. When done, dismiss the chart
window(s) by clicking on the red 'X'.

Effect on subforms
Table-view subforms behave exactly like table-view of a main form.

Programming Conditions
Most form programming in table-view subforms should work as normal.

238
Section 7
Navigating Forms
There are many ways to move within and between the various elements on your
Sesame forms. The recommended way to navigate between form elements other
than using the mouse is to use the Tab key to move forward and Shift-Tab to
move backward. Other keys or key combinations can be used, depending on the type
of element you are moving to or from. You will invariably find your own favorite
combinations.

Sesame has a default or normal behavior when navigating forms. In actual use, you
might see different behavior. Sesame is a customizable and programmable database
manager. Navigation behavior can be controlled by programming and affected by
read-only fields, element-level security, or other customization added by the form's
designer.

This section covers form navigation and the keystrokes associated with it. Be sure to
read the section in this Guide on Adding and Editing Data to understand how to enter,
change, and save data in your forms.

Navigation keys
In addition to selecting an element by clicking on it, Table 1 shows the standard
navigation keys used in Sesame forms.

Keystroke Action

Tab Moves forward in a form between elements in a top-left to bottom-right


direction. Will move from main form to subform but will not leave the
form area. Default Navigation Key

Shift-Tab Moves backward in a form between elements in a bottom-right to top-


left direction. Will not move from subform to main form and will not
leave the form area. Default Navigation Key

Enter Normally moves forward in a form between elements in a top-left to


bottom-right direction unless you enter special types of elements where
the Enter key activates selections.

Home First press moves to the start of the text. Second press moves to the
first element on the form. Third press scrolls the form to the top.

End First press moves to the end of the text. Second press moves to the
last element on the form. Third press scrolls the form to the bottom.

239
7 NAVIGATING FORMS

Keystroke Action

Up Arrow Normally moves to the previous element on the form in the same order
as pressing Shift-Tab, except through element types where arrow keys
select or change selection, or the element is multi-line. If you are in the
first element on your form, Up Arrow will scroll upward until you reach
the top of the form.

Down Normally moves to the next element on the form in the same order as
Arrow Tab key movement, except through element types where arrow keys
select or change selection, or the element is multi-line. If you are in the
last element on your form, Down Arrow will scroll downward until you
reach the bottom of the form.

Left Normally moves through the data in an element, then to the previous
Arrow element on the form in the same order as Shift-Tab movement, except
through element types where arrow keys select or change selection.

Right Normally moves through the data in an element, then to the next
Arrow element on the form in the same order as Tab movement, except
through element types where arrow keys select or change selection.

Ctrl-Home Moves to the first record in the current set.

Ctrl-End Moves to the last record in the current set.

Page Up Scrolls up a long form.

Page Scrolls down a long form.


Down

F10 Saves changes and moves to the next record.

F9 Saves changes and moves to the previous record.


Table 1. Standard Sesame form navigation keys.

Navigating a single form


Sesame attempts to keep your elements in a normal navigation order where you move
from the top-leftmost element in a forward direction toward the bottom-rightmost
element. However, form element alignment and sizing, frame differences, and multiple
redesigns could affect the normal navigation sequence on a specific form. If you are
having trouble with your navigation, you can set the Navigation Order in Designer.

Alternatively you can use programming to control the element-to-element movement


on the form. For example, you could use an On Element Exit programming statement
in a FirstName element like this:
240
7 NAVIGATING FORMS

If LastName = "" Then ThrowFocus(LastName)

This way, you can make sure navigation always goes from FirstName to LastName
when you are adding data. Take care that such go-to statements are suitably
conditional (If...Then...), because On-Element-Exit programming in Sesame will be
activated no matter how you exit the element even by clicking on another part of
the form. See the Sesame Programming Guide for more information on adding
automation to your forms and elements.

Element types and keystrokes


In certain element types, different keystrokes perform different functions. You must be
aware of these functions as you navigate through the form. In every element type,
Tab moves forward to the next form element, Shift-Tab moves to the previous form
element, and a mouse click on the element moves you into the element. Table 2
shows how the most commonly-used keystrokes and key combinations behave in the
various form elements.

Element Keystroke Action

Single line Enter Moves to next form element.


text
Down Arrow Moves to next form element.

Right Arrow Moves through data, then to next form element.

Up Arrow Moves to previous form element.

Left Arrow Moves through data, then to previous form element.

Multi-line Enter Remains in element and moves down one line.


text
All Arrow keys Moves through data until reaching end, then acts like
an arrow key in a single-line text element.

Text Editor Enter Remains in element and moves down one line.

All Arrow keys Moves through data until reaching end, then acts like
an arrow key in a single-line text element.

Image All Arrow keys Moves through data until reaching end, then acts like
an arrow key in a single-line text element.

All Arrow keys Acts the same as arrow keys in single-line element.

241
7 NAVIGATING FORMS

Element Keystroke Action

Spacebar Opens image editor window for selection of image


filename.

Mouse Double- Opens image editor window for selection of image


Click filename.

Radio Arrow Keys Moves through the different buttons. Right arrow also
Button moves selection down and left arrow moves up.
Group
Spacebar Selects highlighted button.

Enter Selects highlighted button.

List Box Mouse Click Selects/deselects list box choice.

Up/Down Moves through list box choices. Leaving the list box
Arrow Keys leaves the highlighted choice selected.

Right/Left Moves to next and previous form elements


Arrow Keys respectively.

Spacebar Toggles selection on and off.

Combo Shift-Tab Moves to previous element.


Box
Mouse click or Opens dropdown list.
down arrow

Shift Opens dropdown list.

Escape Cancels open dropdown list.

Up/Down Moves through dropdown list selections.


Arrows

Enter Moves forward to next form element.

Enter, with list Enters the highlighted list item.


open

Tab Moves forward to next form element. If tab is


pressed with the list active, tab cancels current
selection and leaves entered value unchanged.

242
7 NAVIGATING FORMS

Element Keystroke Action

Command Mouse click Activates button.


Buttons
Spacebar Activates button.

Enter Navigates forward through the button to the next


form element without activating the button.

Tab Navigates forward through the button to the next


form element without activating the button.

Shift-Tab Navigates backward through the button to the


previous form element without activating the button.

Check Box Mouse Toggles values.

Spacebar Toggles values.

Enter Moves to next element.

Tab Navigates forward through the check box to the next


form element without changing the setting.

Shift-Tab Navigates backward through the check box to the


previous form element without changing the setting.

Right/down Moves to next element.


arrow

Left/up arrow Moves to previous element.


Table 2. Keystrokes for different element types.

Moving between main form and subforms


When you have a subform on your form, you will actually be moving and navigating
through two separate forms. Once in the subform, all of the main form navigation
procedures listed above apply. When you are in the main form, the subform is treated
as another element as far as forward navigation is concerned. You can Tab into the
subform from the main form or you can use the mouse to click in the subform.

Once in the subform, you can fully navigate between elements with the keyboard, and
can navigate out of the subform with the Ctrl-Up-arrow key only. You can also return
to the main form by clicking in an element on the main form. The Shift-Tab key will
not move you from a subform to the main form.

243
7 NAVIGATING FORMS

Navigating Table View


When you switch to Table view (Shift-F6), each record is displayed as a row in a table.
(See Figure 1.)

Figure 1. Table view.

Table 3 shows the keystrokes for navigating in Table view.

Keystroke Action

Tab Moves through the columns (fields) in a record from left to right.

Shift-Tab Moves through the columns in a record from right to left.

Enter Edit mode selects the contents of the cell. Typing replaces
highlighted cell contents. A second Enter then moves to the cell to
the right.

Shift-Enter Not a navigation keystroke. Toggles the Sesame window between


its normal (restored) size and a maximized window.

Right-Arrow Moves through the columns in a record from left to right.

Left-Arrow Moves through the columns in a record from right to left.

Home Moves to the first (leftmost) column of the current record (row).

244
7 NAVIGATING FORMS

Keystroke Action

End Moves to the last (rightmost) column of the current record (row).

Ctrl-Home Moves to the top left of the table (first field of first record).

Ctrl-End Moves to the bottom left of the table (first field of last record).

Down Arrow Moves to the next row (record) of the table. From the last row
creates a new row for a new record.

Up Arrow Moves to the previous row (record) of the table.

F10 Moves to the next row (record) of the table. From the last row
creates a new row for a new record.

F9 Moves to the previous row (record) of the table.

Esc Closes the form.

Any alpha- Starts editing selected field of the current record, adding text to
numeric key the end of the current contents.

Mouse click Moves to the selected cell (field in the selected record)

Double mouse Opens that cell (field) for editing, with contents selected. A
click subsequent mouse click deselects the contents and positions the
cursor in the cell.
Table 3. Keystrokes for table view navigation.

See the section in this Guide on Using Table View in the Adding and Editing Data
section of this guide for information on adding records, updating, and saving changes
to your records in table view.

245
Section 8
Searching and Sorting
Sesame has powerful searching capabilities. Searching is both easy and versatile. In
this section you will learn how to perform simple as well as complex searches, how to
save and re-use your search criteria, and how to work with the result set of records
that Sesame finds when you perform a search.

Heres a summary of what this chapter covers:

Basic searches.
Complex searches.
Very complex searches involving programming.
Searching special layout elements
Fine-tuning your searches to obtain the results you want.
Saving searches for re-use.
Sorting your result sets.

Introduction and terminology


You view your Sesame data through forms. A Sesame application can have more than
one database. Each database can have more than one form. It is common to have
several forms connected to one database, each one showing different fields or
"task-related" forms. To view your data, you open a form in Search/Update mode, fill
in the Retrieve Spec, then run the search.

The Retrieve Spec is a view of your form containing no data. You type in examples of
what you are searching for these are called your search criteria. When you run the
search, Sesame will return the group of records that meet your search criteria. This is
called the result set. A result set comprises one or more retrieved records. (If no
records meet your search criteria, Sesame does not return a result set.)

You can now review the records in the result set and update them if you like.

Basic Searches

Retrieving ALL records in the database


Following is an example of a basic search using the Customers.db sample application
on the Sesame CD. Perform the following steps to view all records in the Customers
database:

1. Open the sample Customers.db application from the SAMPLES folder.


2. From the Menu Tree select Search/Update.
3. Select the Customers database.

247
8 SEARCHING & SORTING

4. Select the form Main Form. (See Figure 1.)

Figure 1. Opening Main Form in Search/Update mode.

Sesame will display a blank form. Notice that a new tab has opened up, with the title
Search/Update Main Form. (See Figure 2.) This is the Retrieve Spec.

5. Press F10 or click on Retrieve New Results in the Menu Tree.


Retrieving just some of the records
Perform the following steps to view all records for the state of Georgia in the
Customers database:

Perform steps 1 4 as described above, then at the retrieve spec ...

5. Click in the State field.


6. Type "ga" without the quotes (UPPER CASE or lower case it makes no
difference). (See Figure 2.) It is likely that as you type "GA" will appear in the
field automatically. See "Autocomplete when searching" below.
7. Press F10 or click on Retrieve New Results in the Menu Tree.

248
8 SEARCHING & SORTING

Figure 2. Finding customers in Georgia.

Sesame will display the first matching record of the result set. You can now continue
to press F10 to view the remaining matching records.

There are a couple of features which can prevent searching working exactly as
described above: Autocomplete and Templates. These are described below.

249
8 SEARCHING & SORTING

Autocomplete when searching.


Sesame has a feature called Autocomplete
which "guesses" what you want to enter and
enters it for you as you type into a layout
element.
Autocomplete works in Add data mode, in
Search/Update mode (when viewing existing
records) and also at the Retrieve Spec.
When Autocomplete is active, it will look in
the current database and propose values
from the database as you type in the
retrieve spec. This makes it extremely easy
to locate records based on the value in one
or more fields. If what you want is not a
complete field value you might want to
use wildcard characters or an 'either/or'
search for example then just continue
typing or edit the value that Autocomplete
proposes.
Autocomplete can be turned off in the
Sesame.ini file, and also at the View menu.

Figure 3. Turning off Autocomplete

Templates and searching


When searching a templated layout element, you must include the template
characters, i.e. search just as the data appears. You may need to use literal characters
if the template uses characters that have a special meaning in Sesame searches. For
example, to find templated phone numbers with the area code 330 you would need to
use:

Telephone: \(330\)..

A note on sorting
The records in the result set are likely to be in random order. This is because Sesame
does not store the records in sorted order. For a small database, the records in the
result set are likely to be returned in the order in which they were added to the
database. For a larger database, they might appear in different orders as you work
with the database.

The rule is that if you want your result set sorted, you sort as part of the retrieval
process. You can use the Sort Spec either before running the search, or afterward.
Sorting is covered at the end of this section.

250
8 SEARCHING & SORTING

The Result Set


Retrieved records, as in the example above, constitute a result set. A result set is one
or more retrieved records. Sesame works on the concept of obtaining a result set and
then performing any actions on it that you may require. These actions may be
including the result set records in a report, printing them, mass updating them, or
deleting them. You can perform multiple actions on a result set that is, unless you
delete all the records.

Q&A
Q&A is different. You first tell Q&A what you want to do perform a
mass update, for example then Q&A supplies a retrieve spec just for
that task. If you want to mass update a particular group of records and
then include them in a report, you have to fill in two retrieve specs one
for the mass update, and another one for the report's own retrieve spec.
There is only one thing you can do with a Q&A "result set," and that is,
print it, by pressing Ctrl-F2. In this context, the Q&A documentation uses
the term "stack" of records, which is the equivalent of Sesame's result set.

Running the search


When you have entered your search criteria in the Retrieve Spec, you can tell Sesame
to run the search in a number of ways. You can:

Press F10.
From the menu tree select Search Menu / Search Commands / Retrieve New
Results.
Select Run from the sort window. (Sorting is covered later.)
Press Alt-R, the shortcut key for Run Sort.

There is yet another method. You can select Find First Match from the Search
Commands menu. This is useful if you are searching a very large database for one or
two specific records. Rather than search the whole database, Find First Match does
just what the name implies retrieves the first matching record quickly. If this is not
the right record, you can select Find Next Match from the Results Commands menu
and Sesame will show you another record the next one that matches your criteria.
There is also a Find Previous Match command.

Any sorting you may have specified is ignored when you use Find First Match.
The Find Next Match / Find Previous Match commands are unavailable unless
you run the search initially with Find First Match.

Q&A
Q&A's default search method is the equivalent of "Find First Match"
unless you sort the records or are searching on a speedy field.

Moving through the result set


You can move through the result set by ..

251
8 SEARCHING & SORTING

Pressing F10 to go forwards / F9 to go backwards


Selecting Navigation/Advance Record (F10) or Previous Record (F9) from the
menu tree

Using the navigation buttons on the toolbar:

Entering criteria
Sesame's searching works on the principle of query by example. You have a retrieve
spec, which is a blank form. Using the field or fields you want to search on, you type
an example of what you are looking for, then run the search. In other words, if you
want to retrieve the records where the last name is Smith, you simply type smith into
the Last Name field and run the search.

Although the word "field" is used here, strictly speaking you are entering your search
criteria into one or more layout elements on the form, not fields per se. But the term
field is commonly used in this context, and it will be here as well.

The values or sample data you type in at the retrieve spec constitute your search
criteria.

Q&A
Q&A users will be happy to find that search criteria in Sesame are, for
the most part, identical to Q&A's.

Upper or lower case?


Case doesn't matter when typing your search criteria for normal searches. (Sesame is
almost universally case blind, with few exceptions such as passwords). If you're
searching a last name field for "Anderson," you can type anderson, ANDERSON or
aNDerSoN. If you need to, you can perform special case-sensitive searches. These will
be covered later.

Searching special Layout Elements


Your form might contain special layout elements such as check boxes and combo
boxes. These can be searched, too. They will be covered under Searching Special
Layout Elements later in this chapter.

Searching a single field


To search on one field, you simply type your criteria into that field and run the search.

The examples below are from the Customers.db sample application. You will find that
most of the examples in this chapter will work if you search the Main Form in this
application.

Examples:

Last: jones
Finds all records where the Last field consists of the text Jones (any capitalization).
252
8 SEARCHING & SORTING

City: chicago
Finds all records where the City field consists of the text Chicago (any capitalization).

Note that the field contents must consist entirely of Jones or Chicago to meet the
criteria. Sesame does not automatically perform "wildcard" searches. Wildcard
searches can easily be performed if you need them, and these will be covered later.

Searching multiple fields


When you type criteria in two or more fields, Sesame will find and return the records
that match all of your criteria. For example:

Last: wilson
City: los angeles

These two criteria find the records where the Last field contains just Wilson
and the City field contains just Los Angeles. Wilsons elsewhere are not returned; nor
are other last names in Los Angeles. Both must match.

You can enter criteria in as many fields as you like. The more fields you search on, the
more restrictive the search, and the fewer the records Sesame will return in the result
set.

See later in this section for advanced criteria using mixed "and" and "or" searches
across fields.

Performing a new search


Once you are looking at a result set you can then do the following:

Edit the information in the records.


Perform many different actions on the result set for example, mass update,
export or mass delete. (See Adding and Editing Data.)
Run a report. (See Designing and Using Reports.)

When you are finished with a particular result set, you can either abandon further
searches, or return to the retrieve spec to modify or further refine your search criteria.

To abandon the search, press the Escape key or select Exit Search from the Search
Update menu. If the current record has been changed but not yet saved, Sesame will
ask you to confirm that you want to exit without saving changes.

To modify or refine a search, do not press Escape to abandon the search. Instead,
press the F7 shortcut key or select Search from the Search Update menu. Sesame will
return you to the retrieve spec with your previous criteria retained. You can then make
any changes you like and run the modified search. This can be a handy method of
performing several slightly different searches, but be aware that all criteria are
253
8 SEARCHING & SORTING

retained. For example, there may still be a "Y" in a field on a part of the form that is
not visible.

Clearing a retrieve spec


If you want to be sure that the retrieve spec is blank, press F3 or select Clear Form
from the Search menu.

Search criteria essentials

Field types are important


You must take into account the data type of the field you are searching on. Layout
elements can have formatting that affects the way the actual data is displayed. When
preparing to search a date field, for example, you can type the date in any way that
Sesame can recognize it as a date. So that even though, on the form, the date might
be displayed as December 28, 2007, you can type your criteria as 12/28/07 and
Sesame will understand what you're after.

Similar rules apply for a currency field. You can enter criteria of 6500 and Sesame will
find the records where the amount is actually displayed as $6,500.00. You don't need
to enter the currency symbol, the comma, or the decimal places (though you can if
you like). However, if you had one or more records in the database where a text field
contained "$6,500.00", then you would have to type $6,500.00 exactly at the retrieve
spec in order to find them.

Date fields and years


You can omit the century if the date(s) you are searching for are between certain
years. This is determined by your operating system. Settings for determining at least
the upper threshold can be adjusted in Windows Control Panel / Regional Options /
Date. The default for Windows 2000/XP is for two-digit years to be interpreted as a
year between 1930 and 2029.

If the date(s) you are searching for are in the current year, you can omit the year
altogether. Accordingly:

Jul 4
july 4
7/4 (U.S.)
7-4 (U.S.)
7 4 (U.S.)

will all retrieve the records where the date is July 4, 2007 if the search is run in 2007.

Searching unbound layout elements


You cannot search on unbound layout elements. An unbound layout element is one
that is not linked to a database field, but instead displays, for example, a calculated
value. Criteria entered in unbound elements will be ignored.
254
8 SEARCHING & SORTING

Special search characters


The most commonly used optional search characters are these:

; Means OR. Used to separate a list of alternative criteria. For example,


chicago; los angeles means you want to find records where the city is Chicago
OR the city is Los Angeles.

/ Means NOT. For example, /chicago means not Chicago.

= Means empty the field is blank.

Therefore:

/= Means NOT empty a field that has any value in it.

Important Note: The "/" symbol for NOT makes all that follows negative.
Accordingly:

/chicago; las vegas

means not Chicago and not Las Vegas.

Q&A
Q&A users will be happy to find that the search criteria in Sesame
including these special symbols are, for the most part, identical to Q&A's.

Tables 1a and 1b show some examples of basic searches. Table 1b shows how to use
arithmetic operators.

Type This... To Retrieve... Data Type

smith Smith Text, keyword

16 nov 05 or November 16, 2005 Date


Nov 16 2005 or
November 16
2005 or 16.11.05
or 11/16/2005
etc.

1236 1,236 or 1,236.00 Number

714.56 $714.56 Money

/ philadelphia Anything but Philadelphia Text, keyword

255
8 SEARCHING & SORTING

= Empty field All

/= Field NOT empty All

smith;brown Smith or Brown Text, keyword

/chicago;new All except Chicago and New York Text, keyword


york
Table 1a. Basic search criteria.

Operator What it Means Example

> Greater than 2>1

< Less than 2<3

>= Greater than or equal to 5 >= 4 and 4 >= 4

<= Less than or equal to 3 <= 4 and 4 <= 4

= Equal to. Not required for basic searches.

<> Not Equal to. Behaves identically to / (not). 2 <> 3


Table 1b. Arithmetic operators.

The range operator


In Sesame searches, two periods ("..") sometimes called the "dot-dot" operator
has two distinct uses: as a wildcard character for text searches (see below) and to
imply a range for non-text searches. Sesame works out what you mean from the
context.

In number, money, date or time fields, ".." indicates a range. When typed before the
criteria, it means up to. When used after the criteria, it means upwards. Between two
sets of criteria, it means between. Note that the ".." operator is the equivalent of >=
or <= in that it includes the limits. Accordingly, in the simple example of a number field
containing integers:

3..6 will retrieve 3, 4, 5 and 6. (In a number field, NOT in a text field)

The range operator can be used with numbers, dates, times, and text. You will only
obtain correct results if the field data type is correct for the way you are searching.
Dates or numbers entered into text fields cannot be searched on or sorted as dates
and numbers, only as text. So, 3..6 in a text field would be interpreted as a wildcard
search (see below) and retrieve the values 396 and 36-24-36, for example.

256
8 SEARCHING & SORTING

Table 2 below shows examples using operators and ranges.

Enter This... To Retrieve... Data Type

>01 15 06 or Dates after January 15, 2006 Date


>jan 15 2006
etc.

>=01 15 99 Dates after January 14, 1999 Date

<2000 Less than 2,000 Number

>16:45 After 4:45 pm Time

78.50.. Greater than or equal to 78.50 Number

..1000 Less than or equal to 1,000 Number

600..700 Numbers from 600 through 700 Number

23 feb 06.. or From February 23, 2006 onward Date


02/23/06..
etc.

14 mar..8 jul Dates between March 14 and July 8 inclusive in Date


the current year

>wi All entries after Wi in a telephone directory, for Text, Keyword


example: Wilson, Woodruff, Wright,
Zimmerman

>wi..<Z All entries after Wi but before Z in a telephone Text, Keyword


directory, for example: Wilson, Woodruff,
Wright and Xum, but not Zimmerman
Table 2. Operators and ranges.

Max and Min


To find the highest or lowest values in a field, use Max or Min followed by the number
of records you want to retrieve. Table 3 shows some examples.

Enter This... To Retrieve... Data Type

max 5 Finds 5 records with the latest dates sorted by Date


date.

257
8 SEARCHING & SORTING

Min 10 Finds 10 records with the lowest numbers sorted Number


by number.

min 20 or Finds 20 records, nearest the start of the alphabet, Text


min20 in ascending order alphabetically.

max 1 Finds one record, the last one alphabetically. Text

Max Someone named "Max". Text, Keyword


Table 3. Max and Min searches.

Following are the rules for using Max and Min in searches:

Max or Min must be followed by a number, separated by an optional space


for example: Max 2 or Max3.
If you use Max or Min, the retrieval is automatically sorted on the contents of
the field.
Max and Min always retrieve the specified number of records, not the number
of values.
Max or Min is applied last, after any other search criteria specified in any other
field(s).
Max or Min can only be applied to one field. If you use Max or Min in
more than one field, the results will be unpredictable.
Max and Min searches can take time on very large databases.

Q&A
In Q&A, Max or Min by itself implies the number 1. In Sesame, you must
specify the number. So use "Max 1" rather than just "Max".

Wildcard characters
A wildcard character in a search is rather like a joker in a pack of playing cards it
can represent anything. Sesame supports two wildcards:

? Represents any single character, which must be present.


.. (Two periods). Represents any character(s), or none.

Q&A
When searching, the "?" and ".." wildcard characters work the same way in
Sesame as they do in Q&A.

Table 4 shows some examples of using these wildcards.

258
8 SEARCHING & SORTING

Enter This... To Retrieve... Data Type

dal? Dale, Daly, etc. but not Dallinger Text, keyword

w??d Ward, Wood, etc. but not Wingfield Text, keyword

??? Day, Cox, Lee, etc. Text, keyword

sha.. Sharp, Shaw, Sharman, etc. Text, keyword

..son Anderson, Jackson, Wilson, etc. Text, keyword


and also simply "son"

b..er Baker, Becker, Buckmiller, Branch Text, keyword


Manager, etc.

.. beach (Note the Daytona Beach, Huntington Beach, Long Text, keyword
space) Beach, etc.
but not Beachview, Longbeach, etc.

..west.. Westerville, Key West, newest, Text, keyword


Rowestoft, etc.

1-212.. Phone numbers or the like beginning Text, keyword


with 1-212

93.. Zip codes or the like beginning with 93 Text, keyword

..s..b..m.. Sesame database Manager, Text, keyword


Hey - somebody's home, etc.
Table 4. Wildcard search examples.

Note that the ".." symbol has two distinct uses: as a wildcard character for text
searches, and to imply a range for non-text searches. Sesame works out what you
mean from the context.

Advanced searches

Already in this section all the techniques and methods needed to perform everyday
searches have been covered. What follows are additional menu commands and
additional search syntax devices to enable you to perform advanced searches. Some
of these you might use regularly. Others are infrequently used or even arcane. You do
not need to learn them all.

Using "OR" across fields


You have seen that to find records containing Smith or Brown in the Last field, you
would type this in the Retrieve Spec:
259
8 SEARCHING & SORTING

Last: smith ; brown

This specifies OR for the field. To specify OR across fields, you need to change
Sesame's search logic. By default, Sesame's search logic is AND across fields:

"Find the records where the state is MA and the first name is Mary."

This search mode is referred to as Meet ALL restrictions. To change the search mode,
select Search Options / Meet Any Restriction from the menu tree at the retrieve spec.
The text on the status line at the bottom of the screen will change as shown below.

Figure 4. Changing Search mode. Notice the status line at the bottom of the screen.

Q&A
This is the equivalent in Q&A of pressing Ctrl-F7 at the retrieve spec and
changing the setting from the default "Meet ALL of the Restrictions" to "Meet
ANY of the Restrictions".

260
8 SEARCHING & SORTING

Here's an example:

If you perform the above search using the standard search mode in the Customers.db
sample application, you will get just one record for a Mary in Massachusetts.

After changing the search mode to Meet ANY restriction, the same search will turn up
13 records seven people in Massachusetts and six Marys, one of whom lives in
Massachusetts.

With search mode set to Meet ALL restrictions, the more fields you type
criteria in, the fewer the records you will retrieve.
With search mode set to Meet ANY restriction, the more fields you type criteria
in, the more records you will retrieve.

Here are a few additional points regarding search mode:

The search mode is stored with a saved retrieve. See the heading Saving
Searches below.
Sesame's default search mode is Meet All Restrictions. This is seen on the
status line as Setting search mode to match ALL search restrictions when you
first open the retrieve spec.
If you clear the retrieve spec by pressing F3, for example, the search mode is
retained until you change it.
Exiting Search/Update resets the search mode to the default.

Other Menu Commands to Run a Search

At the retrieve spec you enter criteria


(search examples) and press F10 or
select Retrieve New Results from the
Search Commands menu. That is all
you need to run a basic search.

However, there are twelve commands


on this menu, each of which will run
the search, but in different ways.

These are described in detail in the


rest of this section below. Table 5
shows a summary.
Figure 5. The Search Commands menu

261
8 SEARCHING & SORTING

Search Commands . .

Retrieve new Results (F10) Normal search

Add to Current Results Add records retrieved in this search to the previous
result set

Next Matching Record in Apply this search to the current result set, not the
Current Results whole database, and find the first record that
matches. Leave the result set intact

Search in Current Results Apply this search to the current result set, not the
whole database, to produce a new result set

Remove From Current Remove records retrieved in this search from the
Results previous result set

Inverted Search Search for records that DO NOT meet these criteria

Find First Match Find the first matching record rather than all of them

View Current Results View the current results

Universal Search Perform a normal search, but across all fields on the
form

Simple Search Perform a weighted search across all fields on the


form. Uses implied wildcards. Sorts the records by
how well they match the criteria. Simple Search is
an immensely useful tool.

Duplicates Search Search for duplicates, matching fields as per the


current duplicates spec. Retrieves only the duplicate
records, not the 'original' record in each case.

All Duplicates Search Search for duplicates, matching fields as per the
current duplicates spec. Retrieves the duplicate
records, and also the 'original' record in each case.
Table 5. The Search Commands menu commands.

Searching all fields: Simple Search & Universal Search

Sesame offers two easy ways to search the database across all text, keyword and
image fields. These are:

Universal Search Search across all fields for the search string. Wildcard
characters can be used but have to be added.

262
8 SEARCHING & SORTING

Simple Search a weighted search. This is like universal search in that it


searches every field, but it also searches within every field also. Uses implied
wildcards. Uses a method similar to that used by an internet search engine.

Universal Search and Simple Search are quite different to the other searches in that
the retrieve spec is not used, even though they are accessed from the retrieve spec.

Sesame offers two "web-type" search facilities. Simple Search is an easy way to
search for words or names without knowing which field they might be in. Simple
Search is described below.

There is a third type of search that searches across multiple fields, but this time
searching just one record at a time the current record. Having retrieved records,
Find on This Form searches the current form/record for text, just like you can search
a web page. This is described on page 283.

Simple Searches
Simple search behaves like a web search engine search. You type one or more words
or names into the dialog and Sesame searches the whole database for records that
include those. The records are ranked by how well they match, with the best matching
records first. So a record that has the search string occurring several times even in
different fields will be shown ahead of one that has it only once. Likewise a record
that has an exact match for the search string will be ranked ahead of one that has the
search string included in longer words or names.

There are no special search characters, and multiple words are separated by spaces.

To perform a Simple Search, first go to the retrieve spec then, from the Search
Commands menu, select Simple Search.

Figure 6. Using Simple Search.

263
8 SEARCHING & SORTING

Examples of Simple Search, using CUSTOMERS.DB

Figure 7. Using Simple Search.

Criteria: house produces 4 records. The first of these is Marjorie Baker. She lives
in School House Lane, and her email address is m_baker@schoolhouse.cs.com. This
record comes first because "house" appears as a separate word, and there are two
occurrences of "house" within the record.
The next record is for someone whose position is Warehouse Manager
The next lives at West Rittenhouse Square
The last record is Barbara Mendenhouse

Criteria: will hill produces, in order

* someone named Will Hill


* someone named Will who lives in Cherry Hill
* someone whose last name is Hill and whose email address includes hill
* a couple of people whose last name is Hill
* someone named Williams who also has Williams in their company name and email
address
* a couple of dozen records where will or hill are part of a name, place-name etc.

Simple search is exactly that. You don't have to learn any syntax rules. There is only
one refinement you can make. If you want to concentrate the search on a term that
consists of multiple words, put the words you want to keep together inside quotes

264
8 SEARCHING & SORTING

Figure 8. Another Simple Search.

Safety and Officer entered as two words find many records that contain one word or
the other. Putting the criteria in quotes as in the figure retrieves just one record for
someone whose position is "Company Safety Officer".

Like all Sesame searches, Simple Search is case blind. It makes no difference whether
you enter criteria in lower case or UPPER CASE.

Simple Search and Sorting


Simple search produces a "weighted" result and returns the records in weighted order,
unless a sort spec has been specified, in which case the sort spec takes precedence.

Inverted Search
Selecting Inverted Search from the Search Commands menu retrieves the
complementary set of records to an ordinary search. Suppose your criteria were as
follows:

State: AZ; CO

An ordinary search using Customers.db would return just the 11 records in Arizona
and Colorado. An inverted search would return 371 records all of the records except
those 11.

Inverted searches cannot be saved.

Q&A
This is the equivalent in Q&A of pressing Ctrl-F7 at the retrieve spec
and changing the setting from the default "Select those records that DO..."
to "Select those records that do NOT...."

265
8 SEARCHING & SORTING

Universal search

Universal Search gives you a way of


searching all text, keyword and image
fields at the same time. This can prove
particularly useful if you just know that
there is a reference to a person in a
database, but you're not sure whether it
is in the main contact field, the comments
field, or any other field.

To perform a universal search, first go to


the retrieve spec then, from the Search
Commands menu, select Universal
Search.
Figure 9. Using Universal Search.

The Universal Search dialog is displayed. Enter the criteria you want to use to search
across all fields, then click on Accept.

Figure 10. The Universal Search dialog.

The result set Sesame returns will be all those records that match your search criteria
in any text, keyword or image field. In the example above shown in Figure 5, this
would retrieve all records containing West, such as 110 West Michigan St in the Add1
field and Westerville in the City field, as well as a Last Name containing the characters
west.

Following are a few additional points about Universal searches:

The criteria are matched against the entire field contents.

Wildcards can be used, but you must add them. Without wildcards Universal
Search matches what you type to the complete contents of a field.

The retrieve spec, if filled in, is ignored. This is an alternative to a regular


search.

266
8 SEARCHING & SORTING

Universal search is a text search. It ignores number, date and money fields
and the like.

Universal search does, however, search Image Boxes, performing a text


search on the stored image filename.

Like other Sesame searches, Universal search is case insensitive.

Q&A
Q&A (DOS) does not support any type of universal search.

Keyword searches
A keyword search is a special kind of search adapted to a keyword type field. A
keyword field is one that permits multiple entries, each separated by a semicolon
(";"). Each such entry can then be treated by Sesame as though it were the only entry
in the field. The example used in Customers.db is the Hobbies field. A person can have
many hobbies, and they are listed in the keyword field this way:

Hobbies: Golf; Swimming; Football; Dancing

If this were an ordinary text field and you wanted to find all the people who were into
football, you would need to use wildcards, like this:

Hobbies: ..football..

You would need the ".." because the word Football could be anywhere in the field. It
could be the only entry, or at the start, the end, or anywhere in the middle.

In contrast, each semicolon-separated entry in a keyword field behaves as though it


were the only entry. So to search for the footballers, you'd simply type "football"
(without the quotes) in the Hobbies field in the retrieve spec, and Sesame would
retrieve all the records, regardless of any other hobbies in the field.

Keyword searches with multiple criteria


Keyword fields offer powerful search options for finding entries in combination. You
can use OR and AND for searching in a keyword field.

; Means OR.

& Means AND when used as the first parameter. Using & with ; changes the
meaning of ; to AND as the example in Table 6 shows.

Q&A
Keyword searches in Sesame work the same way as in Q&A.

267
8 SEARCHING & SORTING

Type This... To Retrieve...

Football Football

..ball Football, baseball, etc.

football; golf Football OR golf

&football; golf Both football AND golf

/tennis All except tennis

/tennis; golf All except tennis and golf. (Same as performing inverted search
for tennis;golf)
Table 6. Keyword searches with multiple criteria.

The power of these searches is that the order of the entries in the keyword field does
not matter. In the third example in Table 5, golf can come before football in the
Hobbies field and the record will be included in the answer set.

The following section contains further examples of advanced keyword field searches.

More Special search characters


Here are several more characters that have a specific meaning in Sesame searches.
(The more commonly-used ones have already been described.):

\ Means "treat the next character as a literal character."


] Means "treat what follows as a text string."
& Means AND used to string together multiple criteria.
` Means "make this a case-sensitive search."
~ Means "make this a sounds-like search."

\ Suppresses the special meaning of characters such as &, =, .. and so forth, and is
used immediately before such a character. It affects only the single character following
the \. You can use \ anywhere in the criteria and you can use it more than once.
Examples of use include finding records that have been inadvertently added by
entering retrieve criteria in Add mode, and searching for characters such as the
ampersand ("&") and equals ("=") sign.

] Performs a text search in a non-text field. The ] must be the first character of the
criteria. There are limited opportunities to use this special search character because
Sesame's strict data typing prohibits the entry of invalid information in number and
date fields, for example. The primary use of ] is to perform wildcard searches in date
fields. This is possible because the underlying value stored in the date field
regardless of format is stored in YYYY/MM/DD (2007/12/15, for example) format.
268
8 SEARCHING & SORTING

By beginning the search criteria with ] you can use Sesame's regular wildcard
characters. This will be shown in the examples below.

& means AND. It is used to indicate that more than one expression in a field must be
true for a record to be retrieved.

An example of how & might be used is to search the Add1 field in the Customers.db
sample application for records containing both "in" and "to" in either order:

Add1: ..in.. & ..to..

This finds eight addresses such as: "..Pinto Drive.." and "..Washington..", and also
"..Torrey Pines.."

Compare this to the following search criteria:

Add1: ..in..; ..to..

This retrieves 58 records, all containing either "in" or "to".

` The backtick defines a case-sensitive search. The Backtick (`) character is found on
the key to the left of the number 1 at the top of your keyboard. It should not be
confused with the single quote mark (') found towards the bottom right of your
keyboard.

By default, almost all of Sesame is case-blind. This means it makes no difference


whether you use lower case or UPPER CASE. An exception is passwords. So, normally,
to retrieve "New York" records, you can type in new york, NEW YORK or nEw YoRk. By
adding ` as the first character of the criteria, all that follows will be matched on a
case-sensitive basis.

You can format a text layout element on a form to display its data in UPPER CASE or
lower case, regardless of how it is typed in. For normal searches, this does not matter,
as Sesame is case-blind. In contrast, for case-sensitive searches using the ~ symbol,
the search criteria are matched against the actual value stored in the field, not the
formatted value as it appears in the layout element.

~ (Sounds-like Search)
Sesame incorporates a Soundex Search construct for text fields where you can search
for records that "sound like" instead of match the exact spelling of a retrieve spec.
Precede the sounds-like string with the tilde character (~). E.g. ~smith would return
records like Smith, Smyth, Smeth, etc. Use care to review the result set when using
this feature.

269
8 SEARCHING & SORTING
Q&A
In Q&A the tilde character (~) is used to specify a soundex or
phonetic search, called a "sounds like" search, as it is in Sesame.

Table 7 shows some usage examples of the special search characters covered in the
preceding paragraphs.

Enter This... To Retrieve...


..\.\. PROF..

..\&.. Mr & Mrs

..\;.. cars; vans

]2000/10/.. All dates in October 2000

]2000.. All dates in 2000

]2000/??/01 All dates being the first of any


month in 2000

>100 & <120 Numbers between 100 and


120

..in.. & ..to.. washington, Torrey Pines, etc.

Compare this to

..in.. ; ..to.. prince, windy, Dayton, tower,


etc.

`bbc bbc but not BBC

`Lant.. Lantica but not LANTICA

~hanes Haines, Haynes, Heinz, Heneks

Keyword fields

golf & tennis Both golf and tennis

tennis & /football tennis but not football

tennis & /golf; dancing tennis but not golf or dancing

]tennis Tennis and nothing else


Table 7. Examples of special search characters usage.

270
8 SEARCHING & SORTING

Refining the result set


Sesame allows you to do more to refine and work with a result set of retrieved
records. There are menu commands you can use to do this on the Search Commands
menu seen at the retrieve spec. There is also a menu tree command to remove a
single record you are viewing in Search/Update mode. (See Figure 11.)

Commands on the Search Commands menu to modify the result set.

Here are the result set commands you can use:

Add to Current Results


Search in Current Results
Next Matching Record in Current Results
Remove from Current Results
View Current Results

Figure 11. Commands to modify the result set.

Q&A
Q&A for DOS has no means to refine the result set. Each search needs to
be started from scratch.

Add to Current Results


After performing a search and producing a result set, you can return to the retrieve
spec and change your criteria. This time, instead of pressing F10 to perform a new
search, you can click on Add to Current Results. Sesame will add any newly retrieved
records to the existing result set.

To return to the retrieve spec after viewing your records, you can press F7 or select
Search from the Search/Update menu.

To clear the retrieve spec, you can press F3 or select Clear Form from the
Search/Update menu.

For example, suppose you search Customers.db for Columbus in the City field. Sesame
hands you the three matching records. You now return to the retrieve spec (F7), clear
it (F3), type Los Angeles in the City field, and click on Add to Current Results. You will

271
8 SEARCHING & SORTING

now have five records the three for Columbus and the additional two for Los
Angeles.

Search in Current Results


You can alternatively apply the new search to the current result set, rather than all the
records, by selecting Search in Current Results. This is commonly referred to as drill-
down search.

Here's an example of where this drill-down search could prove useful.

Suppose you want to retrieve all those customers who are in the City of New York, or
the States of Connecticut or New Jersey. However, you only want to include those
where the Currency field contains an amount greater than $500.00. You can't do this
in one retrieve without using programming or a drill-down search.

Here's how you can do it in Sesame:

Run your first search with Search Options set to Meet Any Restriction.

Figure 12. Search stage 1note Meet Any Restriction on status line at bottom.

In the retrieve spec, type in the following and run the search:

City: New York


State: CT; NJ

This retrieves all the records that meet your geographical criteria. Now you need to
follow-up with the money restriction. Return to the retrieve spec (F7), clear it (F3) and
type in the following:

272
8 SEARCHING & SORTING

Currency: >500

This time, click on Search In Current Results and you will have the records you need.
(See Figure 13.)

Figure 13. The final result set, shown in table view.

Note that Search in Current Results produces a NEW result set compare with Next
Matching Record in Current Results(below) which leaves the result set unchanged but
shows you a certain record.

Next matching Record in Current Results


Sesame gives you a search feature found on the Retrieve Menu tree called "Next
Matching Record in Current Results" and a "Next Matching Record" option on the
Search/Update Navigation menu, that allow performing a sub-search within a set of
retrieved records, without eliminating records from the result set the result set
remains unchanged compare with Search in Current Results (above) which
produces a NEW result set.

Example:
This search: State: PA
when run produces a set of records where the state is PA. There are 64 of them in the
Customers.db sample application.

Return to the retrieve spec (using the F7 keystroke or selecting Search (F7) from the
Search/Update menu), clear the "PA" from the state field and enter:
273
8 SEARCHING & SORTING

Hobbies: tennis (See Figure 14)

Clicking Next Matching Record in Current Results will show you a record in this
result set of customers in Pennsylvania for a customer whose hobbies include
tennis. This might be record 10 of 64. Now you are in Search/Update mode. There is
an equivalent menu item here named Next Matching Record. Selecting this will show
you another tennis customer in PA (record 12 of 64), repeat and you see record 25 of
64, then record 39 of 64. Repeating this beyond the last matching record will take you
to the first matching record in the result set and so on.

Figure 14. Viewing records in this result set where hobbies includes tennis

Remove from Current Results


This is the opposite of Add to Current Results.

Suppose you search Customers.db for NJ in the State field. Sesame finds 32 records.
Out of these, 18 show P in the Live_Prospect field, indicating a prospect rather than a
customer.

If you then return to the retrieve spec (F7), clear it, type P in the Live_Prospect field,
and click on Remove from Current Results, you will now have only 14 records the
32 for New Jersey minus the 18 for prospects.

View Current Results


You can view your current results by clicking on View Current Results when at the
retrieve spec. This is a convenient way to see how refinements to your result set are
progressing during a complex series of searches. Press F7 to return to the retrieve
spec with your current result set retained. Pressing Escape abandons the search.

The above search methods are all activated with the retrieve spec showing. They act
on the set of records returned by your search criteria. There is another method that
allows you to further refine your result set Remove from Results.

Remove from Results


Remove from Results is used whilst viewing records, not at the retrieve spec
compare Remove from Current Results.
A single record can be removed from a result set by clicking on Remove from Results
on the Record Commands menu in Search/Update. (See Figure 15.) This allows you to
further refine the result set.

274
8 SEARCHING & SORTING

Figure 15. Removing one record from a result set.

Remove from Results removes only the current record the one you are viewing. It
can be useful, for example, to remove individual records from a group of records you
are about to export. The record is not deleted from the database, it is only removed
from the current result set.

Duplicates Search / All Duplicates Search


Sesame has comprehensive features for identifying duplicate records. These (including
the duplicates searches) are covered in the section Duplicate Records. See page 218.

Searching Special Layout Elements


You might have some special layout elements on your form, like check boxes and
combo boxes. These can be searched, too.

Check boxes
A check box represents a Yes/No field, also called a Boolean field. A check in the box
indicates Yes, True, On or 1. If the box is unchecked, it indicates No, False, Off or 0.

Sesame check boxes are tri-state, meaning that they have a third setting unknown.
It is the equivalent of the underlying Yes/No field being null or blank.

Searching check boxes is conceptually identical to searching a text element you


type or otherwise show an example of what you are searching for. See Figure 16.

Figure 16. Searching Check Boxes for: No, Yes, and "omit from search"

The unknown setting the third (solid, raised) check box in Figure 11 is not a
search criterion, but disregards that layout element. It is the equivalent of leaving a
text box empty, which tells Sesame: "I don't care what is in this field," meaning that
Sesame will retrieve records where that check box is in any of the three states.

275
8 SEARCHING & SORTING

Combo boxes
To search a combo box, navigate to the
combo box or click in it, press the down
arrow, and the combo box will expand to
show the available entries.
Select one and press Enter. Then run the
search.
Combo boxes also allow you to enter
other text not on the pick-list (subject to
any restrictions the form designer may
have imposed on this layout element). To
search for other text, simply type it into
the combo box at the retrieve spec as if it
Figure 17. Searching a Combo Box. were a normal text box.

List boxes

To search a list box, simply select one of


the entries. (See Figure 13.) To clear the
list box, click on the selected item. With
no item highlighted, the list box plays no
part in the search.

Figure 18. Searching a List Box.

Radio button groups

To search a radio button group, simply


select one of the entries. (See Figure 14.)
To clear the radio button group, click on
the selected item. With no item
highlighted the radio button group plays
no part in the search.

Figure 19. Searching a radio button group.

276
8 SEARCHING & SORTING

Menu Buttons
A menu button is like a combo box but without the facility to be able to type your own
entry. You must select one of the available entries. The list of values is entered in
Designer. If your menu button is like the example shown on the left in Figure 20, then
you might have problems when you come to search the form. You will have to select
one of the available values and include that in the search. It is easy to get around this
situation. In Designer you simply add . . (two periods) as the first entry in the list of
values. This way, at the retrieve spec, this entry is the default value (it means "any
valid entry"), and so the menu button is excluded from the search criteria. If you want
to search for one of the entries you simply select it, as in the left-hand example.

Figure 20. Searching an image button, and with a ".." entry

Image searches
Sesame supports image fields. These are fields that store graphical images or pictures.
To be precise, the image files themselves are not stored in the database, only their
paths and filenames. An image field is represented on a form by an image box which
displays the image. You can search these image boxes.

Running an image search


Open a form that contains an image box. The examples shown below will use the
Gems.db sample application on the Sesame CD. The retrieve spec shows an empty
image box. You don't type into this image box. Instead, you use the image browser, a
special dialog for working with images boxes. You can open the image browser by
either of the following two methods:

Double-clicking on the image box.

Placing the cursor in the image box and pressing spacebar.

(See Figure 21.)

277
8 SEARCHING & SORTING

Figure 21. Sesame's image browser, displaying diamond.jpg.

The image browser serves a number of purposes. In Search/Update mode it tells you
the stored filename and path of the image file for that layout element. When
searching, it allows you to search for records by performing a text search for the
filename. It also allows you to view image files both for storing and retrieving them.

Searching for images graphically


With the image browser open in Search mode, navigate as necessary to where your
image files are stored. You can then click on any filename to display the image in the
Preview box. (See Figure 21.)

You can alternatively use the arrow keys to highlight a filename and then press Enter
to display the image.

When you find the picture you want to search for, click on Accept. The path and
filename for that image are entered into the retrieve spec ready to run the search.
(You cannot see the pathname.) You then run your search in the usual way. Any

278
8 SEARCHING & SORTING

records that meet the criteria the specified filename in that image box will be
returned.

In this way you can view a library of images photos of people, houses, and the like.
Without knowing the filename, you can retrieve the record or records containing a link
to that image.

Figure 22. The Gems form displaying emerald.jpg.

Searching for images by filename


Open the image browser in Search mode as described above. This time, use the text
box under the Preview window to enter all or part of the images filename. Wildcards
are acceptable and useful here.

279
8 SEARCHING & SORTING

For example, to find all records with images where the image filename starts with A,
you would enter the following in the Select an image as search criteria box and click
Accept:

a..

This search in Gems.db will retrieve the records for Alexandrite, Amethyst and
Aquamarine.

To find records where the image box contains pictures with House anywhere in the
filename, you would type:

..house..

Notes on image searches


Image searches are "normal searches" in that you can make use of the facilities on the
Search Commands menu at the retrieve spec, such as Inverted Search, Search Within
Current Results, Add to Current Results and so forth.

Image searches can also be saved and re-used in the usual way. (More on this below.)

Universal Searches also work along with text fields, image boxes are included in a
universal search.

The location where Sesame will look for images is defined in Designer in the
Application Property Manager found on the Application menu. The image path as
defined there is relative to the current working directory. So if, for example, the image
path is defined as simply Pics, and the current working directory is C:\Sesame, then
Sesame will look for image files in the C:\Sesame\Pics directory.

This will be the starting point for the directory tree seen in the image browser. You can
browse for images in the image path folder and any folders under that folder.

Programmed retrieves
Though Sesame offers a wealth of record retrieval tools and search options, a search
you need to perform may be more complex than those already described. Perhaps you
need to retrieve records based on a calculation or by comparing the values in two or
more fields; or save a retrieve that finds records dated the previous month, no matter
what the current date might be. You can perform these kinds of calculated retrievals
using programmed retrieves.

Programmed retrieves are especially useful when attached to a report. This way, the
report can always include records from the current month, previous month, year to

280
8 SEARCHING & SORTING

date etc, without modification. This is done by referencing the current date using
@Date or @ServerDate(). Without a programmed retrieve the person running the
report would have to manually input the required dates each time the report was run.

A programmed retrieve requires the use of a programming expression. When writing


such expressions, you must use FIELD NAMES, not layout element names. This is the
sole exception to the rule that you only ever refer to layout element names in Sesame
runtime. Often, field names and layout element names are the same. But that is not
necessarily always the case.

Q&A
In Q&A, you can type logical field numbers (#1, #2, etc.) in fields
and refer to them as such in a retrieval expression. In a Sesame
retrieval expression, you must refer to fields by Field Name.

To search using a programmed retrieve, you type the expression in a text box (field)
on the form, where you would normally enter your search criteria. Programming
expressions, however, must be typed inside French braces, like this:
SomeField: { expression }
Most programming functions from the Sesame Programming Guide can be used in
programmed retrieves, but not all. The requirement is that the expression within the
French braces must (1) evaluate to a value that can be compared to the content of a
layout element in the current form, or (2) evaluate to true or false for the record.

For the former case, you type an equals sign ("=") in front of the opening French
brace in the layout element (field) you wish to compare against the search expression.
When you run your search, any record where the expression equates to true becomes
part of the result set.

In the latter case, it makes no difference in which layout element (field) you type your
retrieval expression.

Following are a few examples that demonstrate using retrieval expressions.

To find records where Date_Entered contains today's date:


Date_Entered: ={ @Date }
If the record being processed in the search contains the current date in the
Date_Entered element, it will be included in the result set.

Note: if comparing a date, it must be in the format YYYY/MM/DD, and in quotes, e.g.
Date_Entered: = { "2007/03/20" }
Expressions that evaluate to true or false for the record can be typed in any layout
element. Use the FIELD NAME if it differs from the layout element name.

281
8 SEARCHING & SORTING

The following expression will find records where the city is Columbia or the state is
MD:

Any field: { City = "Columbia" OR State = "MD" }

For programmed retrieves, as in other types of searches, Sesame is not case-


sensitive.

This expression will find all records where Date_Entered is in May of this year:

Any Field: { @Month(Date_Entered) = 5 AND @Year(Date_Entered) =


@Year(@Date) }

The following expression will find entries in Comments that exceed 255 characters:

Any field: { @Len(Comments) > 255 }

You can even use @XLookups in programmed retrieves. The following example finds
customers in Europe. In this case, Europe as a continent is stored, not in the
current application, but in a different application named Continents.db:

Any Field: { @XLookup("continents.db", Country, "Country", "Continent") =


"Europe" }

As you can see, retrieval expressions are powerful, and you can save them for re-use
just as you might save any retrieve spec. Saved programmed retrieves can be
attached to reports.

See the Sesame Programming Guide for details on all the available programming
functions.

Performance of retrieve spec programming


Programmed retrieves can take longer than normal searches, sometimes much longer.
Sesame 2.0 optimizes the retrieve spec programming by pre-compilation and pre-
running of portions of the retrieve spec. These portions are indicated by placing them
between pipe "" symbols, instead of using curly braces.
For example, if you put, in a date element:

> @Date - 30 & < @Date

you will search for any date between 30 days ago and today. The client compiles and
runs any code found between a starting pipe symbol "" and an ending pipe symbol
and substitutes the result of that expression in the search string it sends over to the
engine. So, on 30 September 2007 the example above would produce the search
string:

282
8 SEARCHING & SORTING

> 2007/08/31 & < 2007/09/30

Unlike using the "{ }" search spec programming, this programming runs only once on
the client, as opposed to running for each and every record to be searched, on the
server. This makes it many times faster, but it also means that record values (the
content of other elements) cannot be used.

Find on this Form


Sesame's Find on this Form
feature located on the Edit
menu (on the main Sesame
menu bar) allows you to
search for an exact match to
whatever characters you wish
in any element on the
displayed form (record).
You can also invoke the Find
on this Form feature by
pressing the Alt-G keystroke
combination (See Figure).
Figure 23. Find on this Form on Edit menu Once you select this option a
dialogue box will open.

Enter what you want to


find and select OK.
Type part or all of what
you are searching for.
The entry is not case
sensitive and wild cards
are not allowed.
Sesame will search for
exactly what you type
throughout the entire
form and will highlight
the element in which
the first match is
found. It will not
highlight the item
searched for in the
element on the form. If
there are multiple
Figure 24. Using Find on this Form.
occurrences of your
requested search on
the form, selecting Find on this Form again will move you to the next occurrence, and
so on (see Figure 24).

283
8 SEARCHING & SORTING

Saving Searches for re-use

You can save your search criteria for later re-use. It is the retrieve spec criteria that
Sesame saves, so only regular searches can be saved, not inverted searches or drill-
down searches, simple searches, or universal searches. You are most likely to want to
save a search when it is used regularly, because it took some effort to set up, or
because it retrieves the records you need under variable conditions, such as "last
month."

Retrieve specs are saved and recalled using Sesame's Spec Manager.

Using the Spec Manager


The Spec Manager is a dialog box where all types of specs, such as Retrieve specs,
Sort specs and Export Specs are managed. There are three ways to access the Spec
Manager. One way is from the menu tree, but there are two other ways

.. via the spec header bar: ..Or via keyboard Shortcuts:

Alt-F8 - Load a spec


Shift-F8 Save a spec

Saved specs, whether they are


retrieves, sorts, mass updates, or
the like, always relate to a form.
Each form has its own specs.

Figure 25. To open Spec Manager to view saved Specs

Saving a search
Follow these steps to save a retrieve spec:

1. Prepare the retrieve spec.


2. Run the search to confirm that you obtained the correct records.
3. Return to the retrieve spec (press F7 or click Search/Update / Search).
4. Press Shift-F8.
5. The Spec Manager displays, showing Retrieve as the type of spec, and the Save
tab active. (See Figure 26.)
6. Click in the Name box.
7. Type a name for the saved retrieve.
8. Click in the description box below the name.
9. Optionally, type a description for the saved retrieve.
284
8 SEARCHING & SORTING

10. Click on the Save button when done.


The retrieve spec name is added to the list of saved retrieve specs in the left hand
panel, followed by a dash and the description.

Note: The name you assign to your saved spec can be as long as you like,
with spaces and mixed capitalization. Likewise with the description.

Note: Although Open Spec Manager is available on the Search/Update menu


when viewing the result set, you cannot save or load retrieves from there. You
need to open the Spec Manager from the retrieve spec to manage searches.

Figure 26. Saving a retrieve.

Using a previously-saved retrieve


To load a saved retrieve, follow these steps:

1. Start a new search.


2. At the retrieve spec, press Alt-F8.
3. The Spec Manager displays, showing Retrieve as the type of spec, and with the
Load tab active. (See Figure 27.)
4. From the list of retrieves, select the saved retrieve you want to use.
5. Click on the Load button.
6. Click on Close.
285
8 SEARCHING & SORTING

The criteria, if any, of the current retrieve spec are replaced by those of the loaded
retrieve. If you return to the Spec Manager, this is shown as the "Currently Loaded"
spec, even if you have since modified the search. If you modify the search and save it
with the same name in Spec Manager, you are asked to confirm that you wish to
overwrite the saved retrieve of that name.

Figure 27. Loading a saved retrieve.

'Load' and 'Save' commands can


be found on the spec window
header bar. Load opens spec
manager with the load tab active,
and with the spec type set to the
spec type currently active in the
spec window. Likewise the Save
button, which opens with the save
tab active.
Figure 28. To open Spec Manager to view saved Specs

286
8 SEARCHING & SORTING

After loading a saved retrieve, you can run it as-is, modify it, or use any of the other
search options, such as Add to Results, Search in Results, and so forth.

Renaming a saved retrieve spec


Follow these steps to rename a saved retrieve spec:

1. Open the retrieve spec.


2. From the Search/Update menu, select Open Spec Manager or press Alt-F8.
3. The Spec Manager displays, showing Retrieve as the type of spec and with the
Load tab active.
4. Click on the Rename tab.
5. From the list of retrieves, select the saved retrieve you want to rename.
6. Edit the name that is now shown under Currently Selected for Rename.
7. You can optionally edit the description.
8. Click on the Rename button.
9. The right hand panels are cleared and the new name appears on the list of
saved retrieves.
10. Click on Close.

Deleting a saved retrieve spec


You can delete a saved retrieve spec this way:

1. Open the Retrieve Spec.


2. From the Search/Update menu, select Open Spec Manager or press Alt-F8.
3. The Spec Manager displays, showing Retrieve as the type of spec and with
the Load tab active.
4. Click on the Delete tab.
5. From the list of retrieves, select the saved retrieve you want to delete.
6. Click on the Delete button.
7. Click on Close.

Setting a default retrieve spec


Sesame allows you to set a default retrieve spec to automatically apply each time you
search that form.

287
8 SEARCHING & SORTING

Warning: If you set a default retrieve spec for a form, you might not see all
of your records unless you clear the default search criteria (F3) before running
your search. There is no indication that the records have been filtered through
a default retrieve spec other than the criteria that are visible in the spec when
you open it.

To set a Default Retrieve Spec:

1. Open the Retrieve Spec.


2. From the Search/Update menu, select Open Spec Manager or press Alt-F8.
3. The Spec Manager displays, showing Retrieve as the type of spec, and with the
Load tab active.
4. Click on the Defaults tab.
5. From the list of retrieves, select the one you want to use as a default.
6. Click on the Set Default button.
7. Click on Close.

You can likewise clear a default retrieve spec by clicking the Clear Default button in
the Spec Manager.

Q&A
Q&A for DOS does not support default retrieve or sort specs.

Regular Expressions

All the foregoing assumes use of the search language used by Sesame 1 and by
Symantec Q&A. Sesame 2 offers an additional, optional search language: 'Regular
Expressions' or 'Regex'.

A search language is a set of characters that have special meaning in a query. For
example, in Q&A and Sesame, entering ".." in a text element, means match any
characters. Entering "m.." in a search spec, means match text that starts with "m".
The ".." will match any characters that follow the "m". Entering "..m", will match text
that ends with "m". The ".." will match the text that precedes the "m". The portion of a
search that is not comprised of special character combinations is matched literally. In
other words, the "m" in the examples above is will match an "m" in the text to be
searched.

288
8 SEARCHING & SORTING

Just as the Q&A search language is a set of combinations of characters that have
special meaning to a search, regular expressions are also a set of combinations of
characters that have meaning to a search.

In Sesame 2.0, a regular expression can be used in place of the Q&A search language.
The two languages can be combined on the same search spec. The default search
language is the Q&A search language. To cause Sesame to use regular expressions as
the default search language, start sesame with the "-regex" startup switch, or use the
"DEFAULT SEARCH SYNTAX: regex" command in the sesame.ini file. At any time, you
can switch the search syntax for any one particular search by using the command tree
command "Search Menu!Search Options!Use Q&A Search Syntax" or "Search
Menu!Search Options!Use Regular Expression Search Syntax". To
mix the two syntaxes in a single search spec, use the "regex(...)" search construct or
the "qanda(...)" search construct in an element in the search spec. The regex(...)
construct allows the use of regular expressions when the Q&A syntax is the default.
The qanda(...) construct allows use of the Q&A syntax when regular expressions are
the default. These constructs must be used by themselves within any one element and
cannot be mixed with the other syntax within that one element.

Regular expressions have many equivalents to Q&A search language constructs for
searching on text. Regular expressions do not have constructs that allow numeric,
date, or time range comparisons as found in Q&A. For that reason, all elements are
treated as text when working with regular expressions. For example, in a Q&A search,
"> 10" will find records where a number element has a value greater than 10. This
search in a regular expression is not possible. The element's value is treated
as a text "1" followed by a text "0", not as a number with a value of 10.

Regular expressions have many text comparison features that are either very difficult
or impossible in Q&A syntax. For example, regular expressions can match a range of
characters, specify a minimum and maximum number of matches required, or match
characters based on the type of the characters to be matched. It is possible to create
a pattern to match any text string using regular expressions. Unlike Q&A, regular
expressions are not anchored to either the beginning or the ending of lines by default.
A search for the letter "m" will match text with the letter "m" anywhere in the text.
Also, unlike Q&A search language, regular expressions are case sensitive by default,
so "m" does not match "M".

Construct Q&A Regular Expression


Match a "M" ..M.. M
Starting with "M" M.. ^M
Ending with "M" ..M M$
Starts and ends with "M" M..M ^M.*M$
Exact match of "Hello" Hello ^Hello$
Text containing "Hello" ..Hello.. Hello
289
8 SEARCHING & SORTING

Find a three letter word ending in "ed" ?ed ^?ed$


Find a four letter word start with "Mar" Mar? ^Mar.$
Find "Mark" or "Marc" Mark;Marc ^Mar[c,k]$

The Basics
Match the beginning of
^ ^Hello Matches a line that starts with "Hello"
the line
Match the end of the line $ Hello$ Matches a line that ends with "Hello"
Matches "but", "bit", "bet", "bat", and any
Match any character . b.t text starting with "b", ending in "t" with
one character between,
Match a character listed
[] b[uei]t Matches only "but", "bet", and "bit".
in the square braces
Matches "Maid" and "Mad" and any text
Match zero or more * M.*d
that starts with "M" and ends in "d"
Match zero or one ? start.?ing Matches both "startling" and "starting"
Matches "Moore" and "More", but not
At least one + Mo+re
"Mre"
Not matching [^ ] [^a].?ount Matches "mount" but not "amount"
Match either | More|moore Matches either "more" or "moore"

Quantifiers
The "*", "?", and "+" listed above are quantifiers. Regular expressions allow the user
to specify the number of matches required by placing a quantifier after the pattern to
be matched. The pattern "mo*re" will match "mre", "more", and "moore", because the
star "*" is after the "o" it indicates that there must be zero or more "o"s after the "m"
and before the "r". The user can specify a precise quantifier by using the
"{ }" construct. These allow the user to specify an exact number of matches or a
range of matches:

A single match {1} Mo{1}re Matches "more" but not "moore"


Matches "moore" but not "more" or
Two matches {2} Mo{2}re
"mooore"
At least 2 matches but Matches "moore", "mooore" and "moooore",
{2,4} Mo{2,4}re
not more than 4 but not "more" or "mooooore"
Matches "moore" and "mooooore", but not
At least 2 matches {2,} Mo{2,}re
"more"
No more than 2 Matches "more" and "moore", but not
{,2} Mo{,2}re
matches "mooore"

290
8 SEARCHING & SORTING

Groups and Text Ranges


In the quantifier examples, the quantifiers each worked on a single letter pattern - the
letter "o". To use a group of characters as the pattern, they need to be grouped.
Regular expressions use the square braces "[ ]" to enclose a group or range of
characters. For example "[abc]" matches text containing "a" or "b" or "c". The dash "-"
can be used to specify a range of characters within a group. So, "[a-z]" will
match the lower case alphabetic characters. "[A-z]" will match all of the alphabetic
characters regardless of case. Ranges can be mixed with individual characters in the
same group. So it is possible to specify a match for "a", "b", "c", or any character
between "q" and "z", using "[abcq-z]".

To match the dash "-" or the square braces inside of a group, use them first in the
group. To match a dash, "a", "b", or "c", use "[-abc]". To match the square braces and
"a", "b", or "c", use "[][abc]".

Character Classes
Characters can be seen as having "class". These classes specify what kind of character
it is. For example the space " " character and the tab character are both seen as
whitespace characters. The characters between "A" and "Z" are considered to be in
both the alphabetic class and the alphanumeric class. The numerals are in both the
numeric class and the alphanumeric class.

The character classes supported by regular expressions:


alphanumeric [:alnum:] letters and numbers
alphabetic [:alpha:] letters
blank [:blank:] tab or space
control
[:cntrl:] character in the ASCII range less than 32 or equal to 127
characters
digits [:digit:] the digits from 0 to 9
printable [:print:] printable characters (ASCII 32 through 126)
graph [:graph:] same as [:print:] but omits space (32)
lower [:lower:] lower case characters
upper [:upper:] Upper case characters
all characters that are neither alphanumeric or control
punctuation [:punct:]
characters
space [:space:] Space, carriage return, newline, tab, and form feed

There are also shorthand character classes:


digit \d any digit
non-digit \D anything not a digit
whitespace \s whitespace

291
8 SEARCHING & SORTING

non-whitespace \S anything not whitespace


word character \w any character that can appear in a word
non-word character \W Characters that cannot be in a word

Sesame's implementation of regular expressions is based on the Perl extension to the


Posix standard. There are many constructs and examples that are not documented
here, but can be found on the hundreds of web pages dedicated to regular
expressions. There are also regular expression example libraries for common tasks
such as validating telephone numbers, post codes, social security numbers, and much
else.

Constructs regex() and qanda()


Regular expression syntax and Q&A compatible syntax can be mixed on the same
retrieve spec, but cannot be mixed within the same layout element. The regex(...)
search construct allows elements on a spec that is defaulted to the Q&A compatible
syntax to use the regex syntax in that element.

Example:

First Name: regex(^M)


Last Name: ..n

The example above will use regex syntax in the First Name element to check if the
first name starts with a capital "M". It uses the Q&A compatible syntax to check if the
Last Name ends with a "n". Any text typed into an element before or after the
regex(...) construct, while not specifically illegal, will be ignored.

If the default has been set to regular expression syntax, you can still use the Q&A
compatible syntax in individual elements by specifying the qanda(....) search
construct. As with the opposite regex(...) search construct, the qanda(...) construct
must appear alone within an element and can be used in multiple elements.

The "content" between the parenthesis can be any Q&A compatible search phrase.
This is especially useful for searching in numeric elements, where the regex syntax will
treat the numeric value as text.

292
8 SEARCHING & SORTING

Sorting records
How to Sort
Sesame does not store your records in sorted order. You specify your sorting criteria
when you retrieve them. Sorting is an option, not a requirement.

You can sort in two ways. You can specify a sort order before you run a search. You
can then optionally perform a dynamic sort when you have your result set.

Just like with searches, you can save and recall sort specs and you can also set a
default sort spec so you automatically see your data sorted the way you prefer. To
specify sorting criteria, you use the spec window.

The spec window


The spec window is a multi-use area at the lower left corner of the Sesame screen.
(See Figure 20.) It can display a variety of specs for operations such as sorting,
exporting, importing and mass updating. For full details on using the Spec Window,
see page 46.

The spec window is context-sensitive. For example, when the retrieve spec is open but
before a search has been run, the spec window will show only the Sort, Duplicates and
Table Specs as the others are not applicable. After a search has been run and you
have a result set, other types of specs, such as those mentioned above can be
selected. The sort spec is not available in Add data mode.

Once you have a result set, you can then


select a different spec by using the spec
selector buttons the arrows on either side
of the spec action bar, or by right-clicking on
the action bar for a list of specs. When
viewing a result set following a search, the
sort spec is the default in the spec window.

If the spec window is not already showing the


sort spec, make it do so by right-clicking on
Figure 29. Right-click on action bar
the spec action bar and clicking on Sort
to see list of specs.
[formname].
Using the Sort Spec
With the sort spec displayed in the spec window, click on the selector for each field
you wish to sort by. That layout element name will move to the top of the list and will
show an S next to it to indicate it is a sorted element (field). Another box with an A on
it will appear, indicating an ascending sort. You have two choices for the sort order:
A Ascending order, A-Z or 0-9
D Descending order, Z-A or 9-0

293
8 SEARCHING & SORTING

Figure 30. The sort spec: sorting by State then City

Click on the A button to toggle between ascending and descending sort for that field.

You can sort by as many fields as you like. The order in which they are sorted is
determined by the order of the layout element names in the sort spec. The top one is
sorted first, then the second one, and so on.

To change the sort order, drag the layout element names up and down in the sort
spec. You can only drag elements that are enabled for sorting that is, they have an
S in the selector.

When and how to sort


You do not have to sort your data when you retrieve it. Sorting is optional. You can
sort in three ways:

1. You can sort as you retrieve. Fill out the retrieve spec with your search criteria,
define your sort parameters in the sort spec, then run the search in one of the
following ways:

Press F10.
Select Retrieve New Results from the Search Commands menu.
Select Run from the sort spec Action Bar.
Press Alt-R, the key combination for Run.

2. You can perform a dynamic sort. This is the same as above in that you prepare the
sort spec then run it. The difference is that you apply it (using one of the latter
two methods above) while viewing the result set, not at the retrieve spec.
You can also apply the new sort order by selecting SORT from the Results
Commands menu.
This way your result set is dynamically re-sorted you don't have to run the
retrieve again.

294
8 SEARCHING & SORTING
Q&A
Q&A for DOS has no dynamic sorting. You have to return to the sort
spec via the retrieve spec in order to re-sort the records.

3. You can Sort by timestamp, described next.

Sorting by timestamp

Sorting by timestamp differs and is


separate from "normal" sorting and
does not use the sort spec at all.

Each record in a database has an


internal timestamp that records the
date and time when that record was
last modified. You can sort a result
set by this timestamp. To do so, you
first run the search and obtain a
result set. Then select Sort by
Timestamp from the Results
Commands menu. (See Figure 23.)
Figure 31. Sort by timestamp.

The result set is immediately re-ordered with the most recently-modified records first.

Here are a few notes about sorting by timestamp:

You cannot sort by timestamp from the retrieve spec. It is a dynamic sort that
can only be applied to the result set.
Sorting by timestamp ignores any sort spec and is an alternative to it.
A timestamp sort has just one sort order most recently modified records
first.
You cannot save sort by timestamp.
The records in the database contain the timestamps, not the layout elements
on a form. Because of this, it might not be apparent on a particular form why
a record is recently modified. The modified field might not be represented on
that form.

295
8 SEARCHING & SORTING

Saving sort specs for re-use


You can save sort specs just as you can save retrieve specs.

To save a Sort Spec

1. Prepare the sort spec you want to use.


2. Press Shift-F8.
3. The Spec Manager displays, showing Sort as the type of spec, with the Save
tab active.
4. Click in the Name box.
5. Type a name for the sort.
6. Click in the description box below the name and type a description for the sort
(optional)
7. Click on the Save button.
The sort is added to the list of saved sort specs in the left hand panel, followed by a
dash and the description.

8. Click on the Close button when done.


Note: Spec names and their descriptions can be as lengthy as needed and include
spaces and mixed capitalization.

Setting a default sort spec


Sesame allows you to set a default sort spec. This is applied automatically every time
you search that form.

To set a Default Sort Spec:

1. Prepare a sort spec as described above.


2. Save the sort spec as described above.
3. With Spec Manager still open, click on the Defaults tab.
4. From the list of sort specs, select the one you want to use as a default.
5. Click on the Set Default button.
6. Click on Close.
You can likewise clear a default sort spec by opening the Spec Manager and clicking
the Clear Default button.

296
Section 9
Mass Updating
Mass update is one of the most powerful features in Sesame. While the most common
use of mass update is to update information in a batch of records, you can also run
very useful mass updates that change no values at all.

For example, mass update can be used to write data from each record to an external
file, send an email for each record in your result set, or display quick report-like
summaries in the pop-up WriteLn window. See the Sesame Programming Guide for
details.

In addition, mass update can be made to pause during operations requiring user
interaction, so you can use functions like @UserSelect to dynamically offer a choice of
actions for each record in your result set. With the RemoveFromResultSet command,
you can also use mass update to remove records from your current batch based on a
programmed set of conditions, leaving you with a trimmed result set for use with
reports or follow-up mass updates.

Mass Update overview


Mass update gives you a way to change the data in many records in a database in a
single operation. The following are typical of the kinds of changes you can make using
mass update:

Direct replacement of data. For example, change "California" to "CA" or


change Tax Rate from 0.06 to 0.075.

Changes based on other field values. For example, If Years of Service exceed
15, then make the Bonus Amount equal to Salary times 0.07.

Changes based on calculations or programming. For example, lookup the new


cost value of a product in an external database and place it in the Cost
element. Then multiply the cost times the customers payment factor, add the
shipping, and calculate the total.

A mass update is performed on all the records in the current result set. (See Searching
and Sorting in this Guide for details on retrieving a result set of records.)

A mass update can be run in interactive (review each record before updating) or
continuous (automatic, no review) mode.

Mass update specs can be saved and recalled for later use.

Mass update can change data displayed in multiple elements (fields) in one operation.

297
9 MASS UPDATING

Backup first
A mass update can change the data in your database records. It is strongly
recommended that you backup your application before running a mass update on any
databases. Any changes made to your data during a mass update are irreversible.
There is no "undo" button for mass updates. See also footnote at end of this section.

Running a mass update


The steps involved in running a mass update are as follows:

1. Retrieve, and sort, as necessary, the records you want to update. See the section
on Searching and Sorting in this Guide.

2. Use the Spec Action bar or the Spec Selection arrows to display the Mass Update
Spec in the spec window. (For details on using the Spec Window see page 46.)

Figure 1. Mass Update selection shown on Search Update Results Commands menu. Mass
Update spec showing in Spec window.

3. Double-click on the element name on which you want to perform the mass update.
Sesame will mark that element with a P for programming attached and will open it

298
9 MASS UPDATING

in the Program Editor. (See Figure 2.) For further details on working in the Mass
Update spec, see Using the Mass Update Spec below.

4. Write the programming statement to accomplish the task you want the mass
update to perform. (See Figure 2.)

All the functions and commands that can be used in mass update programming
can be found in the Sesame Programming Guide.

Your Mass update programming can be as easy as these three examples:

Tax = 0.075

State = "CA"

If City = "Costa Mesa" and State = "CA" Then County = "Orange"

Your programming can be as complex as is necessary to get the job done.

Figure 2. Using the Program Editor to write programming for mass update. Note in the
background window that the Key element has a "P" in its element selector.

5. Test that your programming is valid by clicking on Test / Test program from the
program Editor menu, or pressing the shortcut key Ctrl-T. If there is an error it is
shown in the lower part of the window, under "Error String". If the programming is
good you see nothing there. Close the Program Editor.
299
9 MASS UPDATING

6. From the Results Commands


menu, select Mass Update.
Alternatively, you can click on the
Mass Update Spec window's Action
bar and select Run from the
dropdown menu. (Both options are
shown in Figure 3.)
All programming in all elements
with a "P" next to them in the Spec
window will be executed in the
order in which they are listed in the
Spec window.

7. Sesame will ask if you want to


review each record before it is
updated (click on Interactive) or
run the mass update on all result
set records with no further
interaction (click on Continue). You Figure 3. You can run a mass update from
also have the option to cancel the the Results Command menu or the Mass
operation. (See Figure 4.) Update spec Action bar dropdown.

Figure 4. Select Interactive or Continuous mode for the mass update.

If you select Interactive, you will see the first record in the result set along with the
dialog box in Figure 5. You can then choose among the following actions:

Update the current record and get the next one.

Skip the current record and get the next one.

Update All the rest of the records, including the current record, with no further
interaction on your part.

Cancel the rest of the mass update. (Records already updated will stay that
way).

300
9 MASS UPDATING

Figure 5. Confirming record update in Interactive mode

When the mass update has been completed, you will be returned to your result set to
the same record you started with.

Interrupting a Mass Update


To interrupt a Mass Update press the key combination: Shift-Ctrl-End

You will be presented with the message (figure 6 below) and the mass update will
pause. Clicking on Yes will stop the mass update. Any records that have already been
updated at the time of the break will retain any changes already made. Clicking on No
will allow the mass update to continue. A message will appear on the status bar
informing the user of this option.

Figure 6. Confirm dialog: interrupt mass update.

Interrupting a mass update might leave you with a set of records some of which have
been modified and some not, and with no means of determining which are which.

Using the Mass Update Spec


A mass update spec is the collection of all the programming statements in all the
layout elements to which you have added mass update programming.

Setting which elements to program


With the mass update spec active in the Spec window you can:

Click on the element selector (the gray box to the left of the element name).
This does two things:

301
9 MASS UPDATING

1. Moves the element name up the list, above non-programmed elements.

2. Marks the layout element as one to contain mass update programming by


putting a P next to it (in the element selector box). This does not program
the element that you do in the program editor. It merely marks this
element as one with attached programming or qualified as programmable.

Double-click on a layout name. As well as marking the element with a P and


moving it up the list, it opens the program editor if it is not already open.

To open the mass update program editor, double-click on any layout element name.

You can write programming statements in any layout element. You can also place all
your statements in the one element. This keeps it simple.

You can disable the programming in an individual element by clicking on the P in the
element selector box. This does not delete the programming. It only disables it and
only temporarily, as will be described below.

From the above, you can see that:

You can have a programmed element without a P alongside its name,


indicating its attached programming is temporarily disabled.

You can have an element with a P alongside its name which does not have
programming attached.

When you close the mass update program editor, Sesame marks all elements that
have programming in them with a P, and removes the P from any elements containing
no programming. Disabled elements are re-enabled whenever you close the program
editor after having added programming to them.

All elements can be deselected by selecting Clear All from the Action bar dropdown.
Even though the P is not visible (indicating that the programming attached to that
element will not be run), the mass update programming stays attached to the element
as long as the form is open, unless deleted or changed in the program editor.

Setting the programming execution order


If you have multiple layout elements programmed, the order in which their programs
are executed can be important. Just as the order of updating records is determined by
the sort order of the result set, the order in which the layout element programming is
executed in a mass update is determined by the order in which the they appear in the
mass update spec.

To move an element name up or down in the spec window, drag it up or down.


Alternatively, click once on it to select it and then press Shift-Up arrow or Shift-Down
302
9 MASS UPDATING

arrow to move it up or down the list. You can only move layout elements marked with
a P. (See Figure 7.)

Global code
In the mass update spec
window, you will see listed all
the bound layout elements
(elements linked to a field in
the underlying database), plus
an extra item at the top:
Global Code. (See Figure 7.)

Global code is a storage Figure 7. Mass update spec moving the Last field.
location for programming that
is available to mass update programming in all the other layout elements in this
specific mass update. Global code can be used to declare and initialize variables and
arrays, and store custom procedures such as user-defined functions and subroutines.
Details on Global code and other capabilities of Sesame's programming language can
be found in the Sesame Programming Guide.

The programming in the Global code area runs once at the beginning of the mass
update.

Do not use Global Code for regular mass update programming that is intended to be
processed on every record it will not do that.

Which layout element to program?


There is no reason to place the programming statement that sets a layout element's
value in that layout element. In effect, each layout element is just a general "storage
location" for mass update programming statements. You can put all your mass update
programming into any single layout element.

Placing all programming in one element


Even if you are using mass update to change multiple elements, it is advisable,
although not mandatory, to include all of your statements in a single elements
programming.

There are two advantages to using just one layout element for all your mass update
programming:

You can control the sequence of changes without moving the elements in the
list. In other words, the second change can be dependent on the results of the
first change. For example, you can tell Sesame to "Lookup the employee's
date of birth and, if before 1950, insert bonus value of XX. If bonus value is
greater than XX, then, else"

303
9 MASS UPDATING

You can view all your update programming in one location. You can even add
comments to your programming to assist you in determining what the mass
update is doing. This can be particularly advantageous if you save your mass
update spec for future re-use. See the Programming Guide for details on how
to add comments to your programming.

The advantages to using multiple layout elements are these:

You can make some portions of your code optional by turning off the "P" for
that element.

You can use the Spec window to quickly change the order in which the
statements are executed.

For most mass updates, you will likely see more benefit from putting the entire mass
update program into a single layout element.

Using the Program Editor


The program editor you use to enter your mass update programming statements is
essentially the same as the one you use in Designer to program your forms or layouts,
as described in detail in the Programming Guide. There are a few differences,
however.

Open the program editor by double-clicking on any element name in the mass update
spec window. This will mark that element as a programming "slot." Type your mass
update program in the program editor. (See Figure 8.)

You can employ almost all the functions and other features (loops, arrays,
subroutines) in Sesame's programming language, and the same rules apply:

Your programming must reference layout element names, not field names in
the database.

Your programming can refer to layout elements in other forms in the


database, or in other Sesame databases or applications, using the "X" family
of commands (XLookup and XPost, for example).

Q&A
You can also use XLookup to retrieve values from a Q&A database.

You should not use @Macro or @SelectTreeItem in mass updates.

Q&A
In Q&A mass updates, you can refer to fields by their field names or
Logical Field Numbers (LFN's), such as "#20". Sesame does not have LFN's.
You must refer to layout elements by name.

304
9 MASS UPDATING

Figure 8. Mass update program editor.

In the program editor, the first dropdown lists the layout element names, with Global
Code at the top of the list. The layout elements are initially listed in the order of
execution that is, the order they appear on the list in the mass update spec window,
but you can re-order the list of element names when the list is displayed either by
pressing the / (forward slash key) or clicking the right mouse button. You can use
this dropdown to open a different "programming slot" for a different element. Once a
list is open, typing a letter will move you to the section of entries that begin with that
letter.

You can see only the programming attached to one element at a time. That is to say,
you cannot view the mass update programming in multiple elements as a whole
program. You can, however, create a text file containing all the mass update
programming by selecting Export All to Text File from the File menu in the program
editor, or by pressing the Ctrl-S shortcut key.

The second dropdown, Event, displays only one event Mass Update.

To the right of the event dropdown is the Programmed Element Navigator. It has three
components. The dropdown displays only those elements that have programming in
them. On either side of the dropdown are buttons with arrows that allow you to view
the previous or next element containing programming. (See Figure 9.)

Figure 9. Programmed Element Navigator.

This provides a convenient way of navigating the relevant elements. Note that the
element navigator displays newly-programmed elements only after the program editor

305
9 MASS UPDATING

is closed and re-opened. This list can also be sorted in alphabetical order by pressing
the / key or clicking the right mouse button when the list is displayed.

Testing your programming


After you have composed your programming statement(s), you should test them by
clicking on Test Program on the program editor's Test menu. This tests the code in all
the elements for just this mass update. It does not test the programming in the
layout/form. Any errors are shown in the lower part of program editor window. (See
Figure 10.) Any errors must be corrected before proceeding.

Figure 10. Error string detailing invalid programming. There is no layout element "Last Name".
Note the caret symbol (^) indicating where the error is.

Saving the programming in the program editor


To save all the mass update programming, close the program editor. You can do this
by selecting File / Close Program Editor, by pressing Ctrl-Q, or by clicking on the X
button in the top right-hand corner of the program editor window's title bar.

Whenever you close the program editor, all changes to the current spec are saved
until you exit the form. If you want to apply your changes to a saved mass update
spec, you must resave the spec to make the changes permanent.

Invalid programming
Whether you test your programming or not, Sesame allows you to save it even if it
is invalid. (Sesame does not automatically test your programming.) However, If you
attempt to run a mass update with invalid programming, Sesame will not allow it. You
will receive an error message. (See Figure 11.)

306
9 MASS UPDATING

Figure 11. Error message if invalid mass update programming is detected.

Saving mass update specs for re-use


Mass update specs can be saved and recalled for use later. You save and load these
specs using the Spec Manager. See "Using Spec Manager" on page 284.

Using the Spec Manager


The Spec Manager is a dialog box in Sesame where all types of specs, including
retrieve, sort, mass update, export specs can be managed.

Saved specs, whatever their type, belong to the form you were using when you
created and saved them. Each form has its own specs.

Specs can be run programmatically


All specs can be loaded or loaded and run by programming.

Saving a mass update spec


Follow these steps to save a mass update:

1. Run a search to obtain a result set.


2. Prepare the mass update spec you want to use.
3. Press Shift-F8.
4. The Spec Manager displays, showing Mass Update as the type of spec, and the
Save tab active. **
5. Click in the Name box and type a name for the mass update.
6. Click in the description box below the name and type a description for the
mass update. (This is optional.)
7. Click on the Save button when done.
8. Close the Spec Manager.
(See Figure 12.)

307
9 MASS UPDATING

Figure 12. Saving a mass update spec.

The spec is added to the list of saved mass update specs in the left hand panel,
followed by a dash and the description.

Note: The names and descriptions you assign to your saved specs can be as
long as you like, with spaces and mixed capitalization.

** An alternative way to open


the Spec Manager is to use the
'Load' and 'Save' commands
found on the spec window
header bar. Load opens spec
manager with the load tab
active, and with the spec type
set to the spec type currently
active in the spec window. The
Save command opens spec
manager with the save tab Figure 13. To open Spec Manager to view saved
active. See figure 13. Specs

308
9 MASS UPDATING

Using a saved mass update spec

Follow these steps to re-use a saved mass update spec:

1. Run a search to obtain a result set.


2. In the spec window, display the Mass Update spec. The easiest way to do this
is to right-click on the Spec Action Bar and select Mass Update from the list.
3. Press Alt-F8.
4. The Spec Manager displays, showing Mass Update as the type of spec and with
the Load tab active. **
5. From the list of saved mass updates, select the one you want to use.
6. Click on the Load button.
7. Click on Close. (See Figure 14.)

Figure 14. Loading a mass update spec. The currently loaded spec is Las Vegas 03. Clicking
Load will load the mass update spec named Check figures agree.

309
9 MASS UPDATING

The mass update spec is loaded. It is not automatically run. If you return to the Spec
Manager, the spec you loaded is shown as the "Currently Loaded" spec, even if you
have since modified it.

If you modify the mass update and want to save it with the same name in Spec
Manager, you are asked to confirm that you wish to overwrite that named mass
update spec.

** Alternatively, you can use the 'Load' and 'Save' commands found on the spec
window header bar. Load opens spec manager with the load tab active, and with the
spec type set to the spec type currently active in the spec window. Likewise the Save
button, which opens with the save tab active. See figure 14 above.

Renaming a saved mass update spec


To rename a saved mass update spec, follow these steps:

1. Run a search to obtain a result set.


2. From the Search/Update menu, select Open Spec Manager.
3. The Spec Manager displays, showing Copy as the type of spec, and with the
Load tab active.
4. Change the spec type to Mass Update.
5. Click on the Rename tab.
6. From the list of saved mass updates, select the one you want to rename.
7. Edit the name that is now shown under Currently Selected for Rename.
8. You can optionally edit the description.
9. Click on the Rename button.
10. The right hand panels are cleared and the new name appears on the list.
11. Click on Close.

Deleting a saved mass update spec


Follow these steps to permanently delete a mass update spec:

1. Run a search to obtain a result set.


2. From the Search/Update menu, select Open Spec Manager.
3. The Spec Manager displays, showing Copy as the type of spec and with the
Load tab active.
4. Change the spec type to Mass Update.
5. Click on the Delete tab.
6. From the list of saved mass updates, select the one you want to delete.

310
9 MASS UPDATING

7. Click on the Delete button.


8. Click Yes at the confirm dialog.
9. Click on Close.

Setting a default mass update Spec


Sesame allows you to set a default mass update spec for any form. When you do so,
that mass update spec is automatically loaded whenever you open that form. It is
available to be run at any time by selecting Mass Update from the menu tree or from
the Spec window action bar.

If you want to run a mass update other than the default, you must first clear the
default mass update. You can do this in one of two ways:

By loading another saved mass update spec.

By going to the mass update program editor and clearing each of the
programmed layout elements, then adding new programming statements.

Warning: When you have a default mass update spec and want to use a different
mass update spec, you must clear the old one. It is not sufficient to disable the
layout element(s) in use by the default mass update spec, then program others.
When you leave the program editor, all the programmed elements will again be
enabled.

Follow these steps to set a default mass update spec:

1. Run a search to obtain a result set.


2. From the Search/Update menu, select Open Spec Manager.
3. The Spec Manager displays, showing Copy as the type of spec and with the
Load tab active.
4. Change the spec type to Mass Update.
5. Click on the Defaults tab.
6. From the list of saved mass updates, select the one you want to use as a
default.
7. Click on the Set Default button.
8. Click on Close.

You can likewise clear the default mass update spec by going to the same place and
clicking the Clear Default button. This does not clear the mass update programming in
this spec from the current session. It only stops this spec from being loaded the next
time the form is opened.

311
9 MASS UPDATING

Mass updates and security


Security can be applied to Sesame applications. This can have a big impact on the
mass update facilities available to a particular user or group of users. The following
can be affected by security:

Whether mass update is available to run from the menu tree.


Whether mass update is available in the Spec window.
Whether mass update is available in the Spec manager.
Ability to change values in individual layout elements.

User level security


A user at the user level "Data Entry" will not be able to access the mass update spec
in the spec window it will be grayed out.

If a default mass update has been defined, then data entry users can select Mass
Update from the Results Commands menu to run it. That is the only mass update a
data entry user can run. If there is no default mass update, the Mass Update choice
still appears on the menu tree but will only run a null mass update a mass update
that does nothing.

Whether or not there is a default mass update, the mass update option is disabled in
the Spec window for a Data Entry user.

Element level security


If a user is in a group that does not have "Write" or "Execute" permission relating to a
particular layout element, then that user cannot modify that layout element's values
by a mass update.

Other programming
The mass update will not cause any form or element programming to run other than
what is contained in the mass update including On Form Entry and On Form Exit
programs. If you want your On Form Change programming to be run in a mass update
you have to copy and paste it from the form programming into a mass update.
Q&A
Q&A and mass updates

Recalc options
When you run a mass update in Q&A, you have the option of pressing F8 for the
Auto Program Recalc screen where you can set three options for form
programming to run with the mass update:

On record entry statements


Calculation statements
On record exit statements

312
9 MASS UPDATING

This allows the Q&A user to have any or all of these three kinds of programming
executed on each record after the mass update programming has executed on
each record. The default is No for each option that is, run no form
programming.

Sesame does not have such options. No form programming is run when you
perform a Sesame mass update. The only changes made to the result set records
are those dictated by the specific mass update programming.

Translated Q&A mass updates


Sesame translates your saved Q&A mass updates. Logical field numbers such as
"#120" are converted to layout element names. Each mass update is translated to
a Sesame saved mass update with the same name, and with the description:
"Translated QA Mass Update Spec."

When you translate a Q&A database, the auto program recalc options are lost. If
your mass update depended on form programming running, you will have to
transfer that programming to the mass update itself.

Special Notes on Mass Update

Sort order of records


Mass update will operate on records in the order they appear in the current result set.
In some cases, the order in which the records are mass updated can be critical. Each
time you run a search, you have the option to sort the result set by filling in the sort
spec either before running the search or when viewing the result set. See Sorting in
the Searching and Sorting section of this Guide.

Order in which records are updated


The first record in the result set does not need to be on-screen when you run a mass
update. You can be viewing a record in the middle of the set. When you run the mass
update, Sesame starts at the first record in the set and updates all the records in the
current sort order. When the mass update has been completed, Sesame re-displays
the record you were viewing when you initiated the mass update.

If/Then programming
If your mass update programming employs a simple conditional such as If State =
"MD" Then [statements] to determine which records to update, consider retrieving
your records in a way that the result set contains just the Maryland records to begin
with. In this way you simplify the programming required to perform the update. You
won't need the If/Then conditional, and the mass update won't have to scan as many
records.

On the other hand, an If State = "MD" Then... conditional in your program can serve
to prevent non-Maryland records from being incorrectly updated should the result set
contain such records when the mass update is run.
313
9 MASS UPDATING

Mass updating in a multi-user environment


A mass update can be run while other users on the network are using the same
application and even the same database. All records in the result set will be mass
updated to your specifications except for those currently in use (and thus locked) by
other users. Should this occur, you would ideally want Sesame to inform you about
the non-updated records so you can appropriately deal with them. This is not a
standard Sesame feature, but it can be achieved with programming (not covered in
this manual).

Endurance of the mass update spec


The mass update spec, with its programming, is maintained as long as the current
Search/Update tab (at the bottom left corner of the Sesame screen) is open. This
allows you to perform multiple searches including using advanced search techniques
such as Add to Results to refine your result set. If you press Escape, or otherwise
close the Search/Update tab, then the mass update spec is cleared. You can save the
mass update spec at any time before it is cleared.

Mass updating by other means


In Sesame, it is possible to perform mass update-like actions on the records in a result
set without using the Mass Update feature at all. Built-in programming commands
such as ResultSetCurrentPosition, when used in conjunction with a loop, enable you to
move through each record in the set and update it and/or output the data from it in
the manner you choose. A program like this can be attached to a command button
that you simply click on whenever you want to run the procedure on the current result
set.

A sample program that demonstrates this is shown in Appendix 2 of the Sesame


Programming Guide ("Merge Printing Database Records in an External Word
Processor"). The program loops through each record in a result set, writes its data to
an external text file, then passes the resulting file to a selected Microsoft Word
document, where a letter is merge printed for each Sesame record.

More on Backing up
Note on necessity to back up before mass updating:

Note: In some cases, it may be possible to construct a "reverse" mass update to


effectively revert incorrectly updated records to their pre-mass update condition. This is
not an "undo" but a change back operation. Programming for such a corrective mass
update must fully take into account what the original mass update did and to which
records, and perform the precise programming actions required to reverse it. In cases
such as where the original programming may have conditionally (or not) deleted
information, even the most carefully constructed "reverse" mass update will not be able
to bring it back. Furthermore, the information that identified which records needed
updating may have been changed by the update itself, so they cannot then be identified.
There is no substitute for a backup.

314
Section 10
Printing Forms
There are many ways to print data from Sesame. These include

Reports and Quick reports


Print Merge with MS-Word or another external word processor to print form
letters or mailing labels
Setting up a PrintString document in programming
Printing the form

Each of these methods is best suited to a particular kind of printing task. For example,
printing a 'snapshot' of the visible form/record (Print Form) is convenient, but will not
show all your data if you have long values or tab pages. If you want to use Print Form,
you may want to create a form that is optimized for printing. Fortunately, Sesame
allows you to have multiple forms and the new Switch To Alternate Form feature
makes switching between them seamless.

Sesame allows you to print individual records in your database, the complete result set
of retrieved records, or all the records you've added to a database during a session.
When you want to print just a single record, Sesame gives you the option to print it
directly to an HTML file for use with other programs or to view in any web browser.
Whenever you print a record, the output will contain the entire record including any
displayed subforms and images. The key to printing in Sesame is that you will always
be working with the current set of records rather than all of the records in the
application.

The Print commands in this section print your form as it appears on the screen, with
each layout element displaying the values from the record being printed. To print just
your data without including the form elements, you can create a report, (See the
Designing Reports section in this Guide) or use PrintString or MergeFilePrint (See
Programming Guide). You can also print your data using the Merge File Print
commands on the menu tree these require no programming.

There are several options for printing forms in Sesame:

Print the current form or the whole result set


Print the form exactly as it is or with 'no background'
Print the form directly using the defaults or display the print dialog
There is also an option for printing a single form to HTML.

The commands for printing just the current record are found on the Record Commands
/ Printing Commands menu.
315
10 - PRINTING FORMS

The commands for printing the whole result set are found on the Results Commands /
Printing Commands menu.

Printing in Update mode


The first step in printing your database records is deciding which records you want to
print, then retrieving those records from the database using a suitable form. (If
needed, you can create specialized forms that are designed with printing tasks in
mind.)

Next, you decide whether to print all the records you have retrieved, or just the one
you are currently viewing on-screen. Whichever choice you make, you can then use
the printing options on the Search Update Menu as shown in Figure 1.

Figure 1. Search Update menu showing location of printing commands for


just the current record and for the result set.

316
10 - PRINTING FORMS

Printing individual records


To print just the record currently on-screen, Click on Record Commands / Printing
Commands / Print Form or Record Commands / Printing Commands / Print Form to
HTML (See Figure 1.) If you select Print Form You will immediately be shown the Print
Forms dialog (See Figure 3). The options at this dialog are described below. HTML
printing is described a little later in this section.

Printing the result set


To print all the records you have retrieved (the current result set), Click on Results
Commands / Printing Commands / Print Forms. (See Figure 1.)

This message box will be displayed, showing the number of records that will be
printed:

Figure 2. Message box shown when Print Forms is selected.

Click Yes to proceed or No to cancel the print operation. Whichever menu command
you use (Print Form or Print Forms), you will be shown the Print Forms dialog (See
Figure 3). The options at this dialog are detailed below.

The Print Forms Dialog Box


(See Figure 3 below.)

Selected
This always shows Forms and is not editable.

Print Form Style


Background prints the form as it is shown on-screen, including form and text colors.
On a mono printer the form will print in grayscale - dark colors may print black.
No Background prints the form with no font colors, and a white background to the
form even if it has a colored background. Boxes and lines are not printed, but static
text is. This option is useful for printing dark-colored forms or those where color has
been used to differentiate certain layout elements or values in them, perhaps
programmatically.

317
10 - PRINTING FORMS

Figure 3. The Print Forms dialog, shown also when printing one form.

Current Record / Retrieved Records


Whichever menu item you selected to display this dialog will show the relevant setting
here. But it can be reversed, so you can print a single record having initially selected
Results Commands / Printing Commands / Print Forms, and vice-versa.

Format
Here you can select Portrait or Landscape to print the form(s) with the orientation of
your choice.

Show System Print Dialog


If this box is left clear the form(s) will print immediately you click on the Generate
button. The form(s) are printed to your default printer with its default settings. There
is no further user interaction. If you check this box, clicking on the Generate button
brings up your standard printer dialog box and allows you to change printer, select the
number of copies, print quality, page orientation, and choose other available options.
The options available will depend upon your printer and also the print driver installed.

Options

Units allows you to select inches or mm for the margins measurements.

318
10 - PRINTING FORMS

Paper allows you to select from a wide range of paper sizes. The default is "Printer
Default" which uses the settings currently in use for your printer. Generally Letter
paper is used in the USA, and A4 is used in the UK, Europe and many other parts of
the world. You should get good results leaving this set to Printer Default.

Columns & Rows


If you leave these two boxes blank, or type 1 in them, then you will print one record
per page. You can print more records per page by typing greater values. Figures 4 and
5 below show examples of output printing 4 and 6 records per page.

Figure 4. 1 page, 4 records. 2 columns by 2 rows, landscape

319
10 - PRINTING FORMS

Figure 5. 1 page, 6 records. 2 columns by 3 rows, no background, portrait

Pages Across & Pages Down


This is the opposite of Columns and Rows. If you leave these two boxes blank, or type
1 in them, then you will print one record per page. If you type greater values, then
one record will be split across two or more pages. See figure 6 for an example.

320
10 - PRINTING FORMS

Figure 6. 4 pages, 1 record. 2 pages across by 2 pages down, portrait

Margins
You can set margins for the printed page here, in units specified by the Units
dropdown. All margins are initially set to zero. If using margins it is important to set
all of them to a non-zero value.

321
10 - PRINTING FORMS

Printing in Add mode


In Add mode you have the very same printing options as described above in
Search/Update mode. See "Printing in Update mode" on page 316 onwards.

Note: When you go to print, you may receive a message that the current
record has not been saved. Sesame needs to save your record before it prints
it. You can save your current record by selecting Save Record from the
Navigation section of the Add Data Menu, or by simply pressing F10 followed
by F9 to save and return to the record.

Appearance of the printed record


The record or records you print will look the same way you see them on-screen. Check
boxes, list boxes and other layout elements will print just as you see them on-screen.
A subform will print at the same size as on the form, showing just the subrecords
currently in view on the form.

If there are values too long for a layout element you will see printed only the
truncated values. Only data on the tab that happens to be visible at that time will be
printed.

Sesame scales forms to fit the printed page. This means that if you have a form with
very large dimensions, but you only have layout elements in the top left corner, then
the printed page will show the "active" area of your form in miniature at the top left of
the page. If your form is long then it will print scaled to fit onto a single page, and the
values may be too long to be legible. If printing such a form is important to you then
you should consider creating additional forms designed for printing, and as a minimum
design the form so that its dimensions are roughly in proportion to those of the page
in the orientation you intend to print. You can also use the Pages options described
above to split your form across multiple pages.

322
10 - PRINTING FORMS

Printing to HTML
Selecting Record Commands / Printing Commands / Print Form to HTML creates an
HTML file of the current record and saves it to any location on your local computer or
to a mapped drive or UNC path on the network. This choice displays a file manager
where you name the file and choose where you want to save it. You must use an .HTM
or .HTML filename extension (Sesame will assign the appropriate filename extension
by default) both produce the same results. See Figure 7.
When you supply the path and filename for the file and click OK, Sesame saves the file
to the location you specified then opens it in your browser (See Figure 8). Your output
will look exactly like your form. Even the data fields will be editable in your browser.
You can select static text on the form but not edit it.

Figure 7. File manager dialog window for saving an HTML file print of a single record.

323
10 - PRINTING FORMS

Figure 8. The "printed" record displayed in Internet Explorer. Note that the path and filename
are shown in the browser's Address box.

Printing table view


In Add or Update mode, you can view your records in table view a spreadsheet-like
view by pressing Shift-F6. While you are in this view, you can also print your
records. Table View allows you set your columns as you would like them to appear and
save them in a Table View Spec (See the section in this Guide on Using Table View in
the Adding and Editing Data section.)

324
10 - PRINTING FORMS

Table view is printed in the same way as form view, using the Record Commands /
Printing Commands / Print Form or Results Commands / Printing Commands / Print
Forms commands.

Notes on printing Table View

The printed output will appear essentially as screenshot(s) of your table view
including column and row headers.
The printed output will print the columns and cells exactly as shown on your
screen. Cells will not be expanded. Non-displayed columns will not be printed.
Any columns to the left of the visible table will not be printed.
Your printout will consist of either just the visible records (if Print Form is
selected), or ALL the records, on multiple pages if necessary (if Print Forms is
selected).

Record Commands / Printing Commands / Print Form


This prints the visible table. Only 1 page is printed. The records printed are those
shown in the table currently, even if the selected record is not visible (the form having
subsequently been scrolled). Columns not visible are not printed.

Results Commands / Printing Commands / Print Forms commands.


This prints ALL the records in the table, printing on multiple pages if necessary. For
example, if your current result set has 50 records and you are displaying 20 rows in
the table, your output will be three printed pages, two with 20 rows and one with a
10-row table. Columns not visible are not printed, only those visible in the table
currently.

Print Options
These work as described earlier in this section. A useful setting, when there are many
records, is:

Columns 1 Rows 3

This prints 3 'rows' or screenshots of the table under each other on one page. The text
will still be legible, but you get up to 3 sets of data on a page. See example Figure 9.

325
10 - PRINTING FORMS

Figure 9. Multiple records, printed 1 column, 3 rows.

326
10 - PRINTING FORMS

More ways to print


Sesame offers a variety of other ways to print your data. One of these is to design and
use freeform or columnar reports in Sesame's Report Writer. For more on this, see the
Designing and Using Reports section in this Guide. Quick Reports can be built, and
saved, in Sesame runtime.

In addition, there are two choices of merging with a word processor. These are
described in the next section.

Another way to print involves adding programming to your forms (or Mass Updates)
that makes use of Sesame's powerful PrintString command. PrintString gives you
options for specifying the font face, font size, type of enhancement (bold, italics, etc.),
where to start printing on the page, and the number of columns in which to print the
data. You can even use PrintString to print merge-like documents right from your
records, where only the fields you select will appear in the printed output merged in
with any fixed text you choose. See the Sesame Programming Guide for more
information on using PrintString.

For merge printing more sophisticated documents such as formal business letters and
invoices along with mailing labels and envelopes see the next section Merge
Printing Your Data.

327
Section 11
Merge Printing Your Data
You can use Sesame to easily produce form letters, envelopes, and mailing labels
using the data in your application files by merging the data with documents you create
in your favorite word processor. This is called mail merge or merge printing because it
allows you to take specific information from your database and merge, or insert, that
information into a standardized letter or other document for one, a few, or all the
records. The same data can also be used to merge print envelopes and mailing labels.

Merge documents
Sesame helps you create merge solutions in three ways:
Merge File Print
Merging via data export
WordMerge
The first two methods do not necessitate any programming. WordMerge needs some
programming to be pasted in.

The basic process involves creating a Sesame application and entering into it the
information youll want to include in your merge document. Then, with one of the
above options in mind, designing a form letter (mail merge document) in a word
processing program to merge in that information. The final step is printing the merged
documents.

Merge File Print


The Merge File Print command appears under the Record Commands/Printing
Commands and the Results Commands/Printing Commands sections of the menu tree.

Figure 1 Merge File Print commands for one record and for the result set.

329
11 MERGE PRINTING YOUR DATA

Merge File Print enables you to perform basic merge print operations from Sesame.,
without any programming. When using this command, a file open dialog prompts you
to select a saved merge file from the list. You can browse to find the file.

The merge file must be an ASCII (human readable) formatted file, such as a plain text
file (.txt, .asc, etc.), a rich text file (.rtf), a postscript file (.ps) or an HTML file
(.htm/.html). When you've selected such a file, Sesame scans it, looking for layout
element names contained in double square braces -- [[Company]], for example. For
each one found, Sesame replaces it with the corresponding value from the current
record. After performing this find/replace operation on the entire file, Sesame then
sends the merged file to the printer.

Use Merge File Print (Current Record) to merge print the current record only. Use
Merge File Print to merge print all the records in the result set.

A Merge File Print merge document can be composed in Microsoft Word. After
composing it, you can save it, for example, as an .RTF file using Word's File / Save As
/ Save as Type feature.

Here's a simple example of a merge document:

Dear [[First]] [[Last]],


I heard that you like [[Hobbies]].
Regards,
Bob Smith

For the first record in Customers.db, Merge File Print would print this:

Dear Mary Wilman,


I heard that you like GOLF.
Regards,
Bob Smith

Note that the double square braces used are the actual square braces available from
your keyboard. They are not the special characters that Word inserts to delineate a
merge field. This allows this command to work with virtually any word processor
available for Windows or Linux.

There is a corresponding MergeFilePrint() programming command that supports a


variety of options for more advanced merge printing tasks. See the Sesame 2.0
Programming Guide for more information. Basic use as described above though
involves NO programming you don't need to go into Sesame Designer.

330
11 MERGE PRINTING YOUR DATA

Merging via data export


Another way to create a merge letter is to use Sesame to export whats called a data
source file, and use Microsoft Word, Corel WordPerfect or other modern word
processor to design your merge document or mailing label or envelope template
with a link to that data source or export file. (In this regard, export file and data
source file are synonymous.) This method requires more steps than the File Print
Merge method described above, but does leave you with a normal form letter in your
chosen word processor and so offers more versatility as you can use advanced
features of that word processor.

Follow these steps to export a data source file for use in a merge document:

1. In Sesame, retrieve and sort the records you want to include in your merge
document, label template or envelope template.
2. In the Spec window in the lower left part of your screen, right-click on the action
bar and Select Export to display the export spec. Click on the fields you want to
include in the export. Or Left-click on the action bar and click on Set All to
export all fields. Left-click on the action bar again and click Run. (See Figure 2.)

Figure 2. Creating an Export spec.

331
11 MERGE PRINTING YOUR DATA

3. In the ASCII Export options dialog that displays (See Figure 3), click on Field
Name Header to select it. In the ASCII Export Filename field, type in the
complete path and filename for the export file you are about to create. Make
sure to give the file a .txt extension. Leave all the other settings as defaults
(Comma Separation, Delimit Strings and Double Quote Delimiter) and click
Accept.

Figure 3. Setting export criteria and saving the export file as a text file.

4. Open your word processor and use its wizards or menus to create your merge
letter. (Consult the documentation for the product you are using.) When you are
prompted for the data source to merge with the document, be sure to select
Text Files (*.txt) and choose the export file you just created. Insert the merge
fields in your document and you are ready to print. Figures 4 and 5 illustrate a
sample merge document being created in Microsoft Word XP.

332
11 MERGE PRINTING YOUR DATA

Figure 4. Inserting merge fields in a Microsoft Word XP merge document.

Note: Both MS-Word and Corel WordPerfect have very good in-product help
on merging data from an external text file. The exact steps vary between the
products and from version-to-version within each product.

Once you are satisfied with the merge document youve created, save it. It will now be
permanently linked to your Sesame export file. All you need do to perform a new
merge printing using that same document is retrieve a new set of records in Sesame
and export them to the same filename. Then, when you open your saved merge
document, it will automatically merge with the new data now contained in the export
file.

333
11 MERGE PRINTING YOUR DATA

Figure 5. An example of completed merge letter with the data merged in.

WordMerge
Described just above is how to perform an export, manually, so that the exported data
can be used in an external word processor. The user would then go to the word
processor, choose a merge document and open it. WordMerge, once set up, automates
many of these steps. WordMerge can be used with any word processor that supports
mail-merge to an ASCII or CSV file, such as Microsoft Word and Corel WordPerfect.
The examples below use MS Word.

WordMerge is not built in to Sesame as a feature; it does not appear on any Sesame
menu. It is also not a third-party utility. It is a program which can be attached to a
command button you create on a form in Sesame Designer. To add WordMerge
facilities to a form you:

1. Prepare a list of fields you want included in the data exported


2. Open the form in Designer
3. Add a command button
4. Paste in the WordMerge programming
5. Change 3 values (telling where merge documents are located for example)
.. and then save the programming and apply these changes to your application.

The process should take no more than an hour and once added is self-maintaining and
will not need any further changes.

334
11 MERGE PRINTING YOUR DATA

WordMerge is popular because it provides scope for a developer to add refinements


such as derived export fields (calculated on the fly) and advanced logic and formatting
in the Word document. The process can be totally automated if required.

Using WordMerge

Create your merge documents in Word. They can be as fancy as you like and
include graphic elements such as your company logo and digital signature. They
can be simple merge letters. They can have a sophisticated invoice-like or other
form design with rows and columns of merged data inside tables. They can be
documents that merge print envelopes or sheets of mailing labels.

Add a Command button named Merge Print or the like to your Sesame database
form. When you click on it, programming attached to the button performs the
following actions:

1. Displays a menu of your available WordMerge documents, such as "Thank


You" letter, "Follow-Up" letter, "Final Invoice," "Avery 5160 Labels" and so
forth. You can have as many documents available on this menu as you
need.

2. Asks you if you want to include just the record currently on-screen or all
the records youve retrieved. (This could be all the records in the
database.)

3. When youve chosen a document to merge print, programming generates


a "data source" file for Word with the data from the selected record or
records. The program then starts Word and automatically opens the merge
document. The data is already merged. You simply click the Merge to
Printer button to print the documents, then exit Word to return to the
Sesame database record you were on.

WordMerge also makes it easy to copy one already-prepared merge document with a
different name, edit it, and it will automatically appear on the picklist next time.

To set up WordMerge in your application, refer to the notes in the PDF document
provided with Sesame: Setting Up WordMerge.pdf which is found in the Sesame\Docs
folder. There is also a sample application in the Sesame\Data\Samples folder which
allows you to try out WordMerge easily without any setting up. Sample merge
documents and mailing labels are included.

335
Section 12
Import, Export and Copy Records
Data management tasks can include populating or filling Sesame applications with
data from files created by other programs or systems, or outputting data from Sesame
applications in formats that other programs and systems can use. This is called
importing and exporting.

Sesame can import and export data to and from a variety of common formats
supported by most programs which themselves have import and/or export capabilities.
If an external program has facilities for exporting its data, chances are good that you
can have it create a file that can then be imported into a Sesame application. If an
external program has facilities for importing data, chances are good that you can have
Sesame create an output file that the other program can then import.

Copying records consists of populating a Sesame database with records from another
Sesame database, without having to go through separate export and import
procedures.

Note: Sesame's facilities for importing and exporting data require no


programming. However, Sesame's programming language has its own
capabilities for reading ("importing") the data in external files as well as
generating ("exporting") data to external files. For details, see Parsing a
Delimited File and Importing Records with Programming Only, in the
Sesame Programming Guide.

Note: In the sections on import and export, you will see the term "Standard
ASCII." This indicates a text-only file format designed to store data values of
variable length, usually delimited by quotes and separated by commas.

Importing Data

Importing is the process of bringing into a Sesame application data created by other
programs or even another Sesame application. Such data must be imported into an
existing Sesame database and form.
Q&A
You do not use Import to bring a Q&A database into Sesame. You use
Translate Q&A from Sesame's main menu. However, you can export data from
Q&A to Standard ASCII format, and import the resulting data file into an existing
Sesame database as you would any other importable file.

File format for import file ASCII


Sesame can import comma-delimited Standard ASCII files. These are also called "csv"
files (comma separated values) or plain text (.txt) files because they can be viewed

337
12 IMPORT, EXPORT & COPY RECORDS

and worked with in a text-only editor such as Windows Notepad. ASCII files can be
created by many programs. Most database and spreadsheet programs can create
delimited ASCII files, and even word processors can be used for this purpose.

An ASCII import file has the following characteristics:

One record per line.


A carriage return/linefeed delimits each record.
A comma or other character(s) separates each data value.

ASCII import files may have text values (as opposed to date or numerical values)
enclosed within quotes. Or they may not. They might have all data values enclosed in
quotes. Sesame will accept any values with or without quotes as long as they are
separated by commas or some other delimited character.

If you are importing any data text or numeric that contains delimiters as part of
the data values, such as 120,595 or Susan, John and Linda, such values must be
enclosed in quotes, like this: "120,595" and "Susan, John and Linda".

A typical ASCII import file one that could be imported into an application such as
Countries.db might look like this:

"Afghanistan","Kabul",19.5,657,"Asia"
"Albania","Tirane",2.5,29.0,"Europe"
"Algeria","Algiers",17.3,2383.0,"Africa"
"Angola","Luanda",6.4,1247.0,"Africa"
"Argentina","Buenos Aires",25.7,2777.0,"America"
"Armenia","Yerevan",,,"Asia"
"Australia","Canberra",13.8,7687.0,"Australasia"
"Austria","Vienna",7.5,84.0,"Europe"
"Azerbaijan","",,,"Asia"

Notice the following about this sample file:

In this case there are quotes around the text values such as the country
name, but not around the numerical values such as the area and population.

There is no header row showing the field names.

Blank fields (such as the population and area of Azerbaijan) can be


represented by two commas with nothing in between. These are placeholders
for missing data. Each line must have the same number of data fields,
including blanks. If a data value is blank, Sesame will also accept either " " or
"" that is, quotes with a space in between, or without a space. This is
evident in the second field (for the capital) in the Azerbaijan record in the
sample file above.

338
12 IMPORT, EXPORT & COPY RECORDS

Another type of file you may need to import is called a Fixed ASCII or table ASCII file,
where the data is organized in columns of fixed widths and any "area" between the
columns is "padded" by spaces or another character, such as a 0 (zero) in the case of
strictly numeric data. These types of data files are less frequently encountered than
Standard ASCII files. Although Sesame does not import Fixed ASCII files directly, it is
possible to convert such files to Standard ASCII format using tools in Sesame's
programming language. Alternatively, the data for each record can be imported into a
text field in the database, then a mass update used to parse (separate) the data
values and distribute them to the correct fields. This can be done, for example, by
knowing the starting column position of each data value and using the @Mid function.
See @Mid in the Sesame Programming Guide.

How to import
You import into an open form in either Add Data or Search/Update mode. In either
case, the imported records are added to the existing result set, and you can
immediately perform actions on them, such as printing them in a report, mass
updating them, or even mass deleting them!

The steps involved in importing an external data file into the Countries database using
the Countries form are as follows:

1. Review the data file you are about to import, so that you know the position of
each data value within the file.
2. Open the Countries form in Search/Update (with a set of records retrieved) or
Add Data mode.

Figure 1. Form open in Add Data, selecting Import spec in the Spec Window.

3. Right-click the Spec Action bar, or use the Spec selector buttons (with the
arrows), to display the Import Spec. (See Figure 1.) For full details on using the
spec window, see page 46.
339
12 IMPORT, EXPORT & COPY RECORDS

4. Click on the element selector (the button just to the left of the element name)
for each layout element into which you wish to import data. As you click on each
one, the element name is moved to the top of the list and the element selector
acquires an "I" to indicate that this is an element to receive imported data. See
figure 2.
5. Repeat the above step for all elements that are to receive imported data.
The Import Spec window has a first column which shows the 'column number' of the
file to be imported (see figure 3 below). This is a convenience that can be useful for
matching up columns with fields in the import spec.

Ignoring columns
As you select elements, the item that was at the top of the list [IGNORE COLUMN]
is moved down. Ignore column is a placeholder that represents a data value or field
in the import file that is not to be imported. The word "column" is used because if you
were to open the ASCII file in a spreadsheet program, each field would be a column in
the spreadsheet. You must have as many elements in the Import spec marked for
import as you have fields in the import file. If you are only importing some of the
columns then you must add IGNORE COLUMN rows for the others.

For example, suppose you have an ASCII file containing three fields in the following
first name, middle initial, last name format:

"Frederick","J","Anderson"

You want to import the file into a form containing just FirstName and LastName fields.
In this case, your Import spec would look like the one shown in Figure 2.

Figure 2. Importing only two of the three fields in an import file.

It is important that the rows in the Import spec match the order of the columns in the
import file. To move an element name up or down in the spec window, drag it up or
down. Alternatively, click once on it to select it and then press Shift-Up arrow or Shift-
Down arrow to move it up or down the list. You can only move layout elements
marked with an "I". A completed Import spec for importing countries-related data
might look like the one shown in Figure 3.

340
12 IMPORT, EXPORT & COPY RECORDS

If you need to suppress the import of more than one field (column) of the import file,
then you can replicate more IGNORE COLUMN placeholders by clicking on the "R"
button alongside its element selector. Another IGNORE COLUMN is created, which you
can then position as desired.

Warning: If you select Set All from the


Spec Action Bar, the [IGNORE COLUMN]
marker will remain at the top of the list
and be enabled.

This will have the effect of ignoring the


first field of the import file, so that the
data from the second field of the import
file is put into the first enabled layout
element of the Import spec. This is called
a data shift. To avoid data shift, click on
the "I" in the layout element selector for
[IGNORE COLUMN] to disable it. It will
move to the bottom of the included
Figure 3. The completed import spec. Five
fields are to be imported in this example. elements list, as in Figure 3.

You can save an Import spec either before or after performing the import. To learn
about saving and reusing specs, see Using the Spec Manager in the Mass Updating
section of this Guide.

Running the import


To run the import, you can do one of the following:

Select Import Data from the Results Commands menu.


Select Run from the Spec window Action bar.
Press Alt-R, the shortcut key for Run.

The "Select a File to Import" dialog opens. Specify the location and file you wish to
import, the click on Accept.

The file is imported in accordance with the current Import spec. If the import is
successful, the new records are added to the result set and a message is displayed on
the status line telling you the number of records imported. (See Figure 4.)

341
12 IMPORT, EXPORT & COPY RECORDS

Figure 4. Import complete. Nine records imported. See message on status line.

In the example shown in Figure 4, the message says "Imported 9 top level records..."
because the Countries form includes a Cities subform. Records were imported only into
the main form hence Top Level.

You can see this in the import spec (Figure 4) where only the main form elements are
marked with an "I". The subform elements Cities!City and Cities!Population are not
included in the import. If they were, Sesame would have intelligently imported the
data into the appropriate databases (assuming your Import spec was in accordance
with the import file.) For information on importing into subforms, see the Working with
Subforms section in this Guide.

342
12 IMPORT, EXPORT & COPY RECORDS

Import errors
If there are errors on importing, you will see a message like that shown in Figure 5.

Figure 5. Import Errors message box.

In this case, you will want to view the error log. To do so, select Server Administration
from File menu on the main Sesame menu bar. You will be asked for a user name
(Login:) and password.

The login name is admin and the default password is hello. Both are case sensitive.

Once in Server Administration, click on the Logs tab and you will see a list of errors
and warnings. There will be a line in the log for each record in the import file that
generated an error and, because of that, was not imported.

A typical example might look like this:

Error: Number of fields (6) in ASCII file C:\sesame\data\Countries_A.txt on


line 9 does not match number specified: (7)

This indicates that the Import spec did not match the import file with respect to the
number of fields.

Importing data into subforms


Importing into subforms is covered separately in the Working with Subforms section of
this Guide.

Exporting Data

Exporting copies data out of Sesame for use by other programs or other Sesame
applications. Sesame exports ASCII files. ASCII files can be read by most other
programs. Sesame's ASCII export facilities are quite versatile you have a great
degree of control over the format of your export file. Like Import specs, export specs
can be saved and re-used.

343
12 IMPORT, EXPORT & COPY RECORDS

File format for export file ASCII


Sesame can export comma-delimited Standard ASCII files. These are also variously
called "csv" files (comma separated values) or plain text (.txt) files because they can
be viewed and worked with in a text-only editor such as Windows Notepad. ASCII files
can be imported into many programs. Most database and spreadsheet programs can
import delimited ASCII files. Modern word processors such as Microsoft Word and
WordPerfect can use ASCII files as data source files for mail merges.

A Delimited ASCII file has the following characteristics:

One record per line.


A comma (,) or another character often separates each field, but not
necessarily.
No header record, usually, though Sesame can add a field name header if
desired.

ASCII files often have text values (as opposed to date or numerical values) enclosed in
quotes. Or they may not. They might have all data values enclosed in quotes. You
have control of all of these settings when you export from Sesame.

A typical ASCII file in this case, one that has been exported from Countries.db
can be seen in the preceding Import section.

Sorting of Export files


ASCII Export sorts the exported records based on the order of the records in the result
set, as set by the sort spec, unless the records to be exported include fields from
subrecords. In the case where subrecords are being exported with main records, the
exported records are sorted in exported field order.

How to export
You export from a result set. The form can be open in Add Data or Search/Update
mode. The steps required to export are as follows:

1. Obtain a result set by running a search or by adding new records in Add mode.
2. Right-click the Spec Action bar, or use the Spec selector buttons (with the
arrows), to display the Export spec.
3. Select the layout element names that represent the fields you want to export.
4. For each element, specify the parameters if you want anything other than a
Standard ASCII export. (See Fixed ASCII Export and Truncating Values below,
for information on setting Fixed or Max for any element.)
5. Arrange the elements in the order you want them to appear in the output file.
(See Figure 6.)

344
12 IMPORT, EXPORT & COPY RECORDS

Figure 6. Exporting three fields from Countries.

6. You can save the Export spec before or after performing the export. To learn
how to save and re-use specs, see Using the Spec Manager in the Mass Updating
section of this Guide.
7. Run the export in one of the following ways:

 Select Export Data from the Results Commands menu. (See Figure 6.)

 Select Run from the Spec window Action bar.

 Press Alt-R, the shortcut key for Run.


8. The Export dialog opens. Specify the settings you wish to use for the export
the defaults will give you a standard ASCII file and the location and filename
for the export file. (See Figure 7.)

If the location for the output file is the same as for your Sesame applications,
type just the filename as shown in Figure 7. If the location is elsewhere, type
the full path and filename.
9. Click on Accept.
The data in the current result set is exported to an ASCII file in accordance with the
current Export spec. A message appears on the status line like this one:

Wrote ASCII file From_Countries.txt


345
12 IMPORT, EXPORT & COPY RECORDS

The various options available on the ASCII Export dialog are covered below.

Figure 7. The ASCII Export dialog. Export file is named "From_Countries.txt."

Using Sesame's default export settings, the ASCII file for the Export spec shown in
Figure 4 above will look like this:

"Afghanistan","Asia",657.000000
"Albania","Europe",29.000000
"Algeria","Africa",2383.000000
"Angola","Africa",1247.000000
"Argentina","America",2777.000000
"Armenia","Asia",
"Australia","Australasia",7687.000000
"Austria","Europe",84.000000
"Azerbaijan","Asia",

346
12 IMPORT, EXPORT & COPY RECORDS

Exporting does not alter your result set. It simply copies your data to an external file.
It does not change the current database.

Sort Order of Export


The output file will be sorted in accordance with the sort order applied to the result
set, as long as the export is single level. A hierarchical export forces the sort it needs
to function properly. If you don't apply a sort, the sort order is undetermined.

ASCII options
Sesame is quite versatile when it comes to ASCII file export options. If you need
specially formatted output files, you can change your options at the ASCII Options
dialog. (See Figure 8.)

Figure 8. ASCII Export options with defaults shown.

The Separator
The separator is the character that separates the data values in the export file. You
could say that it separates the "fields" in the export file, if that's how you like to think
of it.

347
12 IMPORT, EXPORT & COPY RECORDS

The default separator for a Standard ASCII file is a comma, hence the term "CSV file"
for Comma Separated Values a type of Standard ASCII file.

Sometimes a tab separator may be required, another option.

Should you require a different separator, you can select Custom Separation, then
specify the character in the adjacent text box. (See Figure 9.)

Figure 9. Here, "%" used as Custom Separator.

Commas are used as separators in this example:

"Australia","Australasia",7687.000000
"Austria","Europe",84.000000

You can also specify No Separator. This is required for Fixed ASCII files with fixed
column widths. (See below). For Standard ASCII file export with variable "column
widths," No Separator would be an unusual option as it would join the field values
together into a continuous string.

348
12 IMPORT, EXPORT & COPY RECORDS

The Delimiter
It is common in Standard ASCII files to enclose text values in double quotes. The main
advantage of this is that data values can contain the separator character (usually a
comma) with no danger of them being interpreted as a field delimiter. The following
example illustrates this:

"Mr","Henry","Kestel","Nanker, Phelge & Partners","5060 Poppy Place, Apt


284","Delray Beach"

Without the quotes around the text values, there would appear to be two additional
fields, and the record would not be correctly imported by the destination program.
This Delimiter option lets you specify a double quote delimiter (the default), or no
delimiter.

Fixed ASCII files generally have no delimiters or separators. Should you require a
different delimiter, you can select Custom delimiter, then specify the delimiter
character in the adjacent text box. (See Figure 10.)

Figure 10. Here, "^" is specified as the Custom Delimiter, and Field Name Header has been
selected.

Delimit Strings/Delimit All Fields


This option specifies whether the delimiter character (normally double quotes) is used
to enclose all fields or only text fields. It is typical not to enclose number, date,
currency and time fields in double quotes. However, some programs demand it, so
Sesame gives you this option. Sesame also allows you to export numbers where a
comma is used as a decimal point or thousands separator, such as "120,534".

Field Name Header


ASCII files generally do not include a header record of field names the whole file
consists of just data records. However, some programs can make of use the field
names if they are added as an optional "first record."

349
12 IMPORT, EXPORT & COPY RECORDS

Even if the intended destination program will ignore (bypass) a field name header,
including it in the export file can be useful, as it helps to identify the source and
structure of the data. It is also very helpful when using export to generate data source
files for use by external word processors and spreadsheets. For example, when
exporting a file for use by Microsoft Word as a data source merge file, a field names
header enables you to insert your merge fields in a letter or mailing label using a
convenient pick-list of field names.

Here's an example of an ASCII export file containing a field name header:

"Country","Continent","Area"
"Afghanistan","Asia",657.000000
"Albania","Europe",29.000000
"Algeria","Africa",2383.000000

Ignore Fixed/Max Lengths


Selecting this option tells Sesame to ignore all settings for fixed or maximum lengths
set in the Export spec. The export is run instead as a Standard ASCII export, not a
Fixed ASCII export. Fixed ASCII exports are described below.

Fixed ASCII export and truncating values


Sesame can export to Fixed or Table ASCII files. Such files have their data arranged in
fixed width columns. Compare this output format with a Standard ASCII file where the
data values (fields) are of variable length.

Sesame offers two options for changing the export file from the more typical Standard
ASCII type file to a fixed format.

The default is "Open" signified by an "O" in the element selector. The three settings
available in the Export spec window are shown in the following table.

Symbol Type Result

O Open Variable column width. Export the entire value regardless of


length.

F Fixed Fixed column width. Make the value the specified number of
characters in length. Truncate it if it exceeds that length. Pad it
with spaces if it is shorter.

M Max Variable column width. Export the whole value up to the


specified number of characters.

Having selected an element for export in the Export spec window, you can change the
"O" default to "F" or "M" by clicking on the "O" alongside the element name. It toggles
between the three values. When F or M are set, an extra text box appears to the right
350
12 IMPORT, EXPORT & COPY RECORDS

of the element name where you type in the number representing the number of
characters you want. (See Figure 11.)

Figure 11. Setting Fixed and Max values when exporting data.

Note: Sesame will let you set a maximum export character limit for
number, date, time and currency fields. This may produce what you
want, such as just the year for a date field (max 4). But it could instead
produce results which are not meaningful. For example Max 3 of
$1,234.56 is "123"; Max 2 of 1.2345 is "1."

The following file structure has a fixed width of 14 characters for each data value, with
no separator or delimiter. It is a Fixed ASCII file:

Afghanistan Asia 657.000000


Albania Europe 29.000000
Algeria Africa 2383.000000
Angola Africa 1247.000000
Argentina America 2777.000000
Armenia Asia
Australia Australasia 7687.000000
Austria Europe 84.000000

This following file has a max width of seven characters for each data value, with a
comma separator and no delimiter:

Egypt,Africa,1002.00
El Salv,America,21.0000
Equator,Africa,28.0000
Ethiopi,Africa,1222.00
Fiji,S.Pacif,18.0000

Notice that El Salvador, Ethiopia and S.Pacific have been truncated, and that the data
is not aligned in fixed-width columns.

351
12 IMPORT, EXPORT & COPY RECORDS

You can mix Open, Fixed and Max within the same Export spec to produce the type of
export file you need to create.

Exporting data from subforms


If you include in your export only fields from the main form not the subform then
you will get a simple generic export file. Exporting from subforms is covered
separately in the Working with Subforms section of this User Guide.

Layout elements on the subform(s) appear under those of the parent form in the
format ParentFormName!SubformLayoutElementName, as shown for the Cities!City
subform in Figure 11 above.

Exporting multi-line text fields with carriage returns


A multi-line text field can contain carriage returns. ASCII export options do not
support these in data values because carriage returns are always used as record
delimiters. Carriage returns/line feeds, when exported, are converted to the \n
(backslash followed by n) combination. Many programs recognize this combination as
a carriage return/line feed and will accommodate it accordingly.

Here's example from Gems (\n is shown in boldface):

"The most valuable sapphires have a medium intense, vivid blue color.
\nThe best sapphires hold the brightness of their color under all
different types of lighting.\nAny black, gray, or green overtones
mixed in with the blue will reduce a stone's value."

If the destination program does not automatically convert the \n combination to a


carriage return/line feed, you can perform a find and replace operation to replace each
occurrence of \n with some other character(s) or a carriage return for that program.

Export Limits
There are no limits on the number of fields, the number of records, or the total output
file size. There is a limit of 4Kb for a single field, in a single record. So if you have a
comments field and for one record there is over 4k of text in it, that will be truncated.

Copying Records

Sesame's Copy command allows you to copy selected forms (records) from one
Sesame form (database) to another. You can copy all the layout elements (fields) or
just selected ones.

 Copy copies records into the current form from another open form.

352
12 IMPORT, EXPORT & COPY RECORDS

 The form you are copying records from must be open in the Sesame
session and in the same application.

 All records in the current result set in the source form are copied to the
destination form.

 One new record is created in the destination form for each record in the
result set in the source form.

 Only fields represented by layout elements on the forms can be copied.

 Layout elements can be matched by name or matched manually, if the


names are different.

 Read-only elements do NOT receive data.

Q&A
Sesame's Copy command copies records INTO the current form from another
open form. This is the opposite of Q&A. In Q&A, you copy records FROM the current
database to the destination database. Q&A uses "field position numbers" on the form
to specify the matching fields in the destination database. In Sesame, the positions of
layout elements on the two forms are irrelevant.

How to copy
In the example detailed below, there are two databases in the application:

 Countries, with a subform named Cities.

 More Countries, with a subform named More Cities.

Each database contains a form with the


same name as the database. They appear on
Sesame's menu tree as shown in Figure 12.
In this example, records are to be copied
between the main forms in each database.
Records from the subforms will not be used.

There are only 10 records in Countries. You


want to copy the records in More Countries
to Countries. More Countries is the Source;
Countries is the destination.

Figure 12. Countries and More Countries.


The steps are as follows:

353
12 IMPORT, EXPORT & COPY RECORDS

1. Find the records you want to copy. Open the More Countries form in
Search/Update mode and run a search to obtain the result set you want. All the
records in the result set will be copied. Sorting is irrelevant.
2. Leaving the More Countries form open, click on the Application Menu tab.
3. Open the destination form Countries. You can be in Search/Update mode (in which
case the copied records are added to the current result set) or Add Data mode.
4. In the Spec window, use the Spec selector arrows to show the Copy Spec. You will
see a list of all the layout elements (fields) on the form and subform.
5. Double-click any layout element name. The Copy dialog opens. (See Figure 13.)

Figure 13. The Copy dialog when first opened.

The destination elements and source elements are listed, but no matching has
been set up. You can change the source elements from the dropdown at the top of
the dialog.
6. Click on the Source dropdown. (See Figure 14.)

354
12 IMPORT, EXPORT & COPY RECORDS

Figure 14. The Source dropdown listing the valid source forms.

The source dropdown lists four forms in this case the two open main forms and
their respective subforms. When a form is open, its subform is open.
The mode for each form is also shown. As you might want to copy records within
the same database by having the same form open in Add and Search/Update
modes, having the mode shown allows you to work out which is which.
In this case the source is the More Countries form, in Update mode.
If the layout element names match, you can click on the Match Names button.
7. Click on the Match Names button in the lower part of the dialog. This matches
elements on the two forms if they have the same names. Having matched names,
you can make alterations later if you want you will see an example later. The
Copy dialog should now look like Figure 15.

Figure 15. Result of matching element names.

8. Click on Close to close the Copy dialog. The Import spec now shows in the spec
window, as shown in Figure 16.

355
12 IMPORT, EXPORT & COPY RECORDS

Notice that there is a "C" for Copy


in the row selector for each
element name that is to receive data.

Also, alongside each grayed is


the element name of the source form
that is supplying that data.

Figure 16. The completed Copy Spec window.

9. At this stage, you have the


option to save this Copy Spec using the Spec Manager. You could also save it after
running the copy operation. How to save and re-use specs is covered in detail
under the Using Spec Manager heading in the Mass Update section of this Guide.
10. Run the Copy operation in any of the following ways:

 Select Copy from the Results Commands menu.

 Select Run from the spec window's Action Bar.

 Press Alt-R, the shortcut key for Run.


11. Sesame displays a dialog (see figure 17) that tells you how many records will be
copied into the current form. Click on Yes to complete the copy operation.

The new records are copied to the database and are viewable immediately as part of
the result set in Update mode or as added records in Add mode.

Figure 17. Confirm dialog showing number of records to be copied.

Disabling individual elements


The Import spec shows the layout elements (fields) that will receive data. Enabled
elements are tagged with a "C". You can click on a "C" to disable that element for the
copy operation and that field will receive no data. The element moves lower down the
list so that the enabled ones are all listed first. (See Figure 18.) Clicking on the tag

356
12 IMPORT, EXPORT & COPY RECORDS

again will re-enable it, using the same matching. Whenever you open the Copy dialog
and close it, all matched elements are again enabled and included in the copy
operation.

Figure 18. The Copy spec with some elements disabled.

Manual element matching


In the Copy dialog, you can click on the Match Names button, then manually alter the
matching elements. Below is a summary of the actions possible at the Copy dialog.
Read it in conjunction with Figure 19.

To add an element Drag an element name from the Source Elements


column to the Destination Elements column and drop
it on the element you want to match it with.

To remove an element Drag it from the Destination Elements column to the


Source Elements column.

To change a match Drag an element name and drop it on a different


element.

To match all element pairs Click on the Match Names button.


with the same name

To clear all matchings Click on the Clear button.

To store these parameters Click on Close.


and return to the Copy
spec

To save this Copy spec Use the Spec Manager.

357
12 IMPORT, EXPORT & COPY RECORDS

Figure 19. Manually matching elements.

Copying the same field to multiple destinations


At the Copy dialog, you can take one element name from the Source Elements list and
drop it onto multiple elements in the Destination Elements list. This copies the data
from one field in the source form into multiple fields in the current form.

358
12 IMPORT, EXPORT & COPY RECORDS

XML Utilities

Export Application to XML


Export Application to XML is used to translate an entire application, data, design and
structure to a single XML file. This file can then be read by the XML Database
command (on the File menu) to recreate that application from XML. Because XML is
human readable, this command can be used to examine, diagnose and repair Sesame
databases. Because XML is a standards based format, this command can be used to
allow Sesame applications to be edited in programs other than Sesame. Because the
XML format is human readable, and can viewed and edited in an ordinary text editor,
care should be practiced to ensure that Sesame XML files are carefully managed.

The Export Application to XML command is on the Application Utilities branch of the
Application Menu. After the Export Application to XML command is selected, a file
dialog appears to allow the user to select the filename of the file to be saved as XML.

XML Database
The XML Database command on the File Menu imports a XML representation of a
Sesame application. See the section: XML Database in the Data Management and
Manipulation section in the XML Utilities section for details.

Export Design to XML


Export Design to XML translates the design of the current Sesame application to XML
and saves it to a XML file. The design includes Form and Report designs,
programming, specs, and other structural elements other than user data.

The Export Design to XML command appears in Sesame Designer under the
Application branch of the Design Menu. After the command is selected, a file dialog
appears allowing selection of the filename for the XML file that will be created.

The XML file produced by Export Design to XML can be opened in Sesame Runtime or
Designer using the XML Database command from the File pulldown menu. Because it
excludes data, this command will produce an "empty" application containing only the
forms, reports, and underlying structural pieces that comprise the design.

Warning on export to XML


Warning on export to XML as to size and complexity of doing this on a
large application, It can tie up system for hours. A small file like
Customer.db creates an almost 1Mb file.

Export Layouts to XML


The Export Form to XML and the Export Report to XML commands export the current
form or report design to a XML file, including specs, attached specs, and other details.

359
12 IMPORT, EXPORT & COPY RECORDS

These commands can be used to copy Forms and Reports to different databases or
applications.

These commands appear in the Commands control panel when a form or report is
open in Design mode. A file dialog appears to allow selection of a filename for the
resulting XML file.

Import Layouts from XML


A form or report exported as XML can be read into an existing database in an
application using the Import XML Form command or the Import XML Report command.
These commands appear under the Manage a Database branch of the Design Menu. A
form or report imported into Sesame as XML will ordinarily need to be relinked to a
database in order to be used. See the Relink Form command.

360
Section 13
Working with Subforms
Subforms are a way to view the records from a second database from the form of a
master database, so that you can see records from both databases at the same time.

Typically, you use subforms to display records where there is a one-to-many


relationship between the master or parent records and their child subrecords. For
example:

One company can have many departments.


One department can have many staff members.
One car can have many services.

The main form displays a record on the one side of the relationship, and the subform
displays records on the many side of the relationship.

A good example of this would be an Invoice form where each record is the invoice for
a customer, and the subform displays the individual line-items purchased on that
particular invoice.

A main form can have more than one subform. For example, a department can have a
subform listing employees in that department, and another subform listing cars in the
car pool for that department. Both these subforms are at the same level. For both of
them, the parent form is Department.

A subform can itself have a subform, or even multiple subforms. For example, a
company form can have a subform for departments, with the departments having the
employee and car pool subforms described earlier.

Subforms are dynamic you are not limited to just viewing your data. You can edit
data in a subform. You can delete records in a subform. You can add records in a
subform.

Using subforms
Most subform operations are the same as using a "regular" form. This section will
focus on describing the differences between using subforms and using regular forms.

Types of subform
There are two types of subform:

A Form-View subform is very much like a typical "main" or "parent" form


that contains it. Its layout elements are arranged as the database designer
placed them. It shows only one subrecord at a time. (See Figure 1.) Scroll-

361
13 WORKING WITH SUBFORMS

bars are available to view other parts of the subform if the entire subform isn't
visible.

Figure 1. A main form with a form-view subform.

A Table-View subform (See Figure 2) shows subrecords arranged in a table


or spreadsheet-like view. There are scroll-bars to view other parts of the
subform if it cannot all be seen. Table-view subforms are popular because they
show many subrecords (child records) at a time.

362
13 WORKING WITH SUBFORMS

Figure 2. Form with a Table-view subform.

Form Navigation

Moving between main form and subforms


When you have a subform on your form, you will actually be moving and navigating
through two separate forms. Once in the subform, all of the main form navigation
procedures apply see the section Navigating Forms in this Guide. When you are in
the main form, the subform is treated as another element as far as forward navigation
is concerned. You can Tab into the subform from the main form, or you can use the
mouse to click in the subform.

Once in the subform, you can fully navigate between elements with the keyboard, and
can navigate out of the subform with the Up Arrow key. You can also return to the
main form by clicking in any element on the main form. The Shift-Tab key will not
move you from a subform to the main form.

363
13 WORKING WITH SUBFORMS

Record-to-record navigation
When you are in a subform, the same rules apply to the set of subrecords as to a set
of main form records. F10 advances, F9 goes back, Ctrl-Home takes you to the first
record, and Ctrl-End takes you to the last record. You can also select these
commands from the Navigation menu.

When you are in the subform, the record navigation toolbar (See Figure 3) works as
usual on the set of subrecords, instead of the set of main records.

Figure 3. The record navigation toolbar.

Adding and editing data


Using a form-view subform is very like using a regular form. The main difference is
when the data is actually committed or saved to the database.

With a normal main form without a subform, it is simple. When you move to another
record your changes are saved. This "other" record can be a new blank record if you
are in Add Data mode, or another record in Table view, or another record viewed by
pressing F10 or F9 or using the navigation commands on the menu tree.

For a subform, the rules are somewhat different. The subform is a layout element on
the main form. The main form itself has to be saved, not just layout elements on that
form, even if one of them is the subform. So, as you work with subrecords in your
subform, you are saving them, but not completely. They remain unlinked to the parent
record (the main form) until you save the main record. The simplest way to do this is
to move the cursor to the main form, by clicking in it, for example, and then pressing
F10 or any of the other actions that will save the record.

There are some special keystrokes designed for working with subforms. These are:

Ctrl-F9 and Ctrl-F10 Save all and retreat/advance.


Shift-F10 Save all and close form.

Following is a summary of the relevant navigation keys:

F9 Saves and moves from the current record to the previous


record. In a subform, moves to the previous record in the
same subform.

CTRL-F9 Saves and moves to the previous record. In forms with a


subform, saves subrecords also and moves to the previous
main form record. Works in a subform.

364
13 WORKING WITH SUBFORMS

F10 Saves and moves to the next record.

Shift-F10 Saves the record and subform records and closes the form.

Ctrl-F10 Saves and moves to the next record. In forms with a


subform, saves the subrecords also and moves to the next
main form record. Works in a subform.

Adding new subrecords


1. In the subform, move to the last record by any means (keystrokes, navigation
toolbar, click on last record, etc.).
2. Use any method to advance to the next record. For a form-view subform, these
include:

 Press F10.
 Click on "next" button on navigation toolbar.
 Select Advance Record from the navigation menu.
For a table-view subform these are:

 Press F10.
 Click on "next" button on navigation toolbar.
 Press Down Arrow.
3. Enter the data.
4. Use any of the "Advance Record" techniques (F10 for example) to save this
subrecord and display a new, blank subrecord.

At this stage, saving your data is incomplete. As mentioned earlier, the subrecords are
unlinked. The main form record needs to be saved. If you click in the main form and
press Escape at this point you are warned that changes to this (main) record will be
lost if you continue.

To save the main record and all subrecords, do one of the following:

Click in the main form and press F10 or F9.


Click in the main form, then click on the "next" button on the navigation
toolbar.
Press Ctrl-F9 or Ctrl-F10 Save all and retreat/advance.
Press Shift-F10 Save all and close form.
Select any of these commands from the Navigation menu.

Parents and children


To some extent you can think of the relationship between main form records and
subform records as a parent/child relationship. This is particularly so if the main form

365
13 WORKING WITH SUBFORMS

and subform are set up using "natural linking," which is the default, rather than
relational linking.

Re-parenting
If using relational linking (matching fields) you can "re-parent" a subrecord by
changing the value it has in the field that links it to its parent record. If using natural
linking, there is no visible linking element, so you cannot re-parent the subrecord.

Orphan records
Thinking of the records in a subform as "children" and the record in the subform as a
"parent," you can open a form showing just the children the subrecords
themselves. The Cities form is an example. If you add records to the Cities form when
it is open by itself, either by typing the data in or importing, then these records will
have no parent. They will be "orphans." They will never appear in the subform of the
Countries form.

Deleting a parent record


If you delete a parent record, you also delete all the subrecords (child records)
attached to it, along with any subrecords of those subrecords, and so on. For example,
if in the Countries.db sample application you delete a country, you delete all its city
records as well. This applies even if you delete the country using a form that does not
have a subform. Sesame does not leave the subrecords in the database as "orphans."

Deleting subrecords
This is exactly like deleting main form records. To delete the current subrecord, either
press F3 or select Delete Record from the Record Commands menu. A confirmation
dialog appears. Click Yes to permanently delete the subrecord from the database.
There is no undo when you delete a record.

Mass Delete
You can, in Sesame 2, use Mass Delete in a subform. Click in the subform first. You
will be shown a confirm box asking you to confirm deletion of n records, where n is the
number of records in the subform. Check carefully that this is correct, and you are not
about to delete parent records by mistake.

Editing existing data

Note: Although the word "field" is used here, strictly speaking you are
manipulating data in a layout element on the form, not a field. A layout
element is a "container" in a form or report that displays the data in the
underlying database. The term "field" is commonly used in this context, and it
will be here too.

Editing data in a form-view subform is exactly the same as editing data in a regular
form.

366
13 WORKING WITH SUBFORMS

Editing data in a table-view subform is just like editing data in table view.

 To replace the data in a field, click or navigate to the field. Press Enter or
double-click on the field contents. Type the new entry from the keyboard. The
original data will be replaced.

 To edit the data in a field, click or navigate to the field. Press F6 to open the
expanded field editor and edit the data. Or, double-click on the field and use
the Arrow keys to move to the position where you need to start your edit.
Start typing. Text you type will be inserted into the existing text unless the
existing text is selected (highlighted), in which case what you type will replace
the selection.

Your changes to the field are saved when you move out of the field. Your changes to
the subrecord are saved when you move off the row the record is on using the Arrow
keys or by pressing F10 or F9 or clicking on another record in the subform. You then
need to save the main record.

As explained above, the subrecords are not yet saved. The main form record needs to
be saved. To save the main record and all subrecords, do any of the following:

Click in the main form and press F10 or F9.


Click in the main form, then click the "next" button on the navigation toolbar.
Press Ctrl-F9 or Ctrl-F10 Save all and retreat/advance.
Press Shift-F10 Save all and close form.
Select any of these commands from the Navigation menu.

Table view
If your subform is Form View (not table view) initially, then you can press Shift-F6 in
the subform to toggle the subform between form view and table view. See Using Table
View in the Adding and Editing Data section of this guide for details on using table
view.

Expanded field editor


You can press F6 in any subform field to open the expanded field editor, just as in a
regular form.

Mass Update
You can mass update subrecords just as main form records. In the Spec window in the
lower left part of your Sesame screen, you can show the Mass Update spec for the
main form, or the Mass Update spec for the subform. The name of the form is shown
on the Spec Action bar. The list of layout elements is confined to those on that form,
not the main form and subform mixed.

When you run the mass update, the only records updated are the subrecords that
belong to the main form record you are currently viewing. It does not matter where
367
13 WORKING WITH SUBFORMS

the cursor is in the main form or in the subform you still get just that main
record's subform records updated, not all records in the result set.

In the example below (see Figure 4), just three records will be updated the three
cities of Egypt. This is despite the fact that the cursor is in the continent field in the
main form. The reason for this is that the mass update spec is for the subform Cities,
with programming attached to the City element.

Figure 4. Mass update spec for the subform.

Printing forms
Print Form(s), Print Form(s) to HTML (on the Printing Commands menu) always print
the main form only. What is printed is a "snapshot" of the main form. Any subform is
printed exactly as you see it on screen.

Searching
There are a couple of significant differences between searching a regular form, or a
main form, and searching in a subform. The syntax what you enter as criteria for
your search is identical. The differences are in the records that are returned.

368
13 WORKING WITH SUBFORMS

Searching in the subform


The examples below use the supplied sample database Countries.db (see Figure 2 at
the beginning of this section). This is an application with two databases:

Countries, with a form named Countries


Cities, with a form named Cities

The Countries database contains 154 records.

The Cities database contains 726 records. You can view just the cities by opening and
searching the Cities form itself, rather than the Countries form.

Searching in the main form is straightforward:


Country: a..
This retrieves nine records for the countries that start with the letter A. They are
shown in Figure 5 in Table view.

Figure 5. Countries beginning with "A".

Performing the same search in the subform may produce surprising (yet correct)
results. If instead of searching the main form, you search the subform (see Figure 6
below), the results will be quite different.

The first record retrieved is Algeria, with the one city Algiers. When you click in the
main form, the record counter tells you that you are looking at record 1 of 22.
Advancing to the next record shows Australia with nine Cities (Adelaide, Brisbane,
etc.), followed by Belgium.

369
13 WORKING WITH SUBFORMS

Figure 6. Searching the subform instead of the main form.

What's happening here is that Sesame is retrieving exactly what you requested:

Countries that have a city beginning with "A"

Belgium qualifies because it has the city Antwerp. It does not matter where in the list
of cities the qualifying record(s) are. There are 22 countries in the database that have
one or more cities beginning with the letter A.

If you want to retrieve a list of all


the cities starting with "A", then you
should not be searching the
Countries form. Searching the
Countries form will show you
countries that meet your criteria. To
find the cities starting with A, open
the Cities form and search that, as
shown in Figure 7. This produces 41
cities all beginning with A.

Figure 7. Searching the Cities form. The first 15 of these are shown in
table view below in Figure 8.

370
13 WORKING WITH SUBFORMS

Figure 8. Results of searching the Cities form.

Searching for blank fields


If you browse the Countries form you will see that some main records (Countries) do
not have any subrecords (Cities). Examples are Albania, Cambodia and Yemen.

This search: Country :


City : =

Produces a "No records returned by query" message on the status line. This might
seem to be failing to find records such as Albania and Cambodia. But this is correct.
What you are requesting of Sesame is:

Countries that have a subrecord where the city name is blank

For this search to retrieve any records, you would have to go to one of the cities
Vienna for example and clear the City field and save the record. The search would
then find Austria, because it would have a subrecord (the population is still in place)
with an empty City field. Searching for main records with no subrecords is not simple,
but it can be accomplished with special programmed retrieves. See "Programmed
Retrieves" in the Searching and Sorting section for information on these.

371
13 WORKING WITH SUBFORMS

Importing and exporting

Exporting data
The output file created by an export from a main/subform will depend on which fields
you include or more particularly, where you take these fields from: the main form,
the subform, or both. This is best illustrated by three examples using the Countries
form in the Countries.db sample database. In each example the result set used is the
same: Countries starting with the letter "A".

Here's an example. Look at Figure 9, along with the export file it generates shown to
the right of the figure.

"Afghanistan","Kabul",657.000000
"Albania","Tirane",29.000000
"Algeria","Algiers",2383.000000
"Angola","Luanda",1247.000000
"Argentina","Buenos Aires",2777.000000
"Armenia","Yerevan",
"Australia","Canberra",7687.000000
"Austria","Vienna",84.000000
"Azerbaijan","Baku",

Figure 9. Export Spec. Only main form fields exported.

In this example, fields are selected from the main form only one record per country.

Figure 10 shows another example. "Adelaide",1115900


"Algiers",1650300
"Baku",1214400
"Brisbane",1535300
"Buenos Aires",11624000
"Cairns",0
"Canberra",0
"Cordoba",1434900
"Darwin",0
"Kabul",2080000
"Kandahar",0
"Luanda",2094200
"Melbourne",3317300
Figure 10. Only subform fields exported.
"Perth",1365600
"Rosario",1229800
"Springwood",0
In the example in Figure 10, fields are
"Sydney",3985800
exported only from the subform one "Vienna",1610100
record per city. "Yerevan",1278700

372
13 WORKING WITH SUBFORMS

Figure 11 shows a third example.

"Afghanistan","Kabul",2080000
"Afghanistan","Kandahar",0
"Algeria","Algiers",1650300
"Angola","Luanda",2094200
"Argentina","Buenos Aires",11624000
"Argentina","Cordoba",1434900
"Argentina","Rosario",1229800
"Armenia","Yerevan",1278700
"Australia","Adelaide",1115900
"Australia","Brisbane",1535300
"Australia","Cairns",0
Figure 11. Main form and subform fields "Australia","Canberra",0
exported. "Australia","Darwin",0
"Australia","Melbourne",3317300
In Figure 11, fields are exported from "Australia","Perth",1365600
both the main form and the subform. "Australia","Springwood",0
"Australia","Sydney",3985800
There is one record per city. In other
"Austria","Vienna",1610100
words, the information derived from "Azerbaijan","Baku",1214400
the parent form will repeat for each of
its child records included in the export.

Importing data
When importing an ASCII file into a Sesame main/subform the results will depend on
which fields are included or more particularly, where you take these fields from: the
main form, the subform, or both.

Like export, there is a single import spec for the main form and its subform, listing
fields from both. You can import into the main form, or into the main form and the
subform in the one import. This is a hierarchical import and is simple if the ASCII file
has the correct structure. If you export from a Sesame main/subform as in the third
example above (see Figure 11), then that export file can be imported into Sesame to
give you the correct results.

For importing into a main/subform (such as Countries) the following apply:

 If you import just into the fields of the main form, you get new main form
records and no subrecords.

 If you import just into the fields of the subform, the import will not work. You
cannot import into just the subform. If you import into the subform form itself
(such as Cities) you will make orphan records. You must import into the main
form, and have parent/child information in the import to establish correct
parenting.

373
13 WORKING WITH SUBFORMS

 If you include fields from both the parent form and the subform, you will
create new parent records and associated child records.

The only scenario to be considered here is the third one. The first example is a
straightforward single-form import as covered in the Import, Export and Copy Records
section of this Guide.

A further example
The following example is the same as the third example of importing (above), but with
fewer records.
Here is the file to be imported:

"Afghanistan","Kabul",2080000
"Afghanistan","Kandahar",0
"Algeria","Algiers",1650300
"Argentina","Buenos Aires",11624000
"Argentina","Cordoba",1434900
"Argentina","Rosario",1229800
"Armenia","Yerevan",1278700
"Australia","Adelaide",1115900
"Australia","Brisbane",1535300
"Australia","Canberra",0
"Australia","Melbourne",3317300
"Australia","Perth",1365600
"Australia","Sydney",3985800
"Azerbaijan","Baku",1214400

It has 14 rows: 14 cities, in six different countries. The file has a field from the main
record Country, from the Countries database, and two fields from the subrecord
City and Population, from the Cities database. The import spec is as shown in Figure
12.

Figure 12. Import spec for hierarchical import.

The result is six new countries, each with its cities three for Argentina, for example.

374
13 WORKING WITH SUBFORMS

Sorting of the import ASCII file


The import example above worked perfectly because the Import spec matched the file
to be imported, and also because the import file was correctly sorted. It is essential
that the import file is sorted so that the values for each main form All Argentinas
together, all Australias together, for example are grouped together in the file.

If the rows of the import file were rearranged slightly, as below (the out of sequence
record is shown in boldface):

"Afghanistan","Kabul",2080000
"Afghanistan","Kandahar",0
"Algeria","Algiers",1650300
"Argentina","Buenos Aires",11624000
"Argentina","Rosario",1229800
"Armenia","Yerevan",1278700
"Australia","Adelaide",1115900
"Australia","Brisbane",1535300
"Australia","Canberra",0
"Argentina","Cordoba",1434900
"Australia","Melbourne",3317300
"Australia","Perth",1365600
"Australia","Sydney",3985800
"Azerbaijan","Baku",1214400

You would now get eight new main form records. You would get two Argentina records
one with the cities of Buenos Aires and Rosario, and another with Cordoba. You
would also get two Australia records one with the cities of Adelaide, Brisbane and
Canberra, and another with Melbourne, Perth and Sydney.

375
Section 14
Creating and Using Macros
A macro is a series of menu selections, keystrokes, and/or mouse clicks that have
been recorded, assigned a name, and saved. When the macro name is called, the
macro is "played back" that is, the steps in the macro are executed from beginning
to end just as if you were performing those steps manually.

Macros can be recorded and played back both in Sesame runtime and in Sesame
Designer.

Macros are used to shorten long menu sequences as well as create "miniature
programs" within an application.

Sesame uses a simple event recorder to record and playback macros. Macros are
literally the events being sent to Sesame from the keyboard and mouse, recorded to
your computers memory. On playback, those same events are sent back to Sesame
as though they came from the keyboard and mouse. Sesame runs in a graphical user
interface, rather than a text screen, so elements may be moved, resized, or otherwise
rearranged at a very fine level of detail between the time when the macro was
recorded and when it is played back. To compensate for this, when it can, the Sesame
macro recorder also records the "names" of objects. These serve as further guides to
the playback system as it attempts to send the correct events to the correct
application elements.

Since the macro recorder is a simple event recorder context is very important. For
reliable operation, Sesame must be in the same state when the macro is played back
as when it was recorded. If, for example a macro is recorded from an ordinary form,
but is played back with the Table View on the screen, the Table View will receive all of
the events that were intended to go to the form. For this reason, it is advisable that
macros be used for short generic sequences of events. For more control of complex
events, Sesames programming language offers a wide range of automation
commands, including the ability to launch macros. See the Sesame Programming
Guide for more information.
Q&A
Unlike Q&A, Sesame can playback only the current macro. Multiple
macros are not maintained in a single file. There is no limit as to how
many you can have, but they are loaded individually prior to running
them. Only one macro can be current at any one time. If there is a current
macro already loaded or recorded and you choose to record or load
another macro, the currently loaded macro is replaced. Unless you choose
to save your new macro using the same filename, the original macro file is
left intact and can be reloaded.

377
14 CREATING AND USING MACROS

Alerts appear while recording/playing macros


Sesame allows the Sesame Initialization file ("sesame.ini") to determine if alerts are
interactive during playback or if the macro answers the alert. If an entry in the
sesame.ini file appears:
PAUSE MACRO: ON
Then the macro will pause and get the user's answer should an alert appear. If the
entry is set to "OFF" (the default) then the macro will provide the answer that was
recorded when the macro was recorded for that same alert.

Recording a macro
To begin recording a macro, select Macro/Recording On from Sesames main menu
bar. The record function is available at all times except during macro playback. You do
not need to have an Application open to begin recording. (See Figure 1.)

Figure 1. Turning on the Macro


recorder.

Once Recording On has been selected,


Sesame begins to save all further
mouse and keyboard events. It is very
important to remember to turn this off
when you are done. Macros can grow
to be very large in only a few minutes.

With Sesame recording your macro,


perform the operations that you would
like to be available as a single,
repeatable series of actions. During
recording there are very few changes
in the behavior of Sesame. The one critical exception to this is the appearance of
popup alerts and warnings. Sesame turns off all popup warnings and alerts while a
macro is being recorded or played back.

While recording, the Macro indicator on the main toolbar turns white and displays the
message Recording. The indicator also shows the cumulative number of events
recorded by the macro. (See Figure 2.)

Figure 2. Macro indicator showing status.

378
14 CREATING AND USING MACROS

To turn off recording, select Macro/Recording Off from the main menu bar. This
command is available only while the macro is recording. The Macro indicator displays
"Unnamed." This indicates that you have an unnamed macro currently loaded. (Refer
to later section on saving and naming a macro.)

Playing back a macro


To test your macro, return Sesame to the state it was in when you began recording.
This may mean returning to a specific form, or to the application menu. It may mean
closing any dialog boxes that may have appeared while the macro was recording.
Once Sesame is back to its original state, select Playback from the Macro menu. (See
Figure 1.) Sesame takes over your mouse and keyboard. It will send all of the events
you recorded back to the appropriate elements within Sesame. If you have Macro
Visibility On selected on the View menu (see Figure 3), you should see Sesame
responding to these events.

Figure 3. Turning macro visibility on for replay (default setting).

Many macros will be convenience operations, intended to replace repetitive typing or


mouse movements. To repeat the playback of a macro, select Repeated Playback from
the Macro menu. (See Figure 1.) A dialog box will appear asking for a count of
repetitions. Enter any positive number and click the Accept button. Your macro will be
played back the number of times you specified. (See Figure 4.)

Figure 4. Setting repetitive playback of macros.

Note: Be sure that your macro has been carefully tested before using repeated
playback. Also ensure that it returns to the initial starting condition for the macro.

379
14 CREATING AND USING MACROS

Saving and naming a macro


You can save and load macros to and from files. Macro files are standalone files and
are not contained in any particular Sesame application. To save a recorded macro,
select Macro/Save Macro from the main menu bar. The Sesame file dialog will appear.
(See Figure 5.) The default path is the current working directory. If you want to save
your macro file to another directory, select that directory from the directory tree. You
do not have to add an extension to the filename. The extension ".mac" will
automatically be added, if it is not specified. The Macro indicator shows the name of
the newly saved macro. That macro file can thereafter be loaded by any Sesame client
with access to that directory. Some macros may be useful to many different Sesame
applications. In these cases, the macro file should be saved to a common shared
location.

Figure 5. Saving and naming a recorded macro.

Loading a macro
To load a macro file, select Macro/Load Macro from the main menu bar. Navigate to
the directory where your macros are stored and select the macro file from the list of
macro files. Only macro files and directories will appear on this dialog. The macro will

380
14 CREATING AND USING MACROS

not commence until you select Playback or press F2. The Macro indicator shows the
name of the currently loaded macro.

Load Macro is an available option while a macro is being recorded. This gives you the
ability to "nest" already recorded and saved macros in the middle of the macro you are
currently recording. If a macro has a nested macro recorded within it, the nested
macro will load and play back when the macro that recorded the "load event" is played
back. In this case, and only in this case, playback is automatic after a load.

Macro files
Sesame can playback only the current macro. Only one macro can be current at any
one time. If there is a current macro already loaded or recorded and you choose to
record or load another macro, the currently loaded macro is overwritten. Unless you
choose to save your new macro using the same filename, the original macro file is
unchanged.

Macros vs. programming


Sesames programming language can duplicate many tasks that might otherwise be
performed using macros. (See, for example, ResultSetCurrentPosition,
CreateNewRecord, CloseCommandArea, FormFieldValue, @SelectTreeItem, @Save,
@Exit and the @Load[saved spec] and @Run[saved spec] commands.) Because
programs can generate their own feedback as to the state of Sesame, and change
what they do based on that state, Sesames programming language is the
recommended method to automate complex operations.

Programming does have a limitation in that it cannot run unless contained within a
Layout (a form in a database). This means that you must run a macro if you want to
automate the opening of another form.

The best way to achieve this is to record a macro and save it. Then launch that macro
from a program using the @Macro command. If the macro closes the current form, the
@Macro call must be the last command in the program. For details on @Macro and the
other programming commands referred to above, see the Sesame Programming
Guide.

Human readable macro files


Sesame 2.0 uses human readable ASCII macro files. These can be edited or created
using any ordinary text editor, like Notepad. Sesame 2.0 can also read and use
macros in the binary format created by Sesame 1.x.x . If a macro is read in using the
older format it will be converted into the human readable format when saved.

Each line in the macro file represents a single event in the Sesame user interface. A
typical, though very short macro file would appear as:

381
14 CREATING AND USING MACROS

MACRO HR
PUSH 13 16 16 45
ENTER 10 14 16 45
RELEASE 10 14 16 45
ENTER 21 28 24 57
ENTER 20 1 26 60
PUSH 37 26 43 85
RELEASE 37 26 43 85
MENUBAR SELECT &Open Application...
ENTER 40 56 43 85
LEAVE 117 142 120 171
ENTER 1 104 124 175
PUSH 105 236 228 307
RELEASE 105 236 228 307
TREE SELECTION Countries.db
ENTER 225 278 228 307
KEYDOWN 65505
SHORTCUT 65505
KEYDOWN 65471 SHIFT

The macro listed above clicks on the "File" pulldown menu button, selects the "Open
Application" item from the pulldown and selects the "Countries.db" application from
the subsequent file selection dialog.

To distinguish the human readable macro files from the older binary macro files, the
first event in a human readable macro file must be "MACRO HR".

Series Counter
Pressing CTRL-F2 inserts a counter value into the "keyboard stream" just as though
the user had typed the number. After the number is inserted, the number is
incremented. It is available in both Sesame Runtime and SDesigner. It is used to
"type" a value that changes every time it is used. The settings for this feature appear
on the Macro menu, but its use is not limited to macros. You can use this to number
lines in a Multi-Line Notes field or to sequentially number records during data entry. In
macros, for example, you can use this in SDesigner to quickly create ten elements
numbered Phone1 through Phone10.

The Series Counter value is retained for as long as the Sesame client is open, even if
you switch forms or open a different application. When Sesame is opened, the Series
Counter for that session is set to the default of 1.

To set the starting value, select Macro / Set Series Counter from the main menu. See
Figure 6. Enter the new starting value in the small dialog box that appears. The value
can be inserted in any of four supported formats by selecting the appropriate choice
from the Macro / Set Series Format pulldown menu, as shown in figure 6.

382
14 CREATING AND USING MACROS

Figure 6. Macro Set Series Format options.

Macro Series Format Explanation

Digits as Needed (Default) Inserts as many digits as are needed to fully express
the number.

n Digits Always inserts n digits, where n ranges from 2 to 5.


(n=3 produces: 001, 002, 003, etc.)

n Alphabetic Inserts the number expressed alphabetically, counting


from A to Z for n places.
N can be 1 (A, B, C etc.) or 2 (AA, AB, AC, etc.)

Roman Numerals Inserts the number expressed as a roman numeral (I,


II, III, IV, V, etc.)

Recently-used Macro List


Both Sesame and Designer maintain a list of macros that have been previously loaded
during the current session. These are added to the bottom of the macro menu on
the main toolbar. Loading a macro file puts it on the list, not running it, or recording it.

383
14 CREATING AND USING MACROS

Macros can be run directly from this list. Selecting a macro name from the Macro
menu both loads AND runs the macro as though that macro was loaded and the user
selected Playback (F2).
When you exit Sesame runtime / Sesame Designer the macro list is cleared.

Figure 7. Recently-loaded Macros List.

Macros loaded by calling @Macro or @DeferredMacro are not added to the menu, in
that they might be sensitive to security and should not be seen by the user.

384
Section 15
Designing Reports
Introduction

A report is a way to view data from multiple records in a grouped format that shows
relationships. Reports can provide much more information than just viewing the
individual records that make up a report.

For example, you might want to display a list of customers who still owe you money,
along with the amount each owes. Or you might want to see a list of all your friends
whose birthday falls in the following month, along with the date their birthday falls on.
When you design a report, you need to tell Sesame what information you want to see
and in what order to present it. You can then view the report on-screen and optionally
print it to paper, send it to an associate, or even open it in another application. You
design a report as a part of a specific database.

In Sesame, reports can be created three different ways.

1) You can create and print 'Quick Reports' while you are working with your data in a
Sesame application. Quick Reports are limited to simple columnar reports but have the
ability to sort, break on values, and do summary calculations. They can be used on a
temporary basis only or you can save them for use in later sessions. See details in
Designing and Using Quick Reports on page 386.

2) You can use Sesame's Report Wizard to design permanent reports in the
Sesame's designer mode. For the beginning report designer, the Wizard will walk you
through the steps of creating a new report with point and click simplicity. Answer a
few questions and the Wizard will create your report design. Once the Wizard is
complete, you can modify and enhance the resulting design using any of Sesame
designer's report features. Once saved and reconciled, these reports become a
permanent part of your application and can be run whenever you are using your
database. See details in Using the Report Wizard on page 412.

3) You can use the Sesame designer to manually design and control a report through
all phases of the process. This mode gives the designer 100% control of the design
from start to finish. Once saved and reconciled, these reports become a permanent
part of your application and can be run whenever you are using your database.

With the second and third methods, the reports you create are stored with the
database for which they were designed. This is also an option for the Quick Reports
method. Any time you retrieve a set of records from that database, Sesame will show
you a list of available reports for it whether they were created with Sesame designer
or saved as a quick report. Those reports designed in Sesame's designer module will

385
15 DESIGNING REPORTS

appear on the menu tree while saved Quick Reports will appear in the Spec manager
list of saved specs.

Designing and Using Quick Reports


Sesame's Quick Report feature allows creation of columnar reports in the Sesame
runtime module. Since Quick reports are a type of spec, they can be saved, modified,
and reused. Just like regular Sesame reports, they can create either Print Only or
HTML reports.

Unlike regular Sesame reports they are not created in the report designer. They have
access to a set of commonly used report features that can be manipulated by the user
for creating quick looks at summarized data.

They do not have separate attached sort or retrieve specs as they use the current
result set in the current sort order.

While Quick Reports can be created and saved for both main and sub forms, you
cannot build a hierarchical report/subreport with them. Quick Reports use default
fonts, headers and footers which are automatically selected by Sesame based on the
columns appearing in the Report.

The Quick Report Spec found in the Spec Window quadrant of Sesame in the lower
left-hand corner of the screen.

Figure 1. Quick Report Spec.

Like the other specs, the user is presented with a table list containing all of the
elements available on the form. Clicking on an element name selects it to be included

386
15 DESIGNING REPORTS

in the report. The order the elements appear in the list is the order the columns will be
presented in the final report output. You can change the order of the elements in the
report by dragging them up and down with the mouse or selecting one and moving it
with the Shift-Arrow keys.

The quick report spec window displays five columns:


The first column shows which layout elements have been selected to be included in the
report and displays an "R" for each selected element.

The second column lets you set a report 'break' on the specific element which allows
the report to group data and perform operations based on that grouping. Repeated
clicking to cycle through the break options button presents the choices:
" " (blank) for no break
"B" for break on value change
"A" for an alphabetic break
"Y" for a year break
"M" for month break
"D" for day break (1 day)

The third column allows you to set a summary calculation on the specific element both
on a break (if specified) and as a grand value at the bottom of the report. These
summaries will appear under the appropriate column. The various choices for
summary, selected by clicking or cycling through the calculation button, are:
" " (blank) for no calculation
"S" for sum
"A" for average
"C" for count
"H" for high
"L" for low
"M" for median
"D" for standard deviation
"V" for variance.

The fourth column is the name of the element to be used in the report.

The fifth is where you can type in a number to control the width of the specific column
in pixels. If a width is not specified, Sesame will automatically size the column based
on the data it contains and the available page width. If your columns are too close
together, you can use this feature to increase the space between them.

The report spec shown in Figure 1 above will list Companies, sorted by State and then
Company (records were sorted that way), Last Name, and Currency. It will count
Companies whenever the State breaks and sum the currency values at the same break
point. At the bottom of the report will be a grand count and a grand total. The State
field was made wider to provide more separation between it and Company.

387
15 DESIGNING REPORTS

Figure 2. Quick Report output.

When setting column widths in a print only report, make sure that your report will fit
the width of your page. Specified widths in a print only report may not allow the
columns to all fit on the paper size specified. If only some of the columns are assigned
widths, those that have not been assigned will attempt to adapt their widths to cause
the report width to fit the width of the entire page. If the print only report columns are
too widespread across a page you can also use the column widths to solve this
problem.

Quick report specs can be saved and loaded utilizing the Spec Manager window (Alt-
F8). The Spec Manager window can also be opened directly from the Quick Reports
dropdown menu by
selecting Save or Load.
Note: If you save a Quick
Report, make sure to
create a new designer file
from your active database
the next time you make
design changes to make
sure your designer file
includes your saved Quick
Reports (as is true with all
saved specs).

A Quick Report designed or


loaded in an open form will
Figure 3. Saving a Quick Report. be available until it is
cleared (Clear All), another
saved Quick Report is loaded, or the form is closed. Quick Reports can be edited by
changing the values or positions of any of the columns in the spec. They can also be
'edited' by retrieving a new result set of data.
388
15 DESIGNING REPORTS

Selecting to 'Run' a Quick


Report will give you the
options to create an HTML or
Print Only report, and to
Preview your report or send it
directly to a Printer. Depending
on the selection made, you will
be presented with different
options based on your output
selection.

Figure 4. Quick Report HTML output dialogue.

Saved Quick Report specs can be run in programming using the command
RunQuickReportSpec(). If you do this make sure to have loaded and run the correct
retrieve and sort specs for your records.

Figure 5. Quick Report HTML output dialogue

389
15 DESIGNING REPORTS

Full-Feature Reports

This section will deal strictly with reports you create with Sesame's designer module
without the use of the report wizard.

Sesame has three basic types of reports:

Columnar Field data from multiple records presented in separate columns where
each line represents a single record. The data from the individual fields in each record
are aligned in columns. The rows can include calculations based on summaries or sub-
summaries of data in the records.

Freeform Field data from multiple records presented in a paragraph style where each
paragraph represents a single record. Freeform reports allow you to place elements
just about anywhere on the page. In a freeform report the data displayed in each
element is placed sequentially, one after the other, instead of in columns. Sesame
Report Writer uses elements like static text, static pictures, line breaks, horizontal
lines, and spacers to allow you to structure your reports almost any way you want
them to appear.

Freeform/Columnar Field data from multiple records presented in groups of both


columns and paragraph format.

Keyword Reports - Field data from multiple records presented in separate columns
where each line represents a single record sorted and broken by the values of data
stored in keyword fields. See the section on Breaks below.

Any report is based on, and generated from, data retrieved from a database prior to
running the report (the result set) or from data retrieved by the report itself due to an
attached retrieve specification.

Sesames Report Writer can be found in the Designer module as a selection on


Designers Menu Tree.

The process of designing a report encompasses the following elements:

1. Opening the relevant application in Sesame Designer.


2. Selecting the database the report will encompass.
3. Defining the type of report you want Freeform or Table (columnar).
4. Specifying the elements to include in the report.
5. Attaching retrieve and sort criteria to the report.
6. Reconciling the new report design to your application.

Your reports are created and previewed in Designer as part of the application.dsr file
using DSR data rather than actual application data. All modifications (redesigns) to

390
15 DESIGNING REPORTS

reports are done in the Designer module. After you are satisfied with your report
design, you reconcile the design back to the actual application in order to make the
report a permanent part of your application.

Once a report has been designed and reconciled to a Sesame application, you will
have control over:

Which records are used and the order in which they are included in the report.
Whether to print to a printer or preview the report on-screen.
Whether to use the report output in other applications.

Begin your report design by selecting Add New DatabaseName Report from the
designer Reports menu.

Figure 6. Starting a New Report Design

A dialog will open asking you to name your report. Type a name and click on OK.

Figure 7. Type a name for your new report.

Designer's report layout screen will then be opened. The report writer is divided into
separate sections in which you will create the different parts of your report including
your data, the headers for the data columns, summary calculations such as sub-totals
and totals, averages, counts, etc. See Figure 8.

391
15 DESIGNING REPORTS

Figure 8. Report design layout screen.

Report writer's default is set for use as a columnar report designer. It will produce
reports structured like the one shown in Figure 9 on page 393.

The report interface


The Report Writer interface uses a "building block" approach. You place elements
representing text and data into the applicable report section (row) in the order you
want them to appear on the final report. You set properties, such as font and color, on
these elements using the same interface as Sesames Form Designer. You can specify
that report data be arranged as a columnar report or in a freeform format. Report
elements can be set to display a field value and/or programmed (derived) value using
the full Sesame programming language command set.

The Report Writer main working screen is initially displayed as nine separate sections,
each represented by a column. Each of these sections can be opened or closed by
clicking on the panel to the left of the label. Clicking on will close a section, while
clicking on will open a section.

The orientation of the design layout is horizontal so that the elements of the report
design appear in the same order as they will in the final report output. i.e. the headers
are above the data and the footers appear below the data. The report and view
headers are above the group, or column, headers and the view and report footers
appear below the group, or column, footers.
392
15 DESIGNING REPORTS

Figure 9. Typical columnar report with Totals and SubTotals

The individual sections are:

1. Report Header This section determines what will appear at the very top of the
Report.
2. Page Header This section determines what will appear at the top of each page.
This section will normally start in a closed mode. HTML does not respect the
concept of individual "pages," so elements placed in this section may not behave
predictably.
3. View Header This section determines what will appear above the data in each
separate view in the report. (See report views later in this section).
4. Group Header This section determines the headers that will appear above the
data displayed in the group body.

393
15 DESIGNING REPORTS

5. Group Body The section where the elements that repeat for each record in your
result set, are laid out in the order they will appear in the final report.
6. Group Footer This section determines what will appear below the data displayed
in the group body, including subtotals, counts, and the like.
7. View Footer This section determines what will appear below the data in each
separate view in the report body (See report views later in this section).
8. Page Footer This section determines what will appear at the bottom of each
page. This column will normally start in a closed mode. HTML does not respect the
concept of "pages," so elements placed in this section may not behave predictably.
9. Report Footer This section determines what will appear at the very bottom of
the report.

On the left of the Report Writer screen is the Control Panel section containing the
following tools:

Commands panel Houses the commands to Switch to Design Menu, Close


Design Tab, Save Layout Design, Toggle Display Mode, Attach Specs, Relink
Report, and Export Report to XML.
Layout Element Adder Where you select the elements you want to have in
the various portions on the report layout. Here you can add:
 Value Box: Displays data values from the records or derived calculations.
 Static Text: Label or text that will stay constant throughout the report.
 Static Picture: An image that will stay constant throughout the report.
 Newline: A line break in the report output.
 Spacer: A space in the report output.
 Line: A horizontal line spanning the width of the section or column.
 Page Break: A page break in the report output. HTML does not respect the
concept of "pages," so this element may not behave predictably.
 Summary Calculations: sum, count, average, high, low, median, standard
deviation, variance calculation on a break in the data.
 Subreport: Advanced reporting capability to create a report based on
subrecords linked to your database.
 Special Value Box: E-Mail and URL Links
Property Editor The command panel that allows you to change the settings
(look and feel) of any element in the report design.
Property Viewer The command panel that displays the current settings of
any element in the report design.
Advanced Element Selector: Allows you to easily select and work with multiple
sections of your report design. See Advanced Element Selector, page 131.

394
15 DESIGNING REPORTS

Message Log The panel that displays any applicable messages to you as you
perform actions during the design process.

Figure 10. Basic, empty starting Report Writer design screen.

Below the Control Panels are the program tabs that allow navigation between all
currently open design tabs. They display the names of any reports or forms open for
design or redesign.

Figure 11. Tabs describing different open tasks with the name of the report being designed or
redesigned.

You have the ability to work on more than one report at a time. The tab interface will
allow you to track where you are, and enable you to easily move from task to task.
Certain tasks, such as setting Application Options, require that other design tabs are
closed first.

395
15 DESIGNING REPORTS

Columnar reports

When you start a new report, there is an empty row for each section of the Report.
Sections can be opened and closed using the button to the left of each section.

For most cases, the Page Header and


Page Footer sections will be closed since
your browser will usually control these
settings. Where appropriate, the section
title has a tooltip with its properties.
Tooltips are displayed whenever your
mouse is positioned over the item. In
Figure 12, you can see that this View is
of type Table (columnar as opposed to
freeform).

Basic design
There are a series of steps required to
layout a basic columnar (Table type)
report.

Make the Group Body section active Figure 12. Tooltip on View Header Row
as indicated by background color and
highlighting by clicking in the row. This is the basic area of a report where you will
place your data. When elements are added to a report they are placed in the active
section.

Most basic columnar reports will have at least three sections:

 Group Body where the layout elements will be listed in the order you want
them to appear on the report.

 Group Header where you will specify the headings for each of your columns
of data. The header titles are placed in the same order as their corresponding
layout elements in the Group Body. This is also where you specify whether you
want borders around your report data by clicking on the section label, and
selecting the size of the border. A size of "0" sets no borders.

 Group Footer where you will place the summary calculations for the data in
your columns. The calculation elements are placed in the same order as their
corresponding layout elements in the Group Body.
In columnar reports, the three sections listed above work together to ensure that the
column headers, data, and footers line up with each other. If either Group Headers or
Footers are used, make sure that you place the same number of elements in the
Group Header and/or Group Footer sections as appear in the Group Body section.

396
15 DESIGNING REPORTS

Adding layout elements to the report


This section will be based on using the Customer.dsr file that is provided as one of the
sample applications on the Sesame CD.

This sample report will use the Company, Firstname, Lastname, Position, and Currency
fields and will be called Customer Amount Owed.

1. Select the Group Body section. (Click in the row with your mouse.)
2. From the Layout Element Adder control panel, in the Select Element Type,
choose Value Box.
3. In the Bind Element To, select Company. (A list of all the fields in your
database will be presented here.)
4. Click on Add Element To Report. You do not have to give it a name. Report
Writer will assign it a sequential layout element number.

Figure 13. Adding a layout element "Company" as a value to the group body.

A new report element will appear in the Group Body section. If you have made an
error, any element can be removed from the report layout by selecting it and pressing
your Delete key.
397
15 DESIGNING REPORTS

You can see all the properties of each report element in the Property Viewer. Each
element shows either two or three pieces of information about itself.

Type of Information in the element This is also partially indicated by the


elements color. There are four "families" of element:

 Static (Gold): Static Text or Static Picture.

 Value Box (Blue): Value (data from your records or the result of a
calculation).

 Page Layout (Gray): Page layout elements. Choices are: Space,


Newline, Page Break, and Line. Page Break element in Table
(columnar) reports Adding a Page Break element from the Layout
Element Adder into a Group Header or Footer will cause the report
output to start on a new page whenever that particular group breaks.
(e.g. You have a report of Companies in different States, sorted by
State and then Company. You make a Group Header that breaks by
state and insert a page break element in the corresponding Group
Footer. When you print the report, every time the state changes,
Sesame will start printing on a new page.)

 Summary Calculation (Purple): Sum, Average, Count, Variance,


Standard Deviation, High, Low, Median.

Element Name The name by which the element can be referred to in


programming. It is enclosed in square braces (for example, [LE0].) Or you can
assign a name when you add the element.

Description Shows information appropriate to the type of element.

Static Text Shows text.

Static Picture Shows filename of image to display.

Value Box Shows database field name or "Unbound."

Summary Calculation Shows element name to summarize.

Repeat steps 1 through 4 above until you have added the layout elements for
Firstname, Lastname, Position, and Currency to the Group Body section. (See Figure
14.)

398
15 DESIGNING REPORTS

Figure 14. All of the elements added to the group body section.

Continue with the report design by following these steps:


1. Select the Group Header section by clicking in that column.
2. From the Select Element Type dropdown, choose Static Text.
3. Type Company in the Name box and click on Add Element To Report. A new
element is added to the Group Header section with the name Company.
4. Repeat steps 1 through 3 until you have added the layout elements for First
Name, Last Name, Position, and Amount to the Group Header section. You only
have to change what is typed in the Name box and click on Add Element To
Report to complete this step.

Figure 15. Complete column titles using the Group Header Section

399
15 DESIGNING REPORTS

5. Select the Group Footer section by clicking in that column.


6. From the Select Element Type dropdown list, choose Spacer.
7. Click on Add Element To Report four times to add four spacer blocks to this
section. This will space the next added element to line up in the report with the
fifth element in the Group Body section (Currency).

Figure 16. Spacing the footer for Summary Calculation to line up with the Amount data.

8. With the Group Footer section still selected, from the Select Element Type
dropdown list, choose Summary Calculation / Sum.
9. From the Bind Element To dropdown list, select LE4. (It will be the only selection
available because there is only one element that can be summed.) LE4 is the
Report Writer assigned name for the Currency layout element. (See Figure 17.)

Figure 17. Summary Calculation in Group Footer.

10. In the Commands Control Panel click on Save Layout Design.


Your report is now complete, and when run will appear as shown in Figure 18.

Note: Any element can be removed from the report layout by selecting it and
pressing the Delete key.

400
15 DESIGNING REPORTS

Figure 18. Completed columnar (table) report.

Element Selection
Multiple elements can be selected by:
1. Holding the shift key and clicking on multiple elements
2. Selecting one element and using Shift-Arrows to select adjacent elements, even in
different rows such as headers, body, and footers all at the same time.
3. Using the Advanced Element Selector to select multiple elements based on similar
criteria. See section on Advanced Element Selector Control Panel.

Element Movement
Any single selected element it can be moved by holding down the mouse button and
dragging it to a new position, even into different groups. It may also be moved, even
between groups, by holding the Ctrl key and using the applicable arrow keys.

Multiple selected elements can be moved, even between groups, by holding the Ctrl
key and using the applicable arrow keys.

Changing properties
To make your design more complete, you will want to change some of the settings
that are the result of a simple basic design. You can change the fonts, add a report
header and footer, and so forth. You do these tasks using additional sections and the
Property Editor and Property Viewer.

To add a report header, you use the Report Header section. In a report with only one
view, the View Header and the Report Header sections are essentially interchangeable.
Click on the Report Header section to select it.

401
15 DESIGNING REPORTS

Add a static text element with whatever title you want to appear on your report.

Figure 19. Adding a report header.

Property Editor / Property Viewer


You can use the Property Editor and the Property Viewer to make changes to the
elements you have placed in the columns of your report design. Property changes
made are applied to all selected elements. You select and deselect elements by
clicking on them with the mouse or using the Advanced Element Selector. Shift-
clicking on multiple elements selects them all. Selected elements are indicated by
highlighting of their descriptive text. The selected element also has black bands
around it and its text is white.

Figure 20. View header. Setting Headers to BOLD using Property Editor and Property Viewer.

402
15 DESIGNING REPORTS

As with Sesames Form Designer, the active element drives the Property Viewer. The
active element is also the one that can be moved, relative to other elements in the
section, using the keyboard or mouse.

As in Figure 20 above, setting the report column headings to be bold is just one
example of what you can do to enhance your reports. Details of all the options and
capabilities of the Property Editor are covered in the section of this Sesame User Guide
on the Designer module.

With some other changes made in Property Editor, such as setting the Group Headers
and Summary Calculations to bold, your final report can look like the one shown in
Figure 21 below.

Figure 21. Enhancements made to basic report design.

Preview mode
If there is data in your designer file, you can preview your report design with one click
on the Preview Report choice in the Commands section of the report designer. Sesame
will select approximately 50 records to use as a preview.

The F5/F6 Keys


As in Sesames Form Designer module, you can use the special keystrokes F5 and F6,
or the right-click menu, to assist you in working with the Property Editor. In the
example above, when you are renaming your report, placing your cursor in the Name
box and pressing F5 will fill the box with the current value stored in the design.
Pressing F6 will open an expanded window enabling you to easily edit the values. F5
and F6 can be used in any Property Editor box that requires typing.
403
15 DESIGNING REPORTS

Fonts/Colors
You can use the Property Editor to change the fonts and colors of the printed output as
well as the display format of the data to be included in the output (Number, Money,
Date formats). Exact procedures for using these features of the Property Editor are
covered in Property Editor in the Designing a Sesame Application section of this guide.

Additional Design Features

Ignore Blank Values


When using Summary Calculations such as
count, average, median, standard
deviation, and variance you can exclude
records that have no values in the column
you are summarizing by setting Ignore
Blank Values to Yes on the Other tab of the
Property Editor for that calculation.

Breaks
If you set a group in a Table report to
Break on Keyword element, Sesame
produces a Keyword report. Sorting and
breaking the records by the values in that Figure 22. Ignore Blank Values in
Summary calculations
keyword field.

Page Headers and Footers


Sesame reports respect page breaks when sent to either the printer or your browser in
preview mode. The page Headers and footers will be placed at the top of each page
when printed. By default the
page header and footer rows
are collapsed. To use them,
click on the arrow to the left of
them to make them ready for
input.

Multiple breaks on single


group
You can create multiple breaks
in a single group by right-
clicking the header and using
the arrows in the top section of
the Report Section Properties
dialogue to cycle through and
set different elements for break
(See Figure 23).
Figure 23. Setting a second (multiple) break in a

404
15 DESIGNING REPORTS

No Repeat option
Using the multiple breaks feature, you can break on an element and click on the "No
repeat" box to tell Sesame to only print the break value for the first record in the
group.

Month and Year Breaks


If you select a date value on which to break, setting the Break Value in the Report
Section Properties dialogue to "M" will break your records by month, setting it to "Y"
will break them by year.

Scrolling
Report Designer scrolls on drag. If you are dragging an element past the end of the
visible screen, the screen will scroll with you to allow you to complete your
movements.

Printing Options
When your report designs are completed and are put into use in the Runtime module
of Sesame, you will have the multiple options when you select a report to print.

HTML Preview Prints the report to your browser for your follow up actions. It
also writes an HTM file copy of the report to disk.

HTML Immediate Prints the basic HTM report to the printer with no preview
in the browser. It also writes an HTM file copy of the report to disk.

Print Only Preview - Prints to the printer with no HTM disk file. This option
gives you a series of printer options to choose from and also opens a window to
preview what the report will look like before printing.

Print Only Same as Print Only Preview without the preview window. After
setting the printer options the report is sent to the printer.

Freeform Reports

A freeform report includes layout elements that are placed on the final report in a
structured, continuous mode rather than in aligned columns. In a freeform report you
can have elements like static text, static pictures, line breaks, horizontal lines, and
spacers. You can structure your report to print in almost any structure you desire.

Basic Design
The steps required to layout a freeform report include:

405
15 DESIGNING REPORTS

1. Clicking on the View Header


section label to bring up the
Section property editor, selecting
Freeform and clicking OK.

2. Making the Group Body section


active, as indicated by background
color and highlighting, by clicking
in the section. This is the area of
the report where you will place
your layout elements. When
elements are added to a report
they are placed in the active
section. Figure 24. Setting the report type to
Freeform.

Most freeform reports will have at least two or maybe three sections:

Group Body where the layout elements will be listed in the order you want
them to appear on the report.
Group Header where you will specify a heading for the data to be printed in
your report.
View Header or Report Header where you can place a title to appear at the
top of your report.

Add layout elements to the report


The examples presented in this section are based on the freeform report named
Schedule Report 2 which you can find in the Schedules.db sample application on the
Sesame CD.

This example will use the SalesPerson, CallDate, Call Time, Company, Appointment
With, and Comments fields in the report design.

1. Select the Group Body section. (Click in the section with your mouse.)
2. From the Layout Element Adder control panel, in the Select Element Type,
choose Static Text.
3. In the Name box type Sales Person:
4. Click on Add Element To Report.
5. In the Select Element Type dropdown list, choose Value Box.
6. In the Bind Element To dropdown, select SalesPerson from the fields list.

406
15 DESIGNING REPORTS

7. Click on Add Element To Report. You do not have to give it a name. Report
Writer will assign it a sequential layout element number.
8. In the Select Element Type dropdown list, choose Newline.
9. Click on Add Element To Report.

Note: Any element can be removed from the report layout by selecting it and
pressing the Delete key.

Figure 25. Working with report sections to create a freeform report. Each element will appear
directly after (next to) the one above it in the section. Line Break elements move the data to the
next line.

You have just created a basic freeform line that will appear in the final output like this:

Sales Person: [persons name from a database record] followed by a


carriage return before the next line.

This is the structure behind freeform reports. Layout elements placed in the Group
Body section are strung together, one after the other. You utilize the available static
elements and page layout elements to separate them and make them readable as
output.

As you can see in the table below and in the sample report in the Schedule.db
application, this structure is repeated using sets of static text, followed by a value box,
and then a newline until the report design is completed and all of the elements
required in it are included (CallDate, Call Time, Company, Appointment With, and
Comments).

All the entries for the Scheduling Report are shown below. Layout Elements are shown
in italics. Data Values are Underlined.

407
15 DESIGNING REPORTS

View Header
Static Text - Your Appontment
Group Header
Static Text - Below is Your Schedule
Group Body
Static Text - Sales Person, Value - SalesPerson, Line Break, Static Text Date:, Value
- Call Date, Line Break, Static Text -Time:, Value - Call Time, Line Break, Static Text -
Company:, Value - Company, Line Break, Static Text - With:, Value - Appointment
With, Line Break, Static Text - Notes:, Value - Comments

In addition, static text elements are added to both the Group Header and View Header
to place title lines in the report. The Property Editor was used to enhance the header
and static text fonts. The result is a final design that creates the report shown below.

Figure 26. Completed freeform report in Schedule.db.

408
15 DESIGNING REPORTS

Combination Freeform/Columnar reports

You can combine both types of reports (freeform and columnar) in one design. Report
writer allows you to have multiple views of your data in the same report. You can
change the type of report format, from view to view, so that you can create a list
(table) in a columnar format for easy reading and review, with a set of full page-width
notes (freeform) appearing below the list.

Basic design
The examples presented in this section are based on the freeform report, Combination
Schedule that youll find in the Schedules.db sample application provided on the
Sesame CD.

This example will use the SalesPerson, CallDate, Call Time, Company, Appointment
With, and Comments fields in the database.

Creating a combination report requires the creation of multiple views in a single report
design. The steps to accomplish this are as follows:

1. Design the first view (Columnar or Freeform) as covered in the previous sections,
and add all of the layout elements needed. If you need to modify this view, you
can come back to it at a later time.
2. Open the Report Section Properties editor for the View Header by clicking the
section label and select Add New View After This View (or Before as needed) from
the View Management dropdown. (See Figure 27.) Click on the Perform Selected
Action button and then OK. A new view, with a complete set of sections, is added
to the report layout. The columns for this view appear after the View Footer
section for your initial view.

Figure 27. Adding a new view to a report design.


409
15 DESIGNING REPORTS

3. In the second Views set of columns, click on the View Header title and set the
View Type for this view to be different from the first view (in this example,
Freeform). (See Figure 28.)

Figure 28. Setting second view in report to Freeform type.

Adding layout elements to the report


Use the procedures listed in both the earlier sections to add the required table and
freeform elements to the applicable views.

In the columnar (table) view, you will use SalesPerson, CallDate, Call Time, Company,
and Appointment With fields. Also, add a Line element to the first report View Footer.

In the second view the freeform view you will use Static Text elements and the
Value Box elements Company and Comments. Note that Report Writer allows the use
of multiple layout elements bound to the same field, in this case, Company.

410
15 DESIGNING REPORTS

Figure 29. Layout elements for the freeform second view.

The final output of this design is shown in Figure 30 below.

Figure 30. Combination columnar/freeform report output.

411
15 DESIGNING REPORTS

Report Creation Wizard

Sesame's Report Creation Wizard creates columnar reports in the Sesame design
module by prompting you for your report requirements. When the Wizard is complete,
you wind up with a final report or one that you can go on to modify further. The
Wizard is accessed by selecting Reports ! Design/Redesign a Report ! Database Name !
Report Creation Wizard from SDesigner Design Menu. You will be presented with a
series of dialogue screens that, when answered, will build your report in the database.

The opening screen will request a name for your report. Fill it in and click Next.

Figure 31. Report Creation Wizard opening screen

The next screen will show a list of all of the fields in your database and allow you to
select the ones you want in the report. The available list appears on the left and the
selected list on the right. You can select fields one at a time by clicking on an field
name and then on the right pointing arrow in the middle of the screen. You can also
select multiple contiguous fields from the list by clicking on the first one and, while
holding down the shift key, clicking on the last one you wish to select. You can select
non-contiguous fields from the list by clicking on the first one and, while holding down
the control key, clicking on the other(s) you wish to select.

You can either select the fields in the order you wish them to appear in your report or
you can use your mouse to change their order, once selected, by clicking and dragging
them to different positions in the right-hand window.

412
15 DESIGNING REPORTS

If you want to remove a field from the selected list of columns, click on it in the right
column and then click on the left pointing arrow in the middle of the screen. You can
use the shift or control key to select multiple fields with the mouse.

Figure 32. Selecting your Data columns in the Wizard

When you are ready, click Next.

The third Wizard screen gives you the ability to select what fields you want to sort
your report by and whether you want to group them by creating a 'break' in these
values. When you break an element, you can also perform calculations like totals and
subtotals on that break. The Wizard will allow a sort on any value in the database it
does not even need to be included in the data shown in the report.

When you click in a sort dialogue (First, Second, Etc), a list of the fields will be
presented. After selecting an field from the list, you will be given a chance to select
the order of the sort by clicking on Descending or leaving it blank (Ascending). You will
also be able to select whether you want to break on the selected element by clicking in
the Break box.

If you select Break, you will also be able to select the characters on which you want
the break to occur. Leaving this block blank will cause a break to happen on a change
in the first character of the element's value. If you select a Date field to break on, you

413
15 DESIGNING REPORTS

will be allowed to break by day, month, or year. If you select a Number or Money field,
you will be allowed to select the amount to determine the break.

Once you complete your selections, another dropdown will appear to allow you to do
the same things for another field.

Figure 33. Adding Sorts and Breaks in the Wizard

When you have completed selecting all of the fields you wish to Sort by and Break on,
click on the Next button.

If you have selected to break on an field that can be totaled, the Wizard will next
present you with the Totals and Subtotals screen that will display each of these fields
in a separate row. Selecting Subtotal will create that total each time the field selected
for breaks change their values. Selecting Total will create a grand total at the end of
the report.

When finished click the Next button. See

The Wizard will then either allow you to generate the report by clicking on a Generate
button or allow you to go back and review the choices you have made.

414
15 DESIGNING REPORTS

Figure 34. Totals and Subtotals stage.

If you are finished and generate the report, the Wizard will ask if you wish to create
another report. If you answer yes, you will give the report a name and repeat the
process above for the new report. If you answer no, the Wizard closes and your report
will be opened in SDesigner.

The Wizard lays out the report with the correct amount of Group Header/Footer sets to
accommodate your selected breaks and totals as well as spacers to ensure correct
placements of your totals and subtotals.

At this point you have the full capability of SDesigner to make any additional changes
you require in the report such as:

Adding other summary calculations counts, averages, highs, lows, etc.


Adding additional columns, including derived columns
Changing formats - fonts, column widths, etc.
Adding additional views to the report
Adding subreports
Attaching a Retrieve Spec
Adding Static Text
Adding Page Breaks
Etc.

415
15 DESIGNING REPORTS

Figure 35. Result of Report Wizard.

At this point, you can also Preview your report design from the Commands Control
Panel.

Attaching retrieve and sort specs


The usual steps involved in running a report in Sesame are:

1. Retrieve the records you want included in your report.


2. Sort the records.
3. Run the report.

The report will present the records you retrieved (the result set) in the order you
sorted them.

Report Writer allows you to attach previously saved sort or retrieve specifications to
your report design. Any spec that has been saved in the database can be used in
Report Writer.

Attached specifications take precedence over any retrieve or sort you used to get your
current result set. If there are both retrieve and sort specs saved with your report, any

416
15 DESIGNING REPORTS

result set (retrieved records) you obtain in Sesame will be ignored by the report when
run. If only a retrieve spec is attached, the report will override only the current
retrieve, If only a sort spec is attached, the report will override only the current sort.

It is recommended that you attach sort specifications to the report design, but that
you leave the retrieve specification out. This way, your result set of records will be the
ones included in the report in the attached sort spec order and it will be easy to
run the same report against any result set.

Note: Attaching a saved spec makes a copy of that spec in your report. Later
changes made to the original saved spec will not affect the report design.

Follow these steps to attach a sort or retrieve spec to your report design:
1. Select Attach Specs from the Commands Control Panel.
2. Using the Attached Specs Editor that opens, select:
The type of spec to apply.
Whether to keep the current spec or attach a new one.
The specification name from the list of those saved in the database.
3. Click on Attach.

Figure 36. Attaching a previously saved Sort specification to the report. This will override any
sort performed in Sesame.
417
15 DESIGNING REPORTS

Saving a report
When you have completed your report design, you must save it before you can
preview or use your design in a Sesame application. When you have saved your work,
you will see a message to that effect in the Commands / Message Log.

The process of saving a report is to click, in the Commands control panel, on Save
Layout Design. The screen will flash momentarily, or present a progress bar, and the
"Layout Saved" message will appear in the message log panel.

While working on complex report designs, it is a good idea to save your work
regularly.

Previewing a report
When you are finished with your design or at any intermediary stage if you want to
see how it is going Report Writer will allow you to save your work and preview the
report. The preview will only include records that were in the DSR file when it was
opened, or have been added to the DSR in Preview Mode. You can preview the report
by opening your entire design in preview mode or get a quick look by clicking on
Preview Report in the Commands section of the control panel. Sesame will select
approximately 50 records to use as a
preview.

To use the full Preview Mode first click


Save Layout Design in the Control Panel
Command menu. Then select Application
Utilities / Preview Application from the
menu tree. It is a good idea to preview
with one of the methods as you move
through your design efforts to check your
progress and save your design in stages.
Figure 37. Quick Preview Mode in the
reports designer control panel. Preview mode opens the Designer file
(.DSR), in a separate window. When in
preview mode, you will see a different window with "Preview Mode" in the window title
bar and an Exit Preview button. While this window is open, the designer window is
disabled. The preview mode is for testing only. Preview does most of what you can do
in Sesame. You can browse; you can add and delete records; almost all programming
will work; you can mass update, import, export, run reports, and so forth.

Preview mode operations are exactly the same as they are in any Sesame application.
For information on specific functions / operations, see the applicable section of the
Sesame User Guide.

In order to preview your report, you first need to retrieve a set of records (result set)
against which you want your report to run.

418
15 DESIGNING REPORTS

On the Preview menu, open the applicable database in Search /Update mode.

1. Retrieve the
records you wish
to include in your
report.
2. Double click on
Reports/Name of
Database until
the vertical scroll
bar expands.

3. Use the scroll


bars to move
down and across
to see your list of
reports.
4. Select the report
you want to print
and then select
the method from
the Print Reports
dialog that opens
(see Figure 39
Figure 38. Opening Reports list after retrieving data in preview.
below).
Note that the vertical scroll bar indicates more below. Scroll
down to see list.

You can choose:

HTML Preview Preview the report in your browser, save a copy to disk,
and let you print from the browser.
HTML Immediate Saves a copy of the report to disk and opens the Windows
printer dialog without displaying in your browser.
Print Only Preview Previews the report in a separate window but does not
save a copy to disk or open in the browser.
Print Only Opens the Windows printer dialog, does not save to disk
or preview the report.

5. Click on Generate to complete the operation.

419
15 DESIGNING REPORTS

When you are finished


working in Preview
mode, close the
application, click on the
Exit Preview button and
you will be back in
Designer.

Any data you have


added to the database
in the DSR file while in
Preview mode is saved
with the DSR file.

Figure 39. Opening Reports list with horizontal and vertical scroll bars.

Reconciling a report
Your report has been created, or redesigned, in Designer and, once saved, is part of
the DSR file. When you have finished your design and have previewed it to make sure
that it is what you want, you must Reconcile your design back to the active
Application. Until then, it will not be available to you in your actual Sesame
application.

For steps and information about reconciliation of DSR files to DB files, see the section
on Reconciling Designer Changes in the Designing a Sesame Application section of the
Sesame User Guide.

Running a report from the Application Menu


To run a report in your Application, once it has been reconciled, follow the same steps
in Sesame as those listed above in the section Previewing a Report:

1. Open the application and database in Search/Update mode.


2. Retrieve/Sort the records to include in your report.
3. Pick the report off the menu and print or preview it.

Advanced Report Features

Toggle the display


Figure 40 and Figure 41 show the ways Report Writer elements are displayed. The
Commands Control Panel contains an option Toggle Display Mode. This command
switches between the two display modes Layout view as shown in Figure 40 and
Format view as shown in Figure 41.

420
15 DESIGNING REPORTS

Figure 40. Layout view of a report design.

Figure 41. Format view of a report design.

Layout view is the normal working mode during design. Format view shows the
elements with sample data. In Format view, the sample data is displayed with the
correct setting for color, font, alignment, format, and so forth, applied. In Figure 41,
you can see that all the elements in the Group Header are in boldface text. The date
and time formats are also displayed. In this view, selection is indicated by the
background color, so that the correct font color settings can be displayed. Each
element has colored bars indicating its type, for reference (Static Gold, Value Blue,
Page layout element Gray, Summary Purple).

Summary totals and breaks


Summary calculations can be added to a report in the Group, View or Report Footers.
Those that appear in the View or Report footers appear as a Grand Total at the end of
the view or report. Summary calculations that are added in the Group Footers appear
as a subtotals wherever the data in the Group Body breaks on a predetermined value.

Sesame reports can have as many breaks as are required for your sub calculations.

421
15 DESIGNING REPORTS

Break elements are set in the Group Headers. The break element is set by clicking on
the Group Header title. This will open the Report Section Properties dialog.

Figure 42. Report Section Properties dialog.

Set the Break Element to the layout element that controls the subtotals (State, in this
example), and set the Break Value to control the actual break. The tooltip that opens
over the Break Value number will give you details on the Break Value setting.

Figure 43. Using Break Value.

In this case, the Break Element is set to State. The Break Value is 0. This will cause a
group break each time the State changes, and will generate sub totals, sub averages,
or sub counts, as the case may be.
422
15 DESIGNING REPORTS

If you need to create a group break based on the value in more than one element, you
can add an additional Group Header/Footer and repeat the above steps. You can add
as many groups as you need to your reports. To add a new set of header/footer, click
on an existing Group Header to open the Report Section Properties Window. In the
Group Management section drop down the action window and select where you want
the new group added.

Note: Keep in mind that adding a group refers to placement of the Group Header
so, placing a new group after the current group will place any sub calculation
(which takes place in the footer) in that group prior to current calculations and
adding it before will place its calculation after the current calculation.

Click on Perform Selected Action and close the window with the OK button.

Figure 44. Adding new group (Header and Footer) in a report

Derived columns
You create a derived column to produce information derived from existing data in your
database. For example, you can create a derived column in your report that shows a
persons full name and position on two lines even though there is no element that
contains this complete information. You can calculate a derived column from other
elements that exist in the report layout or even from the results of other derived
columns in the same report.
A layout element that is used as part of the derived column calculation must be part of
the report. It can be made Not Visible, using the Property Editor so that it doesnt
show, but it must be in the report layout.

Derived columns are created using Sesames Program Editor. To make a derived
column, you create a Value Box layout element that is unbound (not linked to any

423
15 DESIGNING REPORTS

field). The unbound element displays data created On Print, when the report is run. In
this example using Customers.dsr, the unbound Value Box involved is called
Combination (typed in the Name box when added to the report) in the Group Body.
The elements LE1, LE2, LE3, and LE4, in the Group Body, are set to Not Visible.

Figure 45. Report Design with Unbound Layout Element [Combination] for programming as a
derived column.

Open the Program Editor by selecting Program Layout in the Commands Control Panel,
and program the On Print event for the unbound element (LE4) as shown below. (See
Figure 46.)

Combination = LE1 + " " + LE2 + " " + LE3 + @Newline() + LE4

Figure 46. Creating the data for derived column LE4 using Program Editor.

424
15 DESIGNING REPORTS

Close the Program Editor, save your layout design. By adding a new group for creating
a break between names (as explained above), you will have a simple derived column
report that looks like the one below.

Figure 47. Report with only the derived column printing.

HTML output files


Every report you "run" using HTML Preview or HTML Immediate output, creates the
output you request. It also creates an HTML output file in the current working
directory. This file will have a filename structured along the following lines:

Schedule_Report_2_2003_11_02_20_47_29.htm

The structure breaks down as follows:

Report Name + Report Date (YYYY_MM_DD) + Report Time (HH_MM_SS).htm


These files can be opened and worked with in any program that can read HTML
format. They can be made into web pages, used in your word processor, emailed, or
imported into your spreadsheets.

425
15 DESIGNING REPORTS

The report files will remain in the default report folder until they are moved or deleted,
using your operating system file manager.

Note: If you do not want your report files to be created in the current
working directory, you can change their location using the
SESAME_REPORT_PATH environment variable. (See Appendix 2 Sesame
Environment Variables.)

426
Section 16
Using the Application Utilities
The Application Utilities Menu
Sesames Application Utilities menu (see Figure 1) gives you access to application-wide
tasks that you may need to perform routinely or occasionally, depending what you
want to accomplish. These tasks include:

 Making a backup copy of an entire application.


 Designing a new application.
 Redesigning the currently open application.
 Merging an application with another application.
 Removing a database from an application.
 Exporting your Application to XML

Figure 1. The Application Utilities menu tree.

Backup Application
A Sesame application is comprised of a pair of files, one with a .db extension, and one
with a .dat extension. To create a successful backup of your application design, along
with all of its data, you must make a backup copy of both of these files.

427
16 USING THE APPLICATION UTILITIES

Internal Sesame backup


Sesame provides an internal backup feature that enables you to backup an application
to any valid drive on your system. On the Application menu tree under the Application
Utilities section, you will find a selection named Backup Application. When selected,
Sesame will prompt you for a filename for the backup copy of the application. Provide
a path or filename that is different from the active application, and click Accept.
Sesame will make copies of both the .db and .dat files in one operation.

External backup
Any system-wide backup routine performed by a proprietary backup program, such as
a daily backup to a tape drive or other device or simply copying the two application
files to another location, such as a writable CD will make a successful backup of
your application.

As with any backup or file copy, ensure that the application is not in use before
attempting to back it up.

You should periodically validate a recent backup by restoring it (if necessary) to a


location that does not overwrite the original in-use application, then opening it to
verify that it is, indeed, a valid backup. A backup wont serve its purpose if it is not a
true copy of the application as of the date and time it was made, or if it cannot be
restored to full use.

Design New Application


The Design New Application selection on the Application Utilities menu is simply
another way to start the Sesame Designer module. All the steps involved in creating a
new application are performed in Designer. (See the Designing a Sesame Application
section in this guide.)

Redesign Current Application


The Redesign Current Application selection starts Sesame Designer for the currently
open application. It prompts you to select an existing Designer (.dsr) file, or supply a
new .dsr file on which to perform your design/redesign work. (See the Designing a
Sesame Application section in this guide.)

Merge Application
A Sesame application can contain multiple databases. These databases do not all have
to be designed and added to the application in a single session. In other words, they
do not have to be part of the initial application.

You can start with a simple one-database application, and work with it for a while,
adding records to it and so forth. Later, you can design a second application with its
own database or databases, and add new records to it, too. When you are happy with
both applications, you can combine them into a single application using the Merge
Application feature. Later on, if you want, you can add yet another application to the
428
16 USING THE APPLICATION UTILITIES

one that is now the result of having merged the first two. You can even merge an
application with multiple databases into another application. All of its databases will be
merged with the current or target application.

Merging two applications where the databases in each application are related in
some way gives you certain advantages over using those databases as separate
applications. For example, you can place a subform on a form if the database for the
subform is in the same application as the form. (See the section Working with
Subforms in the Sesame User Guide.) In addition, external lookups between databases
in the same application are faster and more efficient than between databases in
separate applications. (See the XLookup family of commands in the Sesame
Programming Guide.)

Note: In the two applications to be merged, there cannot be two databases,


forms or reports of the same name. If you merge a new application into an
existing one where this condition exists, Sesame will append "000" to the
object with the matching name that is being merged.

Always backup your applications before performing a merge operation!

The process for merging two applications is straightforward:

1. Open the first application.


2. Select Application Utilities / Merge Application.
3. When the Select Application dialog displays, click on the filename of the second
application to be merged with the currently opened one.
4. Click on Accept.

Sesame merges the second application into the currently opened application. All
databases, forms, reports, and data are added to the first application. No data is
merged or mixed between the databases of the first and second application. That is,
each database involved in the merge retains its own pre-merge design and data. The
new combined application is now a single application with multiple databases.

When merging applications, the existing security on the target application (the open
application) will prevail, but security for merged applications should always be
reviewed.

Trim Application
Sesames Trim Application feature is the opposite or reverse of the Merge Application
feature. It allows you to remove or delete one or more databases from a current
application that contains multiple databases.

429
16 USING THE APPLICATION UTILITIES

Trimming a database from an application is the same as deleting that database and all
of the forms, reports, specs, and data attached to it. Trimming is an irrevocable
operation so, again:

Always backup your application before performing a trim operation on it!

Follow these steps to Trim an application:

1. Open the application you want to trim.


2. Select Application Utilities / Trim Application.
3. Using the Trim Application dialog (see Figure 2), select the name of the
database you want to permanently delete from the current application.
4. Click on Delete, then confirm that you are sure you want to delete the selected
database along with all its data.

Figure 2. Trim Application dialog: selecting a database to delete.

Your selected database will be permanently removed from the current application. All
of the data related to that database is deleted. Data, forms, reports and the like
attached to any remaining databases in the application are left intact.

Note that you can also remove a complete database in Field Manager in Designer.
Deleting a database by using Trim Application in Sesame runtime does not affect any
Designer (DSR) file. Deleting a database in Field Manager in Designer does not affect a
DB file unless you reconcile or Save As a new application.

Export Application to XML


Exports the entire application to an XML file. This is a human readable ASCII file in the
standard XML format. It can be edited using any ASCII text editor or a special XML
editor. Once an XML file is made, it can be turned back into a Sesame application
using the XML Database command found on the File pulldown menu.

Note: Exporting an entire application to XML can produce a very large file depending
on the size of the application files.
430
16 USING THE APPLICATION UTILITIES

Copying
Facilities for copying all or portions of a Sesame application are not found on one
specific menu. They are in different areas of the program depending on what you
might need to copy.

Copying an application
You can copy an entire application in several ways:

1. Externally Copy the two files that comprise the Sesame application,
application_name.db and application_name.dat, to new filenames or a new
location:

The new application will contain all the databases, forms, elements,
reports and data of the original application.
All internal elements databases, forms, layout elements, reports, and so
forth will have the same names as the application that was copied.

2. In Sesame Open the Application:

From the menu bars File Menu, select Save As and provide a new name
for the copy of the application. Sesame will copy both the .db and .dat files
to the new name. Alternatively, from Sesames menu tree, select
Application Utilities - Backup Application and provide a new application
filename. Sesame will copy both the .db and .dat files to the new name.
The new application will contain all the databases, forms,
elements, reports and data of the original application
All internal elements databases, forms, layout elements,
reports, and the like will have the same names as the application
you copied.

3. In Sesame Designer Open the application for Redesign. (Assign a filename


with a .dsr extension or use an existing .dsr file.)

From Designers Application menu, select Delete All Data Records and then
select Save As New Application. Provide a new application filename.
Sesame will copy the relevant files to the new name.
The new application will contain all the databases, forms,
elements, and reports, but none of the data of the original
application.
All internal elements databases, forms, layout elements,
reports, etc. will have the same names as the application you
copied.

431
16 USING THE APPLICATION UTILITIES

Copying a Designer file

1. In Sesame Designer Open the Designer (DSR) file.


2. Preview the Application
3. In Preview mode, select Save As
4. Type a name for the new Designer file. It will be a copy of the DSR
5. Close Preview mode.

Copying a Database
You cannot directly copy a database within an application in Sesame. You can however
copy a database from another Sesame application. See Merge Application.

Copying forms and reports


This is done using Sesame's Layout Manager. See Managing a Database on
page 161.

432
Section 17
Securing Your Applications
You do not have to apply security to a Sesame application it is an option. A new
application has no security unless and until you choose to apply it.

Security in Sesame applications is based on Users (and their passwords) and on


Groups to which users are assigned.

When an application has security, all databases within the application have the same
users and groups.

Sesame security controls four types of rights:

Rights to the data.


Rights to the design.
Rights to the server.
Rights to the Sesame menus and dialogs.

There are four attributes that define a user and that user's rights, as shown in Table 1.

Attribute Allowed values Comments

User Name One or more characters. Not case sensitive.

Password One or more characters. Case sensitive.

User Level Administrator, Manager, User Levels determine how much access
or Data Entry. the user has to the data and Sesame
menus and dialogs. For example, not all
menu choices are available to all levels.

Group One or more application Each user must be assigned to a group.


specific groups. Groups define access to data at the level
of elements, forms and reports. Groups
also control access to Sesame Designer.
Table 1. Attributes of a user.

Server administration rights are controlled by a Login name and password that are
completely separate from the users and attributes described above.

Q&A
Q&A compatibility With Q&A, security must be defined for each Q&A
database. With Sesame, security is defined for an application, including all
databases, forms and reports within that application.

433
17 SECURING YOUR APPLICATIONS

Sesame's three levels are simpler than Q&A's "Access Rights," which specify seven
rights that can be independently granted to each user. The Q&A rights are:
password, design and program change, mass delete, individual record delete,
mass update, design reports/forms, enter/edit data.

Sesame's groups are similar to what Q&A Windows calls a "Group" and what Q&A
for DOS calls "Field Security Specs."

In Q&A security, you can control a number of different tasks such as assign
passwords, design and program, mass delete, etc. at the individual user level.
Q&A also has a quite separate "Database Lock." Neither of these is directly
comparable to Sesame's method of granting design rights by group, but similar
functionality is offered by use of the following:

Q&A translation notes A user's level in Sesame is determined from Q&A's


seven rights as follows:

Sesame Administrator: An administrator in Q&A is translated to an administrator


in Sesame. (Q&A administrators are those who have password rights.)
Sesame Manager: A Q&A user with any of these rights becomes a Manager in
Sesame Change Design and Program, Mass Update, or Mass Delete.
Sesame Data Entry user: All other users become Data Entry users in Sesame.

Q&A's Groups (also called Field Security Specs) are translated into Sesame
groups. Users are automatically assigned to the proper groups. Note that
groups are not required by Q&A but they are required in Sesame. Therefore, if
a Q&A database does not have groups, during translation the Sesame group
QA Group will be created and all users will be assigned to it.

Warning: As with any database manager, Sesame security can be made


complex. It is possible to inadvertently lock yourself out of your application
and be unable to make any changes to it. Sesame security needs to be applied
in a careful, considered way. You should make backup copies of your
application before making changes to security, and test your redesigned
application carefully before using it and before discarding your backup copies.

User levels
As the name implies, it is users that have levels, not groups. User levels restrict the
tasks that users can undertake in Sesame run-time. (Sesame run-time is the normal
Sesame database program specifically not Sesame Designer.)

Each user is assigned one of three levels. These levels are: Administrator, Manager,
Data Entry.

434
17 SECURING YOUR APPLICATIONS

An Administrator can perform all functions in Sesame run-time. Additionally,


an administrator (and only an administrator) can access Designer from the
run-time, provided that he/she belongs to a group with Designer rights. (See
below.)
A Manager can perform most functions in the run-time.
A Data Entry user can only perform a limited set of functions in the run-time.

Access to different functions within the run-time is mostly controlled by these factors:

By whether the Application Utilities menu is available.


By which choices are available on the Results Commands.
By the Spec Manager and the Spec Selector.

Note: Groups, not user levels, determine which data a user can see or modify
and whether a user has the right to use Designer.

Application Utilities User level


details

Application Utilities (on the Application


Menu) is available only to administrators.
This gives an administrator the following
capabilities (see Figure 1), denied to all
others:

 Backup Application

 Design New Application (Open


Designer)

 Redesign Current Application


(Open Designer)

 Merge Application

 Trim Application

 Export Application to XML


Figure 1. Application Utilities menu seen by
Administrators only.

Results Commands
After creating a result set, access to Results Commands is as shown in Table 2.

435
17 SECURING YOUR APPLICATIONS

Commands Administrator Manager Data Entry


Copy Y Y Y
Mass Delete Y Y N
Mass Update Y Y *
Print Forms Y Y Y
Print Forms to Default Y Y Y
Export Data Y Y Y
Import Data Y Y Y
Remove Duplicates from Results Y Y Y
Delete Duplicates Y Y Y
Sort by Timestamp Y Y Y
Table 2. How User Level affects Results Commands menu.

*A default mass update can be defined for a form by an administrator


or manager (see below). If one has been defined, then data entry
users can select Mass Update from the Results Commands menu to
run it. That is the only mass update a data entry user can run. If there
is not a default mass update, the Mass Update choice still appears on
the menu tree, but will only run a null mass update a mass update
that does nothing. Whether or not there is a default mass update, the
mass update option is disabled in the Spec Manager.

The Spec Manager


After creating a result set, access to the Spec Manager is as shown in Table3.

Type of spec Administrator Manager Data Entry

Copy Y Y Y

Export Y Y Y

Import Y Y Y

Mass Update Y Y N

Sort Y Y Y
Table 3. How User Level affects Spec Manager access.

For each spec type, access to operations is as shown in Table 4.

436
17 SECURING YOUR APPLICATIONS

Operation Administrator Manager Data Entry

Load Y Y Y

Save Y Y N

Rename Y Y N

Delete Y Y N

Defaults Y Y N
Table 4. How User Level affects Spec Manager operations.

To summarize:
Administrators and managers have full access to all specs and all operations
on them.
Data entry users have no access at all to mass updates.
Data entry users can load specs (other than mass updates) but have no access
to any operations on them except Load.

Deleting records
Data entry users cannot use Mass Delete found on the Results menu, but they can
delete individual records in both form view and in table view.

The Security Manager


The Security Manager is used to define users and groups and to specify what each
user and group is permitted to do.

The Security Manager is part of Sesame Designer. Start Designer as you do to make
any design changes to an application. Once in Designer, select Application from the
menu tree and, under that, Security Manager. The Security Manager dialog will
appear. It has four tabs along the bottom. These tabs allow you to define groups,
users, element level security, and application settings.

For an unprotected application, the Security Manager will show that there are no
groups, no users, and that "Everyone" is permitted to redesign.

Note: Only administrators can access Designer directly from the run-time by
selecting Redesign Current Application from the Application Utilities menu.
Managers and Data Entry users who are given rights to make design changes will
have to run Designer directly because they have no Application Utilities menu.

Note: The right to use Designer for any particular application is controlled by
group membership, not user level. That is, an administrator does not get access to
Designer simply by being an administrator. Even though he can run Designer from
437
17 SECURING YOUR APPLICATIONS

the run-time menu, he must also be in a group with designer rights to be allowed
to log in to it. It is possible to allow managers and even data entry users to have
design rights while denying them to administrators it all depends on which
group each individual user is a member of.

As with other design changes, you will need to select either Reconcile Existing
Application or Save As New Application to have your Designer changes take effect.

Groups tab Defining groups


Groups control two types of rights:
Permission to use Designer.
Access to data at the level of forms, reports or individual elements.

Click the Groups tab to create, rename, or delete groups.

Figure 2. Security Manager Groups tab with two new groups.

To create a new group, type the name in the Group Name edit box at the top and click
the Add New Group button. After the group has been created, you can add users to it
by clicking on the Users tab. (See Figure 2.)

438
17 SECURING YOUR APPLICATIONS

To change the name of an existing group, edit the existing name to make the desired
change.

To delete a group, check the box marked Delete This Group. Note that you cannot
delete a group if it has any users in it the Delete This Group option will be grayed
out.

Each group has a box that displays users in that group.

Each group also has a pick-list labeled Set All Users To Level. The pick-list's default is
Keep Current Level. Click the down arrow and use the mouse to highlight
Administrator, Manager, or Data Entry if you wish to change all users in the group to
that particular level. This is a convenient way to change all users currently in the
group to that level, but it does not ensure that all users of this group will remain at
that particular level. In other words, users can subsequently be changed to other
levels, and users added to the group in the future may be assigned to other levels.

After making any changes, click Apply Changes. You can cancel your changes by
clicking Close without applying the changes; Designer will ask you to confirm that you
wish to close without making the changes.

Users tab Define users


Click this tab to create new users, to change user attributes, and to remove users.

Each user has four attributes:

User Name
Password
User Level
Group

To create a new user, type the name in the User Name edit box and type the
password into both the Password and Confirm Password boxes. You can also select the
User Level and the Group if the defaults displayed are incorrect for the new user. (See
Figure 3.)

439
17 SECURING YOUR APPLICATIONS

Figure 3. Security Manager Users tab with several users.

Note that user names are not case sensitive, but passwords are.

When you enter a password, it will not be visible. Names and passwords can be as
short or as long as you wish, but each user must have both a name and a password.
When everything is filled in for the new user, click Add New User.

To change an attribute of an existing user, merely make the desired change or


changes) for that user.
440
17 SECURING YOUR APPLICATIONS

Caution: If you move yourself from a group with Designer rights, make sure
that at least one user remains assigned to a Group with those rights. If not,
youll lock yourself out of the database design. See section below, Deployment
and Preventing Design Changes, for details on how to do this intentionally and
how to avoid doing it accidentally.

To delete a user, check the box marked Delete This User.

Note that a user's level can also be changed by the Set All Users To Level control on
the Groups tab.

After making any changes, click Apply Changes and Close. You can cancel your
changes by clicking Close without applying the changes; Designer will ask you to
confirm that you wish to close without making the changes.

Layout and Layout Element settings tab Define element level access

Figure 4. Security Manager Layout and Layout Element Settings tab. The Key layout element
on the Main Form is read-only for users in the Restricted Group.

Click this tab to specify security for layouts and elements.

441
17 SECURING YOUR APPLICATIONS

A layout is a form or a report. You can control access to individual elements, and also
to the layout (the form or report) itself.

A layout element often referred to as just an "element" is defined as anything on


a form or report. The most prominent of these is the Text Box element that can
display data stored in fields in the underlying database, but it also includes unbound
elements with calculated values, and also static text, boxes, lines, and so forth.
Remove all the layout elements and you will have a blank form or report.

Use the Select A Layout and Select An Element controls to select sensitive elements
that you wish to restrict access to. If no restrictions are specified for an element, then
all users in all groups have full access to that element. To restrict access to an
element, for each group that has been defined, select any of the following rights:
Allow Read, Allow Write, and Allow Execute. (See Figure 4.)

These can be selected in any combination. You can also select none of the rights or all
of the rights. The combinations of Read and Write are shown in Table 5.

Read Write Effect

N N,Y Element is not visible and so cannot be edited. In the case of


a form or report, it does not appear on the list of forms or
reports.

Y N Element is visible but cannot be edited. Label and text colors


are dimmed.

Y Y Element is visible and can be edited. Appearance is normal.


Table 5. Element-level permissions.

Allow Execute allows programming (including mass updates) to change the element
value. If this right is not granted to a user, when he causes programming to be
executed that would set the value of the element (for example On Form Exit) the
value is simply not changed. It is not considered an error if this happens.

To clear all security for a layout, select the layout in the Select A Layout dropdown list
box, then click Remove All Security For Layout. You will be asked to confirm that you
want to do this.

To clear all security for an element, select the layout in the Select A Layout dropdown
list box, and the element in the Select An Element drop down list box, then click
Remove All Security For Element. You will be asked to confirm that you want to do
this.

After making any changes, click Apply Changes and Close. You can cancel your

442
17 SECURING YOUR APPLICATIONS

changes by clicking Close without applying the changes; Designer will ask you to
confirm that you wish to close without making the changes.

You can alter settings for all layout elements even static text, lines and boxes.

Application Settings tab Define application-wide rights


You can remove all security from an application by clicking on Remove All Application
Security.

Performing "X"-family programming operations (such as @XLookup) to a database in


another application requires a user name and password if the target application has
security. To assign a user name and password for these operations, enter the
information into the X User Name, X Password, and Confirm Password fields. This is
the User Name and Password that will be passed to the external application or
database. For the "X" operation to succeed, this User Name and Password must have
permission in the external application or database to access the requested
information. (See Figure 5.)

Figure 5. Security Manager Application Settings tab. Only members of the Design group can
open Designer. An XLookup password for this application has been set using the User Name
"Customers_DB."

443
17 SECURING YOUR APPLICATIONS

The group that a user belongs to determines whether that user can make design
changes to the Sesame application. In the box labeled Which Groups are allowed to
redesign the application? you will see a list of the groups in this application (defined
using the Groups tab). Check one or more groups which are to be allowed to redesign
the application. (See Figure 5.)

If Allow Everyone was previously selected, selecting an actual group will uncheck it
automatically.

There are two ways to allow all users in all groups to make design changes.

1. Check Allow Everyone (which appears in the list of groups as if it were the first
group). If you do this, the other groups will be automatically unchecked.
2. Uncheck all groups one by one. If you do this, Allow Everyone will be automatically
checked for you.

Caution: If you leave all boxes unchecked, the Allow Everyone box is
automatically checked when you click on Apply Changes or switch to another
tab. You now have an application that everyone can redesign.

Caution: Make sure that you are in one of the groups that has Design rights
unless you intend to create a lock-out situation. See section below,
Deployment and Preventing Design Changes, for details on how to do this
intentionally and how to avoid doing it accidentally.

Once you have completed all the tabs, you will see that you can get an overview of the
security at the Groups tab. (See Figure 6.)

After making any changes, click Apply Changes and Close. You can cancel your
changes by clicking Close without applying the changes; Designer will ask you to
confirm that you wish to close without making the changes.

444
17 SECURING YOUR APPLICATIONS

Figure 6. Security Manager Groups tab showing users in each group.

Using a protected application


When you open a protected application in Sesame you are presented with a password
dialog box. (See Figure 7.)

445
17 SECURING YOUR APPLICATIONS

Figure 7. Login dialog box. User name is not case sensitive.

Type your user name and password. The user name is not case sensitive, but the
password is. Then click on Accept and you can use all the databases and forms and
reports in the application, subject to the permissions granted to you.

Password Controls
In a Sesame application that has had security applied to its design a failure alert
("Your User Name or Password was not accepted") will display when an invalid
password/user name is entered. Clicking OK in the message will return you to the
password dialogue box for another attempt at correctly logging in.

You can also use the Sesame.ini file to add entries that will increase the strength of
Sesame passwords. You can set minimum lengths required for passwords with the
entry "PASSWORD MINIMUM LENGTH: <n>" and you can require that passwords
contain at least one non-alpha character with the ini file entry "PASSWORD MUST
CONTAIN NONALPHA: <ON|OFF>". Ini file settings only apply to new passwords added
to an application and will not affect existing passwords in an application.

Deployment and preventing design changes


A developer can deploy a database that cannot be redesigned by creating a group and
assigning design rights to that group alone. If no users are added to this new group,
when the change is reconciled to the existing application or a new application is
created, it will be impossible for anyone to make changes. As long as the developer
maintains a copy of the database (or design file) which permits him access to
Designer, he can always make any changes as required and reconcile them to the
existing database.

A lock-out situation can also be created by mistake. To avoid this, never exit from the
Security Manager in a way that (1) there is only one group that can open Designer and
(2) there are no users in that group.

As a precaution, before exiting from the Security Manager, an administrator should


always double-check that his own user name is still in a group that can open Designer.
446
17 SECURING YOUR APPLICATIONS

It is wise to make a backup of your application beforehand.

Here are two ways to accidentally create a locked design:

1. Have two or more groups, only one of which is permitted to open Designer.

At the Users tab in Security Manager, move all the users from the group which can
open Designer to any of the others that can't.

2. Have two or more groups, only one of which is permitted to open Designer. One of
the other groups has no users, perhaps because it was just created.

At the Application Settings tab in Security Manager, in the Which groups are
allowed to open Designer area, uncheck the group that can open Designer and
instead check the empty group.

Always make a backup copy of your application before undertaking


security changes.

Server administration
Server administration is not, generally, application-specific. It is used to unlock
applications and see server messages. It can be run from Sesame run-time, or from
Designer. It can be opened without an application being open. If a protected
application is open, there are some application-specific functions available. See below
for details.

To start Server administration, select Server Administration from the run-time File
menu. You will be asked for a user name (Login:) and password. Note that this
password dialog is not the same as the regular security password.

The name is "admin" and the default password is "hello". Both are case sensitive
even the user name "admin" (unlike at the regular security password dialog).

Once in, you can change the server admin password by selecting the Administrative
Password tab. You cannot change the server admin login name from "admin", nor add
another server administrator login name.

The Server Administration dialog will vary depending upon whether it is called when a
protected application is currently open or not. When called with a secured application
open, there is an additional tab on the dialog titled User Management. (See Figure 8.)

447
17 SECURING YOUR APPLICATIONS

Figure 8. The User Management tab in Server Administration.

This screen presents an alternative user interface to security for the current
application. Here you can:

Add a new user


Rename a user (change login name)
Delete a user
Change a user's level
Change a user's group

The interface here is a subset of the full security features in Designer. You cannot
change passwords, create groups or change layout permissions here.

It is important to note that here you are making changes to the security for this
application stored in the runtime (.DB) file. Changes made in Designer are stored in
the Designer (.DSR) file. If you make design changes to your DSR file and then
reconcile, you will lose all changes made to security in Server Administration / User
Management.

If you wish to retain security changes made in Server Administration / User


Management, you must select Redesign Current Application from Sesame run-time.

448
17 SECURING YOUR APPLICATIONS

You can choose to create a new Designer (.DSR) file or to re-use an existing one. If
you re-use an existing DSR file, you will overwrite that designer file with a copy of the
DB file complete with data and security.

The security settings in Server Administration are useful for making temporary
changes to security on a running application. For example, if you have an application
in current use by twenty users, you dont want to shut it down to allow a new
employee to start working. You can use Server Administration to quickly grant
permissions in the application.

Summary

 Every User has to be in a Group.


 Users have User Levels.
 User Levels can restrict tasks in Sesame.
 Groups do two things:
o Allow or prevent using Designer.
o Control Form- and element-level security.

 To use Designer at all, for any particular application, a user must be in a


Group permitted to do so.
 All users in such a group can use Designer, regardless of User Level.
 A user in a group permitted to Design can do everything in Designer, including
changing security.
 It is possible to lock all users out of redesigning.
 There is another security dialog where users can be added, etc., in Sesame
runtime: Server Administration / User Management.
 You do not have to use element-level security: it is optional.

Temporarily Disable Security


When working in an application with security, you are prompted for a login each time
you enter Preview Mode so you can Preview your application as different security
settings would cause it to behave. If you want to disable the login prompt for the
current Designer session, you can do so by clicking the Temporarily Disable Security
button on the Application tab of the Security Manager. Click the button again to re-
enable security.

Security is disabled only for the current Designer session. The next time you open
your Application, security will behave normally. This setting does not affect Runtime,
even if you Reconcile with security temporarily disabled. There is no need to re-enable
security before closing the Application.
449
17 SECURING YOUR APPLICATIONS

Security frequently-asked questions

Q. How can I easily apply a password to my application?


The minimum steps to require a password to use your application are as follows:

1. For safety, first make a backup of your application.


2. Open your application in Designer, using or creating a Designer (DSR) file.
3. Select Application / Security Manager.
4. Create a Group for example: SECURE.
5. Create a User for example: Boss. User Boss should be an administrator.
6. Close Security Manager.
7. Reconcile or save as new application. (All users must be out of the application
to reconcile).
8. Everyone logs in as Boss.

Q. How can I easily stop users from modifying my application?


The minimum steps required to protect your application design are as follows:

1. For safety, first make a backup of your application.


2. Open your application in Designer, using or creating a Designer (DSR) file.
3. Select Application / Security Manager.
4. Create a Group for example: OWNER.
5. Create a User for example: Boss. User Boss should be an administrator.
6. Create another Group for example: USERS.
7. Create a User for example: User.
User User can be an administrator or a manager.
8. In Security Manager, make the group OWNER the only group that can design.
9. Close Security Manager.
10. Reconcile or save as new application. (All users must be out of the application
to reconcile.)
11. Users log in as User.

Q. How do I change my password?


If you are not a member of a group with permission to open Designer, you can't.
Assuming you are, you can do the following:

1. For safety, first make a backup of your application.


2. Open your application in Designer, using or creating a Designer (DSR) file.
3. Select Application / Security Manager.
4. Click on the Users tab.
5. Delete your password and type the new one in the Password box.
6. Do the same in the Confirm Password box.
7. Click on Apply Changes.
8. Close Security Manager.
9. Reconcile or save as new application. (All users must be out of the application
to reconcile).
450
Section 18
Web Capabilities
Web Server

Sesame has a built in web server. By starting Sesame using the -web_server startup
switch, you can cause Sesame to act as a simple web server capable of delivering
web pages and data content from your applications without requiring any
programming.

Example:
sesame -server <machine_name> -web_server 80
<machine_name> is the name of the computer

All web servers, including Sesame's, operate on the same basic principle. A web client,
such as a browser, connects to the web server and makes a request using a URL
(universal resource locator). Typically, a URL is seen in a web browser as something
like: http://www.ExampleSite.com/ExamplePage.html. The named web server receives
that request and sends the browser HTML, usually from the HTML file requested in the
URL.

The Sesame web server capabilities can be used to:


Serve web pages
Retrieve and display information from your Sesame applications
Add records to your databases
Update existing records

Sesame Web Server Mini-Tutorial


The following tutorial creates a small web site which lives on your computer and is
server by the Sesame web server. You do not need Internet access. The site makes
use of the sample Customers database that comes with Sesame. The example web
pages shown below can and should be used as a starting point for your own Sesame-
enabled pages.

Preparing Your Computer


Make sure your machine is not already running any web servers by starting a web
browser and typing http://localhost in for the URL. If no web page is shown or the
browser indicates that it cannot connect, or connects you to a default Internet search
page, then you are not running a web server. If it shows you a local web page, or
gives you a permission error, then you probably are running a web server on port 80,
and you will need to shut it down or run Sesame's web server on a different port.

451
18 WEB CAPABILITIES

About the Example Website


Our website is designed to provide a web page interface to the Customers application.
It consists of four main pages, plus some supporting pages. The four main pages are:
A Menu page providing links to the other three main pages
A Search Listings page to search for Customer records matching our criteria
An Update Listing page to update existing Customer records
A New Listing page for adding new records to the database

The supporting pages are used by the main pages above to perform the required task.

For the sake of simplicity and minimal typing for you, the example pages do not make
use of colors, fonts, images, CSS. You can use all of these things in your own web
pages.

Note: When creating the web pages, make sure to use a text editor such as
Notepad or vi. Do not use a word processor as this may add extraneous tags and
information that will prevent your pages from displaying correctly.

Create a Directory
In the current working directory for Sesame, create a new directory called Site. All the
files for your site will go in this directory. Copy Customers.db and Customers.dat from
the Samples directory into your new Site directory. Rename the new files to
CustomersWeb.db and CustomersWeb.dat

Start the Sesame Web Server


Start Sesame Server using the following command line. Remember to substitute
"MyServer" with the name of your machine:

sesame -server MyServer -web_server 80

If you needed to change the port number from 80 because you are running another
web server, substitute the 80 above with a different number. Try to choose a number
above 4096.

You should now see the Sesame server dialog. The Sesame Server is now able to
operate normally for Sesame Clients and will also respond to web page requests.

Start a Sesame Client and Load the Application


For security purposes, the Sesame web server will not load an application that is not
already open. To get Customers data onto our web pages, we need to give the web
server permission to use that data by attaching a Client and loading the Customers
application.

Start a Sesame Client using the following command line. Remember to substitute
"MyServer" with the name of your server machine:

452
18 WEB CAPABILITIES

sesame -client MyServer

Open the copy of CustomersWeb.db in your Site directory. Once CustomersWeb is


open, you can minimize (not Close) your Sesame Client.

Create the Menu Page


The index page is the page that loads by default when you browse to a particular
directory. For Sesame Web Server, the index page is called index.html. Our index
page is the Menu page that provides links the various site functions. It is just a static
page and does not talk to a database.

To create this page, open your text editor and type or paste the following to create a
web page with three links:

<html>
<head>
</head>
<body>
<P><A HREF="find.html">Search For Customer Listings</A></P>
<P><A HREF="update.html">Update Your Listing</A></P>
<P><A HREF="new.html">Submit A New Listing</A></P>
</body>
</html>

Save the file in your Site directory as index.html.

To see this page, start your web browser and set the URL to
http://localhost/Site/index.html or http://MyServer/Site/index.html (again, substitute
your machine name for "MyServer"). If you are running on a port other than 80, for
example 4099, type: http://localhost:4099.

You should now see a web page in your browser that looks like Figure 1.

If your machine was exposed to the internet without any intervening firewalls, anyone
could set their browser to look at the web page you are now serving. To serve a web
page other than index.html, give the file a filename ending in .html or .htm and place
it in the current working directory or in any directory below the current working
directory. When you specify the URL, include the path to that file. If the new file is
named MyNewPage.html and is in the MyDir directory, specify the URL as
http://MyServer/MyDir/MyNewPage.html.

453
18 WEB CAPABILITIES

Figure 1. Menu page served by Sesame Web Server - index.html

Note: You must specify index.html in the URL. Only the top level directory will
load the index page by default.

Now, we can build the three pages to which this Menu page links and make them talk
to the CustomersWeb application.

Searching a Database
The first page we will build is the one to Search For Customer Listings. There are a
number of fields in the database, but we will limit our users to searching by Company,
State and ZIP.

The Menu page links to a page called find.html, so that is what we need to call this
page.

Open your text editor and type or paste the following to create a web page with a form
with the fields needed to search the CustomersWeb database. This page also contains
some special tags needed to talk to Sesame, which will be explained below.

Save the file in your Site directory as find.html.

454
18 WEB CAPABILITIES

<html>
<head>
</head>
<body>
<form name="kmp" method="post" action="result.html">
<input TYPE="hidden" NAME="command" VALUE="search">
<input TYPE="hidden" NAME="file" VALUE="Site\CustomersWeb.db">
<input TYPE="hidden" NAME="database" VALUE="Customers">
<input TYPE="hidden" NAME="searchfields" VALUE="Company;State;ZIP">
<input TYPE="hidden" NAME="sortfields" VALUE="Company">
<P>Please enter your search criteria and click Find Matches.</P>
<TABLE>
<TR>
<TD>Company</TD><TD><input type="text" size="20" name="Company"></TD>
</TR>
<TR>
<TD>State</TD><TD><input type="text" size="20" name="State"></TD>
</TR>
<TR>
<TD>ZIP</TD><TD><input type="text" size="20" name="ZIP"></TD>
</TR>
<TR>
<TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR>
<TD><input TYPE="SUBMIT" NAME="b1" VALUE="Find
Matches"></TD><TD>&nbsp;</TD>
</TR>
</TABLE>
</form>
</body>
</html>

Now, if you click the Search For Customer Listings link on your Menu page, your new
page should appear as shown in Figure 2.

The three fields in this form are search fields taking the same search syntax as
Sesame. Once we build the final piece of this section, you will be able to enter search
criteria into these fields in Sesame syntax, click the Find Matches button and display
information from the records in the CustomersWeb database that match your criteria.

The secret to doing this is in the line that starts with <form name and the five lines
that start with <input TYPE="hidden".

These six lines tell Sesame what to do with the criteria typed into this form and what
information you want from the CustomersWeb database.

455
18 WEB CAPABILITIES

Figure 2. Search form - find.html

Looking at these six lines individually, you can see how this works:

<form name="kmp" method="post" action="result.html">

This line tells the web server that this is a form and the when the form is submitted
the web server should send the data on this form to the web page result.html, which
we will be building next. This line is standard HTML and a line very much like it
appears in any web form.

<input TYPE="hidden" NAME="command" VALUE="search">

This line tells the web browser to place a hidden field on the form and to give it the
value of "search". When the form is submitted to a web server all of the fields are sent
over, including hidden fields. When the Sesame web server receives a field named
"command" that contains a value of "search", it knows to use some of the other fields
and their names to search the Sesame application.

<input TYPE="hidden" NAME="file" VALUE="Site\CustomersWeb.db">

456
18 WEB CAPABILITIES

This line tells Sesame which application file to use for the search. The application must
already be loaded on the server.

<input TYPE="hidden" NAME="database" VALUE="Customers">

This line tells Sesame which database inside the application file named above to use
for the search.

<input TYPE="hidden" NAME="searchfields" VALUE="Company;State;ZIP">

This line tells Sesame to search the named fields Company, State and ZIP using the
criteria entered on the HTML form. This is a semicolon separated list of named fields.
This line must appear in the HTML before the HTML fields it names. The HTML field
names must match the names of the database fields to be searched.

Your HTML form can include other fields, but only those listed in searchfields will be
used for the search.

<input TYPE="hidden" NAME="sortfields" VALUE="Company">

This line tells Sesame to sort (ascending only) using the named fields. Again, this line
must appear before the named field in the HTML.

The rest of the page is what makes the form fields appear on the screen. Note that
their names match the database field names specified in the hidden field values
explained above.

When you submit this form, the web server will collect the values in the hidden and
visible fields and hand them to the next page, result.html.

Display the Search Results

When the Sesame web server sees the form submission, it will notice the special
instructions created by the hidden fields. It will search CustomersWeb.db for records
matching the criteria, sorted by Company. The data in these records can then be used
to create the web page displayed by submitting the form - result.html.

Open your text editor and type or paste the following to create a web page with a form
with the fields needed to search the CustomersWeb database. This page also contains
some special tags needed to make use of the data retrieved by Sesame, which will be
explained below.

Save the file in your Site directory as result.html.

457
18 WEB CAPABILITIES

<html>
<head>
</head>
<body>
<p>Matching Member Records</p>
[[SESAME_START_REPEAT]]
<p>
[[First]]&nbsp;[[Last]]<br>
[[Company]]<br>
[[Add1]]<br>
[[City]], [[State]] [[ZIP]]<br>
<hr>
</p>
[[SESAME_END_REPEAT]]
</body>
</html>

Everything in find.html is standard HTML and will work with any web browser. The
same cannot be said for result.html, which we will now build. While the basic
framework of the file is standard HTML, it also contains some special tags that the
Sesame web server recognizes and uses, to perform a kind of "merge" with the data.
These tags are the ones enclosed in double square braces - [[ ]].

The tags operate as follows:

[[SESAME_START_REPEAT]]
[[SESAME_END_REPEAT]]

Everything between these tags will be repeated for each record retrieved.

[[FIELD_NAME]]

Inserts the value in the named field from the current record. Note that these tags will
only work between the [[SESAME_START_REPEAT]] and [[SESAME_END_REPEAT]]
tags listed above.

So, if you type m.. into the Company field on find.html and click the Find Matches
button to submit the form, Sesame will retrieve the four records where the Company
begins with M and create a web page for you displaying the information from those
records as shown in Figure 3.

458
18 WEB CAPABILITIES

Figure 3. Dynamic web page created from live Sesame data - result.html

459
18 WEB CAPABILITIES

If you wish, you can click the Back button on your browser to enter different criteria
and submit again to see different results.

Keep in mind that these example pages are intentionally free of enhancements and
decoration. You can make your own pages as fancy as you like by using fonts, colors,
images, CSS and other web page enhancements.

Update an Existing Record


Using similar techniques to the ones used to search for records, you can also update
the matching records using an additional hidden field called postfields. Using the
postfields field instructs Sesame to take the values in the named fields and post them
to the fields with same names in the Sesame application in any of the records that
match the searched fields.

To see this in action, we will now build the pages for the Update Your Listing link on
the Menu page (index.html).

Get the Correct Record


For someone to update their listing, we will first get the correct record and prefill the
update form so they can see their current information. To do this, we need to search
the database and build a web page from the matching record, just like we did above.

CustomersWeb.db includes a unique KEY field, so we will let the user enter their KEY
in order to get their record.

Open your text editor and type or paste the following to create a web page with a form
to enter and search for a KEY.

Save the file as update.html, which is the page specified by the link on the Menu form.
Note that the hidden fields in this page are almost identical to the ones used for the
earlier search. The difference is that, this time, we are only searching the KEY field.
We have also omitted the sortfields as we expect to find only one match and do not
need to sort.

<html>
<head>
</head>
<body>
<form name="kmp" method="post" action="findkey.html">
<input TYPE="hidden" NAME="command" VALUE="search">
<input TYPE="hidden" NAME="file" VALUE="Site\CustomersWeb.db">
<input TYPE="hidden" NAME="database" VALUE="Customers">
<input TYPE="hidden" NAME="searchfields" VALUE="KEY">
<P>Please enter your Key.</P>
<TABLE>
<TR>

460
18 WEB CAPABILITIES

<TD class="copy">Key</TD><TD><input type="text" size="20"


name="KEY"></TD>
</TR>
<TR>
<TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR>
<TD class="copy"><input TYPE="SUBMIT" NAME="b1" VALUE="Find My
Listing"></TD><TD>&nbsp;</TD>
</TR>
</TABLE>
</form>
</body>
</html>

Now, if you click the Update My Listing link on your Menu page (index.html), you
should arrive at your new search form, as shown in Figure 4.

Figure 4. Search form for Update My Listing - update.html

This form submits to findkey.html as specified in the form's action tag, so we will build
that page next.

461
18 WEB CAPABILITIES

Prefill the Update Form


This page, findkey.html, is a bit longer than the others, but only because it has more
fields that the user can fill out. The methods are the same as we have used previously,
with two exceptions which will be explained below.

Open your text editor and type or paste the following to create a web page with a form
to display and update information from CustomersWeb.db.

Save the file as findkey.html.

<html>
<head>
</head>
<body>
[[SESAME_START_REPEAT]]
<form name="kmp" method="post" action="postupdate.html">
<input TYPE="hidden" NAME="command" VALUE="search">
<input TYPE="hidden" NAME="file" VALUE="Site\CustomersWeb.db">
<input TYPE="hidden" NAME="database" VALUE="Customers">
<input TYPE="hidden" NAME="postfields"
VALUE="First;Last;Company;Add1;City;State;ZIP">
<input TYPE="hidden" NAME="searchfields" VALUE="Key">
<input TYPE="hidden" NAME="KEY" VALUE="[[KEY]]">
<P>Please enter your listing information.</P>
<TABLE>
<TR>
<TD>First Name</TD><TD><input type="text" size="20" name="First"
value="[[First]]"></TD>
</TR>
<TR>
<TD>Last Name</TD><TD><input type="text" size="20" name="Last"
value="[[Last]]"></TD>
</TR>
<TR>
<TD>Company</TD><TD><input type="text" size="20" name="Company"
value="[[Company]]"></TD>
</TR>
<TR>
<TD>Address</TD><TD><input type="text" size="20" name="Add1"
value="[[Add1]]"></TD>
</TR>
<TR>
<TD>City</TD><TD><input type="text" size="20" name="City"
value="[[City]]"></TD>
</TR>
<TR>
<TD>State</TD><TD><input type="text" size="20" name="State"
value="[[State]]"></TD>

462
18 WEB CAPABILITIES

</TR>
<TR>
<TD>ZIP</TD><TD><input type="text" size="20" name="ZIP"
value="[[ZIP]]"></TD>
</TR>
<TR>
<TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR>
<TD><input TYPE="SUBMIT" NAME="b1" VALUE="Submit
Listing"></TD><TD>&nbsp;</TD>
</TR>
</TABLE>
</form>
[[SESAME_END_REPEAT]]
</body>
</html>

Note that, for each visible field, the value is preset to the current value in the
database using the special [[FIELD_NAME]] tag.

There are two things to notice about the usual set of hidden fields. First, the inclusion
of a hidden postfields field. The value of this field, just like searchfields, is a list of field
names. These field names match the names of the fields on the HTML form and in the
database. Any fields listed in postfields will post their values to the records in the
database that match the criteria in the searchfields list. In this case, all the visible
fields are listed. This line must appear in the HTML before the HTML fields it names.

The other thing to notice is that the [[SESAME_BEGIN_REPEAT]] and


[[SESAME_END_REPEAT]] tags also enclose the hidden fields. This allows you to use
values from the record found by searching for the KEY in these fields as well. For this
form, our search field is again KEY. However, instead of having the user type it in
again, we make sure we use the same record by embedding the KEY value in a hidden
field which is used again for the search by including the following line.

<input TYPE="hidden" NAME="KEY" VALUE="[[KEY]]">

On update.html, enter 938 as the Key and click Find My Listing. Sesame will build and
display the page shown in Figure 5.

463
18 WEB CAPABILITIES

Figure 5. Information for record 938 prefilled for updating - findkey.html

Post the Updates to the Database

The last piece of this process is to post the updated information back to the database.
This page already knows which record to update (searchfields) and which fields to
change (postfields). So all we need to do (if we want to) is display the results of the
update on the page specified by the action tag of this form - postupdate.html.

Open your text editor and type or paste the following to create a web page that
displays the information form the updated record.

Save the file as postupdate.html.

464
18 WEB CAPABILITIES

<html>
<head>
</head>
<body>
<p>Listing Update Confirmation</p>
[[SESAME_START_REPEAT]]
<p>
[[First]]&nbsp;[[Last]]<br>
[[Company]]<br>
[[Add1]]<br>
[[City]], [[State]] [[ZIP]]<br>
<hr>
</p>
[[SESAME_END_REPEAT]]
</body>
</html>

Now, if you change something on the update form and click Submit Listing the result
of your update will display in the browser as shown in Figure 6. For this example, we
changed City from "PHILA" to "Philadelphia".

Figure 6. Updated database record - postupdate.html

If you now search the database for this record using an ordinary Sesame client, you
will see the update in the record.

465
18 WEB CAPABILITIES

Add a New Record


Sesame web server can also add new records to a database. This uses the same
techniques as we have used until now. To make this work, we will now build the page
for the third Menu link - Submit A New Listing.

This page is very similar to the update form we created earlier. Since we are creating
a new record, we don't need searchfields, we only need postfields. We also set the
command field to "post" instead of "search". The post command instructs Sesame to
make a new record using the values from the web form, instead of finding or updating
existing records.

Open your text editor and type or paste the following to create a web page with a form
to add information to CustomersWeb.db.

Save the file as new.html.

<html>
<head>
</head>
<body bgcolor="#FFFFFF">
<form name="kmp" method="post" action="addnew.html">
<input TYPE="hidden" NAME="command" VALUE="post">
<input TYPE="hidden" NAME="file" VALUE="Site\CustomersWeb.db">
<input TYPE="hidden" NAME="database" VALUE="Customers">
<input TYPE="hidden" NAME="postfields"
VALUE="First;Last;Company;Add1;City;State;ZIP">
<P>Please enter your listing information.</P>
<TABLE>
<TR>
<TD>First Name</TD><TD><input type="text" size="20" name="First"></TD>
</TR>
<TR>
<TD>Last Name</TD><TD><input type="text" size="20" name="Last"></TD>
</TR>
<TR>
<TD>Company</TD><TD><input type="text" size="20" name="Company"></TD>
</TR>
<TR>
<TD>Address</TD><TD><input type="text" size="20" name="Add1"></TD>
</TR>
<TR>
<TD>City</TD><TD><input type="text" size="20" name="City"></TD>
</TR>
<TR>
<TD>State</TD><TD><input type="text" size="20" name="State"></TD>
</TR>
<TR>
<TD>ZIP</TD><TD><input type="text" size="20" name="ZIP"></TD>
466
18 WEB CAPABILITIES

</TR>
<TR>
<TD>&nbsp;</TD><TD>&nbsp;</TD>
</TR>
<TR>
<TD><input TYPE="SUBMIT" NAME="b1" VALUE="Submit
Listing"></TD><TD>&nbsp;</TD>
</TR>
</TABLE>
</form>
</body>
</html>

Now, if you click Submit A New Listing on your Menu page (index.html), your new
page should display as shown in Figure 7.

467
18 WEB CAPABILITIES

Figure 7. Form to create a new record - new.html

Post the New Record to the Database


The last piece of this process is to post the new record to the database. This page
already knows which fields to set in the new record (postfields). So all we need to do
(if we want to) is display the new record on the page specified by the action tag of this
form - addnew.html.

Open your text editor and type or paste the following to create a web page that
displays the information form the updated record.

Save the file as addnew.html.

<html>
<head>
</head>
468
18 WEB CAPABILITIES

<body>
<p>New Listing Confirmation</p>
[[SESAME_START_REPEAT]]
<p>
[[First]]&nbsp;[[Last]]<br>
[[Company]]<br>
[[Add1]]<br>
[[City]], [[State]] [[ZIP]]<br>
<hr>
</p>
[[SESAME_END_REPEAT]]
</body>
</html>

Now, if you fill out the update form and click Submit Listing the resulting new record
will display in the browser as shown in Figure 8.

If you search the database for this record using an ordinary Sesame client, you will
find the new record.

Figure 8. New record added to the database - addnew.html

Using these techniques, you can make a Sesame application that can be publicly
viewed, searched, and even edited without needing Sesame client software - any
browser will do.
469
18 WEB CAPABILITIES

Available Fields and Tags


This is a complete listing of the hidden fields and tags you can embed in web pages
server by Sesame's web server.

Hidden Fields
command: Instructs Sesame whether to find/update matching records (search) or
add a new record (post).
<input TYPE="hidden" NAME="command" VALUE="search">
<input TYPE="hidden" NAME="command" VALUE="post">

file: Specifies the application file to use. This file must already be loaded on the
server. For security purposes, Sesame web server will not load application files. The
value can include a path.
<input TYPE="hidden" NAME="file" VALUE="MyApp.db">

database: Specifies which database in the application to use.


<input TYPE="hidden" NAME="database" VALUE="DBName">

postfields: Specifies the list of fields to be updated or set in the affected record(s) as
a semicolon separated list. This line must appear in the HTML before any of the named
fields. The field names must match the names specified in the HTML and in the
database to be affected.
<input TYPE="hidden" NAME="postfields" VALUE="Field1;Field2;Field3">

searchfields: Specifies the list of fields to be used as search criteria as a semicolon


separated list. These fields accept Sesame search criteria, including wildcards. This
line must appear in the HTML before any of the named fields. The field names must
match the names specified in the HTML and in the database to be affected.
<input TYPE="hidden" NAME="searchfields" VALUE="Field1;Field2;Field3">

sortfields: Specifies the list of fields by which to sort the affected record(s) as a
semicolon separated list. The sort will always be ascending. This line must appear in
the HTML before any of the named fields. The field names must match the names
specified in the HTML and in the database to be affected.
<input TYPE="hidden" NAME="sortfields" VALUE="Field1;Field2;Field3">

Tags
[[SESAME_START_REPEAT]]
[[SESAME_END_REPEAT]]
Everything between these tags will be repeated for each record retrieved.

[[FIELD_NAME]]
Inserts the value in the named field from the current record. Note that these tags will
only work between the [[SESAME_START_REPEAT]] and [[SESAME_END_REPEAT]]
tags listed above.

470
18 WEB CAPABILITIES

@(LOGIN)
Inserts the login value entered by the user. This is only available if you are using a
password file. For more information, see the Sesame Web Server Security section
below.

Sesame Web Server Security


If you want to limit access to pages served by your Sesame web server, or prevent
users from seeing records other than their own, you can use a web server password
file. If you do so, upon arriving a one of your web pages, your users are presented
with a login dialog similar to the one provided by htaccess. See Figure 9.

Figure 9. Login Dialog

If you use this feature, you can also embed the special @(LOGIN) tag in your HTML to
insert the User Name in your pages. This can be very useful in a hidden field for
limiting users to their own records.

<input TYPE="hidden" NAME="searchfields" VALUE="Key">


<input TYPE="hidden" NAME="KEY" VALUE="@(LOGIN)">

To use this feature, you need a password file and an entry in your sesame.ini file. The
password file is a text file which you can create in your text editor. It has one
login/password combination per line and takes the form login:password.

Example Password File:


JSMITH:raka/shah
SGRANT:usu_sandy
VJOHNSON:m35Tdd

471
18 WEB CAPABILITIES

Once you have saved your password file, you then make an ini file entry telling
Sesame where to find it. For example, if you save the password file in your Site
directory as webpass.txt, then your ini file entry would look like this:
WEB SERVER PASSWORD FILE: Site\webpass.txt

Automatic Email Retrieval and Response

Sesame can scan an email server and retrieve the email that it finds there. If that
email contains special Sesame commands, Sesame will respond to the sender of that
email by running a report in a Sesame application an emailing that report to the
sender.

This feature is ideal for providing automated responses to customer inquiries or

Figure 10. ClientList report emailed automatically

informational needs for out-of-office employees. For example, if the Customers


database contains a report called ClientList and your sales rep needs a list of all the
clients in Pennsylvania, he can send an email to the designated address.

472
18 WEB CAPABILITIES

Sesame will pick up this email and run the report. When your sales rep checks her
email she will have a message with a report that looks something like Error!
Reference source not found..

This is what the email would contain to generate the report shown:

SCommand Open: Customers.db


SCommand Database: Customers
SCommand Query: !State=PA
SCommand Report: ClientList
SCommand Reply To: sales_rep@your_domain.com

INI File Entries


To set up email scanning, the following commands need to be placed in the sesame.ini
initialization file:

EMAIL COMMANDS: [ON | OFF] - enables/disables scanning of the POP3 server.

EMAIL COMMANDS POP3 SERVER: [server_name] - i.e.:


"outgoing.MyMailServer.net".

EMAIL COMMANDS POP3 LOGIN: [login name] - the login name on the POP3
server.

EMAIL COMMANDS POP3 PASSWORD: [password] - the password on the POP3


server.

EMAIL COMMANDS DELETE READ: [ON | OFF] - specifies whether Sesame should
delete the email message after it is read.
EMAIL COMMANDS POLL INTERVAL: [n] - the interval in seconds Sesame should poll
the POP3 server.

EMAIL COMMANDS SMTP SERVER: [server_name] - the SMTP (outbound) mail


server name.

EMAIL COMMANDS SMTP LOGIN: [login name] - the login name on the SMTP
server.

EMAIL COMMANDS SMTP PASSWORD: [password] - the password on the SMTP


server.

EMAIL COMMANDS LOCAL PASSWORD: [password] - the password remote users


must supply in their request emails.

473
18 WEB CAPABILITIES

For example, the following ini file entries scan a server named pop3.MyServer.net
every 3 minutes (180 seconds) for email in the JDoe account, using the password
my/password. Once the email is retrieved, it is deleted from the server. The reply is
sent using the same account and password for the outgoing email server of
smtp.MyServer.net:

EMAIL COMMANDS: ON
EMAIL COMMANDS POP3 SERVER: pop3.MyServer.net
EMAIL COMMANDS POP3 LOGIN: JDoe
EMAIL COMMANDS POP3 PASSWORD: my/password
EMAIL COMMANDS DELETE READ: ON
EMAIL COMMANDS POLL INTERVAL: 180
EMAIL COMMANDS SMTP SERVER: smtp.MyServer.net
EMAIL COMMANDS SMTP LOGIN: JDoe
EMAIL COMMANDS SMTP PASSWORD: my/password
EMAIL COMMANDS LOCAL PASSWORD: remote/user

Some of the commands above are optional and default to safe and/or reasonable
values. EMAIL COMMANDS DELETE READ defaults to OFF. This means that the Sesame
email scanner will not delete retrieved email from the server until this flag is set to
ON. In general, OFF is a good setting for testing purposes. Once you are using this for
actual queries, you should set this to ON to avoid responding more than once to the
same request message. EMAIL COMMANDS POLL INTERVAL defaults to 30 seconds.
Setting it lower than 30 seconds is not recommended. Many outgoing email servers do
not require a password. In such cases no SMTP login or password should be set. More
details on these sesame.ini file commands are available in the Sesame Initialization
File section.

Once scanning is enabled, Sesame will begin to scan the specified email account for
emails with special Sesame commands in the body of the email. If the correct
commands are found in the email, Sesame will reply to that email with information
derived from the applications accessible to the Sesame server.

Email Commands

SCommand Open: [Application File Name] - Specifies the application file to use. The
value can include a path.

SCommand Database: [Database Name] - The name of the database to use in the
application file specified in the Open command.

SCommand Query: [Search Spec] - Retrieve spec specifying which records to include
on the report. The spec takes the form of !Field=Spec where Field is the name of the
database field to search and Spec is what you would have typed in the Retrieve Spec.
You must include the bang(!) before the field name. Multiple criteria can be included
by using multiple SCommand Query lines in the request email.

474
18 WEB CAPABILITIES

SCommand Report: [Report Name] - The name of the report to run. This report
must be based on the database specified in the Database command.

SCommand Reply To: [Reply Email Address] - Email address where the report
should be sent.

SCommand Password: [Password Needed to Access Sesame] - This must match the
password specified in the EMAIL COMMANDS LOCAL PASSWORD entry in the
sesame.ini file.

For example, a request email containing:

SCommand Open: Customers.db


SCommand Database: Customers
SCommand Query: !Key=<1000
SCommand Report: MyReport
SCommand Reply To: sales_rep@your_domain.com
SCommand Password: remote/user

will cause Sesame to open the Customers.db application and in the Customers
database, search for records where the value in the Key field is less than 1000. It will
run the report called MyReport using those records. The resulting report will be
emailed to sales_rep@your_domain.com.

Because Sesame will reply to the email address specified in SCommand Reply To, it is
possible to send the email from one address and have the resulting report sent to a
different address.

The email scanner runs from a Sesame client, not from the Sesame server. This allows
multiple users to set up scanners on their own boxes without impacting the Sesame
server or other users. In most cases it is advisable to dedicate a Sesame client to this
task, in that it will stop responding to the user interface at the polling interval to scan
the email server for more email. Name the ini file containing the email command
something other than sesame.ini and use the -ini_file startup switch to specify the ini
file containing the email commands for the dedicated client only without impacting
other Sesame clients running on the same machine.

Because Sesame's email scanner uses email protocols, this feature can be used to
serve data to remote users using only their email program. They do not need to have
a Sesame client on their remote computer. Additionally, because email can pass
readily through firewall protected networks, Sesame email scanning can be used while
the Sesame server and all of its clients are still protected by a firewall.

475
Section 19
Troubleshooting
Q&A Translation Errors

Managing Q&A Translation Errors


Some Q&A translation errors, such as illegal field names and incorrectly formatted
data values, are errors the user should be aware of before attempting to use the new
Sesame application. These types of errors cause a warning message to appear at the
end of the translation process encouraging the user to view the Server Administration
Log for details. Click Yes to view the log. If you choose not to view the log at this
point, you can still see the translation errors at a later time by choosing File / Server
Administration. You use Server Administration even if you are running Sesame in
standalone mode.

Starting Server Administration


You will be asked for a user name (Login) and password for the Administration login.
This is different to the normal security login for a password-protected application.

Figure 1. Menu command Figure 2. Administrator login dialog.

The login name is admin and the default password is hello. Both are case sensitive
and must be entered in lower case as shown.

You will be shown the Server Administration dialog. The tabs comprising this dialog,
and the first tab shown, will vary depending upon the mode you are in: standalone or
client-server, whether an application is open or not, or whether an open application
has security or not.

477
19 TROUBLESHOOTING

Figure 3. Server Admin in Client-Server Mode

Figure 4. Server Admin in standalone mode

478
19 TROUBLESHOOTING

Once in Server Administration, click on the Local Log tab and you will see a list of
errors and warnings. There will be a line in the log for each translation error, for
example a field name that translates into an illegal layout element name, or a data
record which has an illegal value in a field. There will be one line for each occurrence
of a field which has a value which cannot be retained, such as a text value in a date
field or "ERR" in a number field. You can filter this window, e.g. for client warnings,
and you can print it, by using the menu commands.

Figure 5. Errors and warnings after Q&A Translation

479
19 TROUBLESHOOTING

Unlocking an Application

If Sesame or Designer should be terminated abnormally for any reason then the file in
use will be locked. Trying to re-open this file will give the message "Database . . .
failed to open". To unlock both DB files and DSR (Designer files) use Server
Administration. You use Server Administration even if you are running Sesame in
standalone mode.

NOTE: unlocking an application which is open for example by another user on the
network is likely to cause severe damage to the application. Make absolutely
certain that the application is not legitimately locked before unlocking it.

Sesame itself will do all it can to make sure that you are not trying to unlock an
application that is currently in use. If you attempt this, you will get a message that the
unlock attempt failed.

Starting Server Administration


You will be asked for a user name (Login) and password for the Server Administration
login. This is different to the normal security login for a password-protected
application.

Figure 6. Menu command Figure 7. Administrator login dialog.

The login name is admin and the default password is hello. Both are case sensitive
and must be entered in lower case as shown.

You will be shown the Server Administration dialog. The tabs comprising this dialog,
and the first tab shown, will vary depending upon the mode you are in: standalone or

480
19 TROUBLESHOOTING

client-server, whether an application is open or not, or whether an open application


has security or not. Click on the Unlock Application tab.

After reading the warning message, select the .DB or .DSR file to unlock. The status
box will show "Selected " followed by the pathname and filename of the selected file.
Next click on the Unlock Selected Application button. The status box changes to
"Unlocked " followed by the pathname and filename of the selected file.

Figure 8. The Unlock Application tab in Server Administration.

If Sesame will not allow you to Unlock an application it is probably because it is in use
by another user. The best approach in this instance is to either unload the application
or completely shut down Sesame server and then retry unlocking the application.

Note: Make sure that users do not try and reopen an application
once you have unloaded it.

Both the unloading and shutdown operations are available on their own tabs
servers and unload applications, respectively.

481
19 TROUBLESHOOTING

Figure 9. Shut down a Sesame server and disconnect all clients

Figure 10. Unload an Application

482
Appendix 1
Network Administration
Depending on your requirements, your Sesame client-server environment may be as
simple as two users sharing an application, or as complex as dozens of users
connecting to multiple Sesame servers serving multiple applications in a load-
balancing scheme. This section is intended to familiarize you with your choices for how
to set up your Sesame client-server system to meet your needs.

Why use a client-server setup?


The simple answer is, so that more than one person can use the same information.
Keeping your data on a server also has advantages with regard to centralized backups,
data synchronization and data security. If you are reading this section, then you
probably already have certain requirements in mind that you want to meet by running
Sesame client-server.

Configurations
Sesame can run in a number of client-server configurations:

One Computer / One Server / One Application


A single copy of Sesame Server running on a single computer on your network which
serves a single Sesame Application to multiple Sesame clients. This setup is the norm
for most small networks. (See Figure 1.)

Figure 1. One Computer / One Server / One Application.

One Computer / One Server / Multiple Applications


A single copy of Sesame Server running on a single computer on your network which
serves multiple Sesame applications to multiple Sesame clients. This setup is still
suitable for a small network, but allows for using Sesame for different applications.

483
APPENDIX 1 NETWORK ADMINISTRATION

You may have one Sesame application for Inventory and another for Sales Calls. (See
Figure 2.)

Figure 2. One Computer / One Server / Multiple Applications

One Computer / Multiple Servers / Multiple Applications


Multiple copies of Sesame Server running on a single computer on your network which
serves multiple Sesame applications to multiple Sesame clients. Using multiple servers
on the same computer allows you to separate applications by department. You may
have one Sesame Server for the Sales Departments Applications, and another that
serves Shipping and Receiving. (See Figure 3.)

Figure 3. One Computer / Multiple Servers / Multiple Applications.

Multiple Computers / Multiple Servers / Multiple Applications


Multiple copies of Sesame Server running on multiple computers on your network
which serve multiple Sesame applications to multiple Sesame clients. This setup allows
for load balancing between applications in a high traffic environment. You may want to
484
APPENDIX 1 NETWORK ADMINISTRATION

devote an entire computer, with all its RAM and CPU to the application needed by your
phone room, and use a second computer to serve other, less heavily used
applications. (See Figure 4.)

Figure 4. Multiple Computers / Multiple Servers / Multiple Applications.

Limitations
The main limitation is that a Sesame application may only be opened by one Sesame
Server at a time. Once that application is being served, it can be used by as many
Sesame clients as permitted by your license, but the application cannot also be
opened by another Sesame Server.

Setting Up the Client-Server environment


Setting up Sesame to run Client-Server is very straightforward. The Sesame
executable contains the ability to behave as either a client or a server. By installing
Sesame, you are most of the way there.

485
APPENDIX 1 NETWORK ADMINISTRATION

By default, Sesame only allows a single client to connect to a server at a time.


Increasing the number of allowed simultaneous connections requires purchase and
installation of additional licenses.

You can create desktop shortcuts that will automatically start Sesame as either a client
or a server. The command line options needed for this are detailed below.

Command line options


Running Sesame as a client or as a server is determined by command line options
used to start the program. The relevant portions of the command line syntax are:

Server
sesame -server machine_name[:port1:port2]

machine_name The name of the server computer. See your operating system
documentation for how to determine this.

port1:port2 Optional. If these are omitted, the default ports will be used. Using
and setting ports is covered later in this document.

Client
sesame -client machine_name[:port1:port2]

machine_name The name of the server computer to which this client is to


connect. This must be the same name as is used to start the Server.

port1:port2 Optional. If these are omitted, the default ports will be used. If
specified these must be the same ports as are used to start the Server to which
the Client is to connect.

Ports
Ports are a way of channeling network resources. By providing port numbers, you give
Sesame ownership of a particular set of these network resources, so that the Sesame
server can communicate with its clients without interference from or interfering with
other programs. Sesame requires two port numbers: one for normal operations and
one for special notifications messages sent from the server to the clients.

Using the default ports


If the port numbers are omitted form the command line, Sesame will use the default
port numbers of 20000 and 20001. Since only one server can be run on any one set of
ports, you can only use the defaults for a single server. If these ports are in use on
your system, you can change the default ports by making an entry in your services
file.

Location of services file:


Windows 95/98 C:\Windows\services

486
APPENDIX 1 NETWORK ADMINISTRATION

Windows NT/2000/XP C:\%SystemRoot%\System32\Drivers\etc\services


Linux - /etc/services

The services file entry specifies the first port number. Sesame will automatically add
one (1) to get the second port number. The sample entry below will cause Sesame to
default to ports 20020 and 20021. The services file may be edited using any text
editor which does not apply formatting codes. If you are in Microsoft Windows, use
Notepad. Before editing your services file, you should make a backup copy.

sesame 20020/tcp #Sesame

STARTING A SERVER ON DEFAULT PORTS:

sesame -server mymachine

STARTING A CLIENT ON DEFAULT PORTS:

sesame -client mymachine

Using specified ports


To run multiple servers, or to connect to a server that is not running on the default
ports, you will need to specify the port numbers when starting Sesame. Theoretically,
port numbers can be any number between 0 and 65535. In reality, however, many
ports are reserved or already in use. Finding out which ports are in use can be difficult.
You can look in the services file, but it is often not complete. The easiest way is simply
to try starting the server on the ports you want. If the ports are in use, you will see
the following error message:

Error: Failed to create a local socket: unknown

When choosing port numbers, it is customary to make the second port one (1) higher
than the first port (i.e. 20020:20021). Port numbers below 1024 cannot be used. It is
recommended that you use port numbers no lower than 2048.

Starting a server on specified ports


sesame -server mymachine:20020:20021

Starting a client on specified ports


sesame -client mymachine:20020:20021

Using Sesame Server


Once you start your Server using either a command line, or a shortcut, you have two
ways to interact with the Server the Server Status Window and the Server
Administration interface.

487
APPENDIX 1 NETWORK ADMINISTRATION

Server Status Window


For each Server that you launch, a Server Status Window (see Figure 5) will appear.
This is also sometimes referred to as the Server Console. The Server Status Window
provides information about the running Server.

Figure 5. Server Status Window.

Connections: Shows the number of Sesame Clients currently connected to this Server
and the total allowed by your license. A Sesame multi-user license allows a maximum
number of concurrent users.

Physical Memory Remaining: Shows the amount of available physical memory


remaining on the system. Since Sesame depends on physical memory to enhance
performance, you can use this to gauge if your system needs more physical memory
to effectively handle your application requirements.

Virtual Memory Remaining: Shows the amount of available virtual memory remaining
on the system.

Open Applications: Lists the applications currently being served. The first item on the
list is always System Database, which is used internally by Sesame.
488
APPENDIX 1 NETWORK ADMINISTRATION

Connection: Shows the connection portion of the command line used to launch the
Server. As a minimum shows the Server name.

Commands Processed: Shows the number of Client requests processed by this Server
since it was started.

Activity Meter: A bar which turns green to show the general level of Sesame Server
activity.

Uptime: Shows the elapsed time since Sesame Server was started.

Emergency Shutdown: Allows the Server Administrator to force the Server to


disconnect all Clients, close all open applications, and shut down. This is a forced
shutdown and should only be used when the normal shutdown procedures fail, or in an
emergency situation.

Server Administration Interface


To access the Server Administration Interface, start a Sesame Client attached to a
running Sesame Server. From the main menu select File / Server Administration.
A dialog box appears, asking for the Server Administrator login and password (see
Figure 7).

Figure 6. Menu command Figure 7. Administrator login dialog.

The login name is admin and the default password is hello (unless you have changed
the Server Administrator password). Both are case sensitive and must be entered in
lower case as shown.

489
APPENDIX 1 NETWORK ADMINISTRATION

You will be shown the Server Administration dialog. The tabs comprising this dialog,
and the first tab shown, will vary depending upon the mode you are in: standalone or
client-server, whether an application is open or not, or whether an open application
has security or not. Standalone mode. If you start the Server Administration interface
while Sesame is running in standalone mode, only the Unlock Application, Local Log,
Administrative Password and User Management tabs are available.

The Server Administration Interface provides the following functions:

Start and stop servers


Disconnect Clients
Broadcast messages to connected Clients
Unload applications
Update Sesame license information
Backup open applications
Unlock applications
View Server logs
Change the Administrator password
Add and delete users, change their user levels and passwords

Servers tab
The Servers tab (see Figure 8) provides the ability to start and stop servers.

Figure 8. Server Administration Servers tab.

490
APPENDIX 1 NETWORK ADMINISTRATION

To start another Server on the same machine as the Server being administered, click
the Start Another Server button. If you do not want to start the new server using the
default ports, you can also enter the desired port numbers into Port 1 and Port 2. If
the default ports are already in use, you must enter different port numbers to start the
new Server.

To stop the Server, select the desired shutdown options and click Stop This Server.

Notify All Clients: Broadcasts a message to all connected Clients that the Server is
about to shut down. The Server then waits at least 60 seconds before beginning
shutdown, giving the Clients an opportunity to save their work and disconnect.
Wait For All Clients to Disconnect: Server will wait for all connected Clients to
disconnect before starting shutdown. If Notify All Clients is also selected, the
connected Clients will be notified that the Server is waiting to be able to shut
down.
Disconnect and Stop All Clients: Disconnects all connected Clients and begins
shutdown. If Notify All Clients is also selected, the connected Clients will be
notified and given an opportunity to disconnect on their own before being forcibly
disconnected.

Notification tab
The Notification tab (see Figure 9) provides the ability to see and communicate with
connected Clients.

Figure 9. Server Administration Notification tab

491
APPENDIX 1 NETWORK ADMINISTRATION

The lower panel shows a list of machine names currently connected to the Server.
Buttons above the box allow you to mass select and deselect Clients. You can select
individual Clients by clicking on the machine name.

The upper panel allows you to type a message to be sent to the selected clients. The
Client will see the broadcasted message as a popup on their screen. Optionally, after
broadcasting your message, you can also disconnect the selected clients.

Unlock Application tab


An application is "locked" while it is in use. If Sesame releases the application without
properly closing it, due to incidents like a power failure, the application will remain
locked, and Sesame will not be able to open it. The Unlock Application tab (Figure 10)
provides the ability to unlock an application. It shows a menu tree and you can browse
to locate any Sesame application or designer file.

After reading the warning message, select the .DB or .DSR file to unlock. The status
box will show "Selected " followed by the pathname and filename of the selected file.
Next click on the Unlock Selected Application button. The status box changes to
"Unlocked " followed by the pathname and filename of the selected file.

Warning: Unlocking an Application that is locked because it is in active use by


a Sesame Server can have serious consequences, including severe data
corruption. Do not unlock an application which is in active use.

Figure 10. Server Administration Unlock Application tab.

492
APPENDIX 1 NETWORK ADMINISTRATION

If Sesame will not allow you to Unlock an application it is probably because it is in use
by another user. The best approach in this instance is to either unload the application
or completely shut down Sesame server and then retry unlocking the application.

Local Log tab


The Local Log tab (Figure 11 below) provides a log of events, warnings and errors for
the Server. This includes errors on translating (converting) a Q&A database.

The log display can be filtered by severity (see Figure 11) and printed by pressing
Alt-P or selecting File / Print.

The log file rotates automatically. It will always the show the most recent messages,
up to 10000. If more than 10000 messages accumulate, the oldest ones are deleted.
The log file is automatically created in the current working directory.

Figure 11. Server Administration Local Log tab.

Unload Application tab


This tab allows you to unload Applications. (See Figure 12 below.) You will see a list of
all applications currently open on this Sesame server, either by this client or other
clients.

Select the name of the application you want to unload and click the Unload Selected
Application button. That application will immediately become unavailable to any of the
Clients that are using that application. Because there is no warning available to these
Clients, it is advisable to only unload applications after you have confirmed that that

493
APPENDIX 1 NETWORK ADMINISTRATION

application is no longer in use by any Client as any unsaved changes will be lost. The
application file is unlocked and may be opened again by any connected Client.

Figure 12. Server Administration Unload Applications tab.

The list of applications is not automatically updated as Clients connect and open
applications. To refresh the list and view the current set of loaded applications, click
the Refresh Application List button.

You cannot unload applications that are open on the same Client that invoked the
Server Administration dialog. To unload an application that you have open on your
computer, you must first close that application, or open a second Client on the same
computer.

The Unload Application tab is only available when the server is running in client/server
mode. It is not available in standalone mode.

Relicense tab
This tab allows you to update your license information. You need to be connected to
the internet to do so. (See Figure 13 below.)

494
APPENDIX 1 NETWORK ADMINISTRATION

Figure 13. Server Administration Relicense tab.

Backup Application tab


An application loaded standalone or on a running server can be backed up by selecting
the Backup Applications tab in the Server Administration dialog box.

Figure 14. Server Administration Backup Applications tab.

495
APPENDIX 1 NETWORK ADMINISTRATION

Select the name of the application you want to back up and click the Backup Selected
Application button. Sesame will copy the files comprising the selected application to a
directory under the current working directory named after that application (.db
filename). In the case of Customers.db, the directory is named "Customers". The
copied files are named after the original application files with the addition of a unique
number. The backup file for Customers.db will be named something like
Customers1154981757.db. The backup file for Customers.dat will be named
Customers1154981757.dat. The files created by Backup Selected Application are not
immediately loaded for use as they would be using the similar "Save As" command.

Once an application has been backed up its name is removed from the selection list in
the dialog box. To restore an application's name to the list, or to see the current set of
applications loaded on the server, click the Refresh Application List button.

Administrative Password tab


The Administrative Password tab (see Figure 15) allows you to change the
administrative password. It is strongly recommended that you change the
administrative password from the default, especially if you are running in a multi-user
environment.

Type the password in the New Password input box. It shows as asterisks. Type it again
in the Confirm Password input box. Click on Apply. If successful the message box
shows "Password accepted". If not the message box shows "Error: Passwords not
accepted. They do not match.".

NOTE: Admin password is case sensitive. Be careful to note the state of the Caps Lock
key when changing passwords, as you do not see the password entered.

Figure 15. Server Administration Administrative Password tab.

496
APPENDIX 1 NETWORK ADMINISTRATION

User Management Tab


The User Management tab will only be shown if there is open, on that client, an
application with security applied. The User Management tab (see Figure 16) allows
the Server Administrator to make changes to some of security settings (user
information and permissions). From this tab, you can:

Add, rename and delete Users


Change Logins and Passwords
Move a User to a different Group
Change a Users security level

You cannot:

Create, delete or rename Groups


Change Design permissions
Change Group permissions

Figure 16. Server Administration User Management tab.

Changes made on this tab will be overwritten by a Reconcile made from the Sesame
Designer module, if the security setting at the reconcile Options dialog is changed
from the default "No" setting. (See Figure 17.) If this is set to Yes, then changes to
security for example changed user passwords made since the last reconcile,
would be lost.

497
APPENDIX 1 NETWORK ADMINISTRATION

Figure 17. Replace Security option at reconcile dialog.

Standalone administrative client

Sesame can be started as an administrative client. In this mode, Sesame only shows
the Server Administration dialog. The administrative dialog that appears when running
Sesame as an administrative client is identical to the dialog that is invoked by
selecting Server Administration form the File menu in either Sesame Runtime or
Designer. Starting Sesame this way does not use up a client license and is intended to
be used on those occasions when you intend only to perform server administration
tasks.

This mode is invoked by starting Sesame with the "-admin" startup switch:

sesame -admin ServerName

Optionally, you can start the administrative mode with the port number specified:

sesame -admin ServerName:20005:20006

The port number used must match the port numbers used when the Sesame Server
was started. The administrative mode can only be used when Sesame is running
client/server.

Network administration tips

Following are a few tips and tricks that may improve your client-server experience.

Preloading applications
Sesame opens an application when it is needed and closes it when the last Client using
the application releases it. If there is an application that is used regularly for XLookups
or is used daily and takes a long time to load, you may want to preload the application
and make sure it stays loaded. You can do this by starting a "dummy" Client and
opening the desired application. As long as this Client remains open, the Server will

498
APPENDIX 1 NETWORK ADMINISTRATION

keep the application loaded. The "dummy" Client can be on the same machine as the
Server.

Sesame on the Internet


Sesame Server can be run on a machine which is attached to the Internet just as if it
was running on your local network. To start the Server, use your website address as
the machine name:

sesame -server www.lantica.com:20000:20001

Clients can attach to the above server in the same way:

sesame -client www.lantica.com:20000:20001

Protect your computer with rootdirs.ini


You can use the rootdirs.ini file to restrict access to files on the computer running your
Server. Sesame will only allow users to browse directories that appear in the
rootdirs.ini file. The rootdirs.ini file below will restrict users to the Sesame data
directory, the Lantica data directory and their subdirectories.

c:\sesame\data
c:\lantica_data

To allow full access to the computer, add [DRIVES] to ROOTDIRS.INI. This


ROOTDIRS.INI file will offer users the Sesame data directory as a first choice, but
allows access to all the drives for the Server machine.

c:\sesame\data
[DRIVES]

The rootdirs.ini file should be placed in the current working directory on the Server
machine. If you do not want to keep your rootdirs.ini file in the current working
directory, you can specify a full path to this file using the SESAME_ROOTDIRS_PATH
environment variable.

Manage your license file


If you do not want to keep your license file at the default location, you can set an
environment variable to tell Sesame where to find your license file.

The example below tells Sesame to look for your license file in the HideMyFile directory
on your C drive. The variable name is SESAME_LICENSE_PATH. The value should be
the full path to your license file, including the filename.

SESAME_LICENSE_PATH = "c:\ HideMyFile\s_conf.cnf"

499
APPENDIX 1 NETWORK ADMINISTRATION

You can also use this method to rename your license file. See your operating system
documentation for instructions on setting environment variables.

Protect your server with the network connection allow and deny files
There are two optional files the Sesame server will use to specifically allow or deny
particular network connections or ranges of connections. These files can be used to
make sure that only specific computers are allowed to connect to your server. When a
particular computer running Sesame Client attempts to connect to a Sesame Server,
the Sesame Server will attempt to locate that computers IP address in the allow file, if
there is one. If that IP address exists in the allow file, or there is no allow file, the
Sesame Server will attempt to find that IP address in the deny file. If it finds that
address in the deny file, the connection is disconnected. If there is no deny file, or the
IP address is not found in the deny file, the connection is allowed to continue.

The wildcard character "*" (asterisk) may appear within the IP address specified in the
allow and deny files. Once it appears, it causes a range of addresses to be specified.
Subsequent wildcard characters will be ignored:

In the allow file:

192.168.0.* allows all computers with IP address starting with 192.168.0 to be


connected.

178.* allows all computers in the IP range starting with 178 to be connected.

168.20* allows all computers in the IP range starting with 168 with a secondary
address of 200 or greater to be connected.

The same wildcard rules apply equally to the deny file. Using the combination of the
two files it is easy to set a range of computers that are allowed, such as a single
department, while excluding particular computers from within that department:

In the allow file:

192.168.0.*

In the deny file:

192.168.0.22
192.168.0.23
192.168.0.147

The above examples will exclude all computers not in the range of 192.168.0 (those
not in the department) and the specific computers with IP addresses ending in 22, 23,
and 147.

500
APPENDIX 1 NETWORK ADMINISTRATION

The allow and deny files do not use unresolved IP addresses (for example,
www.lantica.com). All IP addresses must be specified numerically in the common IP
address dot separated format: XXX.YYY.ZZZ.NNN (for example, 192.168.0.12).

The default filename for the allow file is "sesame_allow.txt". The default filename for
the deny file is "sesame_deny.txt". Unless superseded by the environment variables
SESAME_ALLOW_FILE and SESAME_DENY_FILE, both files must appear in the current
working directory to be used. The environment variables supersede the full paths and
filenames.

It is recommended that Sesame system administrators set these files to be read-only


to prevent access by users who are allowed write access to other files in the same
directory. Of course, it is also recommended that firewalls and routers be configured to
prevent unauthorized access.

501
APPENDIX 1 NETWORK ADMINISTRATION

New Sesame 2.0 Integrity Features

Log File
Sesame 2.0 logs message, errors, and warnings to a file named "s2_logxxxx.log",
where "xxxx" represents a four digit number, such as s2_log0000.log or
s2_log0001.log. The four digit number is incremented to produce a new file if the
currently highest numbered file cannot be written by Sesame. As with earlier versions
of Sesame, the log file format cannot be read or written in any other program, such as
a text editor or word processor. The Sesame 2.0 log file contains a "key" value to
distinguish it from earlier versions and to protect the file from external manipulation.
This file can be viewed or printed from the Server Administration window.

Lock/Unlock
Sesame application files (.db. .dat, .dsr, .ddt) are locked while in use. Unlocking an
application file while it is in use allows multiple Sesame servers (whether running
client/server, or standalone) to access that file at the same time. Each server has a
copy of that application file in its own memory. As each server runs, these different
copies begin to differ from one another as different users make different changes to
the application. Having these multiple servers writing these changes all to the same
file causes that file to become unusable to any of the Sesame servers. This is only
possible if the file becomes unlocked while in use.

To prevent multiple Sesame servers from accessing a Sesame application at the same
time, the administrative interface will not allow unlocking an application file that is
currently running on that Sesame server. The "Unlock" tab in the Server
Administration dialog will only present application files that are not currently loaded
into the current Sesame server.

It will present application files that are in the current root directories available to that
server that are not loaded in that server, but might be loaded into a different Sesame
server. Each Sesame server is independent of any others that may be running on that
computer, or any computer that has access to that computer's file system, and cannot
know if any application file is loaded onto a different Sesame server. Because it can
only know if a file is locked or unlocked and whether or not that file is loaded into its
own memory, a Sesame server can unlock applications that are loaded in a different
Sesame server.

Because unlocking a running application can cause that application file to be rendered
unusable, the Sesame server checks if its application files have been unlocked by an
external server. If they have, the Sesame server with those file loaded will
immediately begin to refuse to save any changes made by the attached clients. The
clients will receive an alert indicating, "This application has been unlocked while
running. This application will no longer save changes to the application files. It is
recommended that you close this application at once."

502
APPENDIX 1 NETWORK ADMINISTRATION

Additionally, Sesame 2.0 uses facilities in the operating system to make it difficult, if
not impossible, for an external program or user to unlock, copy over, delete, or in any
other way alter a running Sesame application. In most cases it requires a concerted
effort to allow an external program, including a different Sesame server or the
command line "sunlock" program to unlock a running Sesame application. Different
operating systems provide differing levels of file protection and cannot be relied on to
provide 100% protection for running files. For this reason, it is strongly advised that
great care be used when copying application files atop one another, or when unlocking
an application, to make sure that you are not inadvertently unlocking or overwriting a
running application.

Communications
Sesame 2.0 provides a "heartbeat" message to client/server network communications.
Every ten seconds, the Sesame server sends a "ping" message to each of the
connected clients. If a client, for whatever reason, does not respond to the heartbeat
message within thirty seconds, that client is considered disconnected and the server
will close the ports used by that client and reclaim the connection for use by a
different client. This all happens automatically and does need any action on the part of
the user or administrator. The "ping" and the "ping reply" are handled in tasks
separated from the main tasks in both the client and the server. So having
exceptionally busy clients or servers will not cause a timeout condition. Clients are not
automatically detached due to inactivity or idleness.

Many of the critical communications between client and server now have timeout
values so that the client or server can detect if the network has failed. This allows the
client or server to continue operation and report the error, rather than waiting
indefinitely for communications to resume. The length of the timeout period varies
depending on the command. Most are set to very lengthy periods, greater than ten
minutes, to prevent premature failures.

Communication timeout detection is entirely automatic. It does not require any action
on the part of the user. Should a communications failure occur, it is important that the
circumstances be examined to determine if there has been a network failure. Any
network failure should be repaired before that network is put back in use.

503
APPENDIX 1 NETWORK ADMINISTRATION

Optimizing Performance

Sesame 2.0 incorporates many new features to maximize performance. Some are
automatic, some are optional.

Load optimization occurs when an application is loaded into the Sesame Server from
the application file. Sesame 2.0 loads applications 4-10 times faster than Sesame
1.x.x, depending on the size and configuration of the Sesame application. For
example, on a Pentium IV with 2 gigabytes of RAM, a 100,000 record application with
442 megabytes of data, takes 61 seconds to load in Sesame 1.1.4. The same
application takes 6 seconds to load in Sesame 2.0. An application with 91,000 records,
but only 25 megabytes of data takes 4 seconds to load in Sesame 1.1.4, and only one
second in Sesame 2.0.

This optimization is in place for initial loading when an application is opened by a client
or standalone, and also when applications are loaded to be used by "X" commands in
SBasic. The optimization is in the Sesame Server and in Sesame standalone. If you
have a large application and start to see slower loads occurring, the server/standalone
computer probably needs to have more RAM installed.

Load optimization is achieved by preloading the file image of the application's files
directly into memory in a single operation and then "parsing" that image into the
application the Server will actually present to the clients. This means that the
optimization depends on the server computer having enough memory to briefly keep
two copies of the application in memory. If the load cannot get enough memory,
including both RAM and "swap", for the optimization, it will "fail over" and use the
slower load. This is a very rare condition and will only occur if the application file is
very large, or there is very little available memory.

Find Duplicates Optimization


The operations associated with finding duplicate records have been highly optimized
for speed. For both the Remove Duplicates command and the Delete Duplicates
command, Sesame 2.0 will find the duplicate records approximately 400 times faster
than Sesame 1.x.x.

Relational Records Search


The major optimization of relational searches occurs when there are search
parameters in both the parent and the child records. In Sesame 2.0, the parents that
do not meet the search parameter are eliminated from the collection of records that
must have their child records searched. This causes the search as a whole to run many
hundreds of times faster, especially if the search parameter for the parent is very
exclusive.

Relational record searches have also been optimized through a dynamic index of the
relational key fields in the child records. This allows the child records to be excluded

504
APPENDIX 1 NETWORK ADMINISTRATION

from consideration in the search much faster, especially if the relational key field is
unique or exclusive in value.

Both relational search optimizations depend on the search parameter and the key
fields to be free of search constructs. In other words they must be values that match
the field value as a whole, rather than wildcards or range comparisons.

X-Commands
With the SERVER PREINDEX XLOOKUPS flag set in the sesame.ini file, XLookup
commands use the same preindexing as relational records. This allows the X-
Commands to run much faster than non-indexed records. Setting the flag will cause X-
Commands to run 100 to 400 times faster. For example, a simple XLookup to an
application with 100,000 records normally provides 385 results a minute. The same
XLookup using the preindexing flag provides 120,774 results a minute. As with the
relational indexing, the X-Command indexing requires that the key value not contain
any search constructs, such as wildcards or range comparisons.

Images
In Sesame 2.0, images are cached on the Server. This means that after the Server
has read an image file from the hard drive, it is kept in memory. If that image is
needed again, it does not need to be reread from the hard drive, but can be sent from
the server's memory directly to the requesting client.

FormFieldValues in Tables
The SBasic function @FormFieldValues detects if the element to be accessed is in a
table. If so it reads the value directly from the table without requiring that the table
refresh that value from the server. While necessary for a form view subforms, further
acquisition is not required by table subforms in that every record In a table subform
has already been acquired from the server. This results in much faster
access to elements in tables than is possible in Sesame 1.x.x. In Sesame 1.x.x, a
typical retrieval from a table view subform provided 4,575 values a minute from
@FormFieldValues. In Sesame 2.0 the same function provides 373,720 values a
minute on the same Pentium IV computer.

Just in Time Compilation


In order to speed up initial form opening of heavily programmed forms, there is a
sesame.ini file entry called "JUST IN TIME COMPILATION: [ON | OFF]" that causes
form code to compile only when it is about to run. This eliminates much of the wait
associated with opening forms. The only code that will compile on initial opening is the
form's GLOBAL CODE. It may cause some hesitancy when tabbing through a form's
elements for the first time, as the code in various elements gets compiled. This
hesitancy will only be present for the first time the user moves through that element,
or triggers a particular event. The default is OFF.

505
Appendix 2
Sesame Environment Variables
Sesame uses a small set of environment variables to customize its behavior. Most of
these variables are completely optional. Some of the variables are created by Sesame.
Others are operating system variables used by Sesame to locate specific resources.

All Operating Systems Variables


SESAME_ALLOW_FILE Supersedes the default path and filename of the network
connection allow file. If this is not set, the allow file path defaults to the current
working directory. The allow file is named "sesame_allow.txt".

SESAME_DENY_FILE Supersedes the default path and filename of the network


connection deny file. If this is not set, the deny file path defaults to the current
working directory. The deny file is named "sesame_deny.txt".

SESAME_HELP_PATH Supersedes the default path to the Sesame help directory.


The default is the directory "HelpFiles" in the current working directory.

SESAME_LICENSE_PATH Supersedes the path and the filename of the Sesame


client / server license file "s_conf.cnf". By default, s_conf.cnf must be in the current
working directory of the Sesame server.

SESAME_REPORT_PATH Supersedes the current working directory as the directory


location where report files are created. (Details below.)

SESAME_ROOTDIRS_PATH Supersedes the path and filename of the "rootdirs.ini"


file. The default path is the Sesame servers working directory.

SESAME_PRINT_COMMAND Used by Sesame to supersede the default print


command for your operating system. On Unix, this command will also supersede the
LPDEST, PRINTER, and SESAME_PRINTER variables.

SESAME_PRINT_PREVIEW_COMMAND Used by Sesame to supersede the default


"open to preview" command for your operating system. On Unix, this command will
also supersede the BROWSER variable.

Unix-only variables
BROWSER* Used by Sesame to determine the HTML browser to be used by the Help
System. If BROWSER is not set, the HTML browser "netscape" will be invoked.

LPDEST* Used by Sesame to determine the special file for the printer device to be
used. LPDEST is only used if PRINTER is not set.

507
APPENDIX 2 ENVIRONMENT VARIABLES

PRINTER* Used by Sesame to determine the special file for the printer device to be
used. PRINTER is only used if SESAME_PRINTER is not set.

SESAME_PRINTER Used by Sesame to determine the special file for the printer
device.

Note: If LPDEST, PRINTER, and SESAME_PRINTER are not set and no


PRINT_COMMAND is set, Sesame will default to using "a2ps" for printing.

*These are usually set by Unix and not special to Sesame.

For Microsoft Windows operating systems, because the method of setting environment
variables is different on most versions of Microsoft Windows, see your operating
system documentation for how to set environment variables for your system.

For Unix based operating systems, environment variables are set based on the shell
being employed:

Examples:
ksh: export LPDEST=/dev/lp
tcsh: setenv LPDEST /dev/lp

Setting Report Writer Output File Environment Variable


Every Sesame report you run using Preview or Print Immediate output, produces a
preview in your default browser or outputs directly to your printer. Running a report
either way also creates an HTML output file in the current working directory. This file
will have a filename structured along the following lines:

Schedule_Report_2_2003_11_02_20_47_29.htm

The structure breaks down this way:

Report Name + Report Date (YYYY_MM_DD) + Report Time (HH_MM_SS).htm

By default, these HTML files are created in your current working directory. The current
working directory is where you "are" as far as your computer is concerned. This
directory is not affected by where you installed Sesame. If you started Sesame using a
Windows desktop shortcut, your working directory is the path shown in the Start In
property of the shortcut. If the Start In property is blank, then your working directory
is a system default directory, such as your Desktop folder. If you are running from a
command line, the current working directory is the directory shown at the command
prompt.

508
APPENDIX 2 ENVIRONMENT VARIABLES

If you do not want your report files in the current working directory, you can set an
environment variable to specify a different path for them a path such as
c:\sesame\reports.

The environment variable you need to set is SESAME_REPORT_PATH.

Follow the steps below to set this environment variable on the Sesame Client
computer for that computers operating system. Other Sesame environment variables
can be set using the same procedure. If you are unsure about anything, or the screens
shown below are not the same as yours, ask your system or database administrator
for assistance.

For Windows XP and Windows 2000

1. Exit Sesame if it is running.

2. Create the folder on your computer (if it doesnt already exist) where you want
to store your Report Writer output files. For example, c:\sesame\reports.

3. From your Windows XP or Windows 2000 desktop, click Start / Control Panel.

4. In Control Panel, double-click on the System icon to display the System


Properties dialog. (See Figure 1 for Windows XP; Figure 1a for Windows 2000.)

5. Click on the Advanced tab. (See Figure 1a for Windows XP; Figure 1b for
Windows 2000.)

509
APPENDIX 2 ENVIRONMENT VARIABLES

Figure 1a. The Windows XP System Properties Advanced tab with the Environment Variables
button.

510
APPENDIX 2 ENVIRONMENT VARIABLES

Figure 1b. The Windows 2000 System Properties Advanced tab with the Environmental Variables
button.

6. Click on the Environment Variables button to display the Environment


Variables dialog. (See Figure 2.)

7. Under System Variables, click on the New button to display the New System
Variable dialog. (See Figure 3.)

511
APPENDIX 2 ENVIRONMENT VARIABLES

Figure 2. The Environment Variables dialog.

Figure 3. The New System Variable dialog.

8. In the Variable name field, type SESAME_REPORT_PATH as shown in Figure 3.

512
APPENDIX 2 ENVIRONMENT VARIABLES

9. In the Variable value field, type the full path to the folder where you want
Sesame to create your report files. Figure 3 shows a C:\SESAME\REPORTS
path already entered.

10. Double-check that you typed the variable name and value correctly, then click
OK to save your new environment variable.

11. Click OK twice more to return to Control Panel, then close Control Panel.

Your SESAME_REPORT_PATH environment variable has been set. You do not need to
restart your computer.

For Windows 98

1. Exit Sesame if it is running.

2. Create the folder on your computer (if it doesnt already exist) where you want
to store your Report Writer output files. For example, c:\sesame\reports.

3. In Windows Explorer or My Computer, locate your autoexec.bat file. This file is


normally stored in the C: folder. Right-click on the file and select Edit from the
submenu. This should display the file in Notepad.

4. Move to the end of the file and, on the first available empty line, type the
following:

SET SESAME_REPORT_PATH=C:\SESAME\REPORTS

5. Replace C:\SESAME\REPORTS with the full path to the folder where you want
your Report Writer output files stored. Otherwise, the line must be typed
exactly as shown. Do not use quotation marks.

6. Save the file.

7. Close any open programs, then restart your computer for the change to take
effect.

For Unix-based operating systems

For Unix based operating systems, environment variables are set based on the shell
being employed:

Examples:
ksh: export SESAME_REPORT_PATH = "/usr/local/Sesame/Reports"
tcsh: setenv SESAME_REPORT_PATH "/usr/local/Sesame/Reports"

513
Appendix 3
Philosophy
Filling the void
If you are familiar with the history of Sesame, then you know that it began as a
replacement product for a Symantec database product called Q&A. All of the original
Lantica team are developers, consultants and power users brought together by using
Q&A. As Q&A began to be less and less viable, mainly due to changes to hardware and
operating systems, the Q&A community began to look for a replacement. They wanted
an easy-to-use database product that they could run themselves, yet still had enough
power to create viable business applications. They had a hard time finding one.

The current software market is filled with application development tools. These are
products focused on allowing a consultant/developer to build an application which
users then use. The users dont really know how it works and they cant find out. If
they need changes, the consultant/developer must provide them. Many products are
turning more and more into nothing more than front-ends for high-end database
engines.

Sesame, on the other hand, tries to maintain a slant towards the user. Simple tasks
remain simple until you ask for more complexity. Powerful features are available, but
you are not forced to deal with them. Wherever possible, Sesame offers you the easy
way first. Its design philosophy is centered around allowing users and small business
people to be self-sufficient.

Batch based operation


Sesame is batch based. Once you have retrieved (or added) the records you want, you
can perform multiple operations on those records without having to retrieve them
repeatedly. The batch of records is called a Result Set. Because Sesame uses batches
so heavily, the tools available to get exactly the records you want are extensive and
flexible. Some examples of this are Drilldown Searches and the ability to remove
individual records from the Result Set.

Form based
Sesame is highly form-based, especially in Designer. The connection between data and
forms is often difficult for a new user to understand. Sesame allows you to build your
forms first. As you build forms, Sesame quietly creates matching storage for your
data. This is explained more fully in the Advanced Concepts appendix of this manual.

Non-invasive interface
Sesame tries to avoid doing anything that you did not explicitly ask it to do. It also
tries to stay out of your way as much as possible. Confirmation dialog boxes are
limited to actions that can be destructive to your data. Layout elements and forms
attempt to maintain your cursor position as you move between elements and records.

515
APPENDIX 3 PHILOSOPHY

Command trees maintain the state you left them in until you close their tab. In
general, screen elements do not attempt to second-guess your intent.

Revaluate ease-of-use
Just because a particular technique is common, that alone does not automatically
mean that it is good. While familiarity is part of overall ease-of-use, it is not the only
factor to be considered. Sesame sometimes departs from a commonly used technique
where doing so would improve usability.

The philosophy in action


Application of the general principles listed above results in many concrete effects that
you will encounter while using Sesame. Many instances of this philosophy (such as
those listed above) appear quite obviously in Sesame Runtime, where you will
encounter them daily. The effects on Sesame Designer may be less obvious.

Separate Designer module and separate Designer files


Sesame Designer is separated from Sesame Runtime both by being separate
executables, and also by the fact that Designer operates on a copy (dsr file) of the
working application (db file). This layer of separation between the application design
and the working application provides some advantages:

It allows for a much smaller installation for those users who do not need to
design or redesign databases.
It protects a copy of the application design itself.
It allows the application designer to make and test extensive changes to a
working application without requiring the runtime users to stop working.
It allows the application designer to keep multiple revisions of an application
design. This way, if a particular change does not work out, it is fairly easy to
retreat to an earlier version of your application. This also allows you to keep a
history of your application changes.

Disabling of Menu Choices


In general, if a particular action will do no harm, Designer will allow you to do it, even
if it may have little effect. For example, you can Preview an application, even if you
have not yet added any forms. Doing so is likely to be pretty boring, but it wont do
any harm. In situations like this, Designer assumes that you have some reason for
wanting to do that particular action, and your reasons are good enough for it.

Disabling of Properties in the Property Editor


Designer departs from other current software packages in several ways. One of these
is disabling or "graying out" of choices. In some packages, if you select multiple
objects, only choices that apply to all the selected objects are available. The problem
with this is, if you want to set a particular property for some of the selected objects,
you must first locate the ones that dont have that property and deselect them.

516
APPENDIX 3 PHILOSOPHY

Designer takes the opposite route. With few exceptions, all properties are available at
all times. If one of the selected elements does not accept the property, that element is
simply skipped. For example, all elements have a background color property.
However, only certain elements display a value of type DATE. If you select several
elements and apply a background color, the change affects all the selected elements.
If you then change the date format, the change affects only those elements displaying
a value of type DATE. The non-DATE elements are ignored. This prevents you from
having to deselect all the non-DATE Elements to apply your format change.

Property Editor vs. Property Viewer


Another way in which Designer departs from other packages is in the separation of the
Property Editor from the Property Viewer. Property Viewer displays the current settings
of the selected elements, while Property Editor enables you to alter these settings.
This has several advantages over an integrated viewer/editor:

It allows you retain the "last thing you did". For example, you can set sizing
and alignment for one set of elements, then apply those same settings to
another set of elements with a single click, and without having to remember
exactly what you did.
It keeps the current settings available for reference until you actually change
them.
It allows Designer to offer richer controls for setting properties than are
needed for displaying properties. For example, the color chip palettes used for
selecting colors, as opposed to the single line used to display your choice.

Report Writer
Sesame Report Writer does not look like the striated "WYSIWYG" report designer that
is often used. The main reason for this is because those report designers are not really
WYSIWYG. The striated sections are not able to correctly depict the dynamic section
sizing and repetition that occurs when a report is actually run. Sesame Report Writer
uses a simple list. You tell it what you want in what order. Because the reports are
HTML-based, sizing and layout is handled automatically. By not pretending to be
WYSIWYG, Sesame Report Writer can often provide a clearer picture of what your
report design will actually produce.

Whats in it for you?


Hopefully, the end result of the philosophy implemented in Sesame is a product that is
easier and more efficient to use. If you want a simple application, you can have one by
doing a few simple tasks. If you want to explore Sesames power, you can do so in a
way that allows you to proceed at your own pace. Sesame will do its best to supply
you with tools as you request them, and stay out of your way wherever possible. The
applications you build will reflect your choices, not Sesames choices. Ultimately,
whats in it for you is whatever you choose to make out of it.

517
Appendix 4
Advanced Concepts
Application components
By this time you will have built several forms, added numerous layout elements, and
created the components that are the underpinnings of Sesame: databases and fields.
While it is not necessary to understand exactly how these elements relate to one
another, it may well be beneficial to the designer of more complex applications to have
a clear picture of what is going on "behind the scenes."

Forms and layout elements


The most apparent component of Sesame is the form. It is the face of your
application. But what is a form? In the simplest sense: a form is a container. It holds a
set of layout elements. But, that does not wholly describe what a form does. A form
provides a link between a set of layout elements and the data they represent. Usually,
that link is provided automatically and does not require any decisions from you. In
Sesame, building a form and placing layout elements on the Form also builds a
database and a set of fields in that database.

In the simplest case, you create a form. Sesame takes note of this and builds a
database to which that form is tied. You then place layout elements, such as text
boxes, combo boxes, or radio button groups, on the form. Sesame builds fields in the
database that can hold data for each of these elements. In this simple case, a form
and a database parallel each other. A layout element and a field parallel each other. A
form contains layout elements and gets data from a database. A layout element is the
"window" onto the data contained in a particular field in that database. (See Figure 1.)

519
APPENDIX 4 ADVANCED CONCEPTS

Figure 1. Forms and layout elements provide a "window" onto your data.

Record definitions and field definitions


Throughout the Sesame User Guide and Programming Guide, the term "database" has
been used to describe the collection of records, forms, reports, specs, etc. as they are
defined internally. Here we need to speak of a more limited concept: The record
definition. A record definition is a component in Sesame that contains a collection of
field definitions. Neither a record definition nor a field definition ever contains any user
data. Instead, they keep track of the characteristics of the user data. For example, if
you create a layout element on a form, and you tell Sesame that that layout element
should contain a Date field, Sesame will build a field definition that has the type Date.
It will also put that field definition in a record definition that was built when you built
your form. When it comes time to enter data into that form for the very first time,
Sesame will look to the record definition to build an actual record to hold that user
data. A record definition can be seen as a "blueprint" for a record, used by Sesame to
make sure that all the fields in that record are the correct type.

520
APPENDIX 4 ADVANCED CONCEPTS

Binding user interface components to data engine components


While forms are bound to records, and layout elements are bound to fields, it is the
record and field definitions that make that binding. When you look at the properties of
a form, alongside properties like Background Color and Font, you also see the name of
a record definition shown as Database Name. The same can be said of a layout
element and a field definition, shown as Bound To. By knowing the name of the
definition that determines the characteristics of its data, the form and the layout
element "know" where their data is, and what it is like.

The form-to-record definition relationship is often completely invisible. But, there are a
few cases where this relationship can be manipulated by the application designer get
the most out of their application. The most obvious example of this is a database that
contains more than one form providing views onto a single record definition. Because
Sesame separates forms from records, it is easy to build two forms that each show the
same set of records. These records, will, of course, be built from the same record
definition.

For example, imagine that you have a form that displays employee information. It is
complete in that it displays all of the information about each employee. You may also
want a form that only displays contact information about each employee, excluding
many of the fields that are not appropriate. You could use the same form again and a
healthy bit of security to hide the inappropriate layout elements. But, in many cases, it
would be far simpler to build a second form that is simply bound to the same record
definition as the first. Its layout elements would then be bound to the field definitions
of the desired fields, thereby hiding much of the information the first, more complete,
Form reveals. Figure 2 shows the field definitions that might appear in an Employees
record definition.

Field Definition Field Type


Last Name TEXT
First Name TEXT
Street Address TEXT
City TEXT
State TEXT
Zip Code TEXT
Phone TEXT
Age NUMBER
Years Experience NUMBER
Salary MONEY

Figure 2. Sample record definition for EMPLOYEE.

The sample record definition in Figure 2 is created automatically by building the form
in Figure 3. No additional field definitions are created by building the form in Figure 4.
Instead, the form and its layout elements are bound to the record definition and field
definitions that were created when building the form shown in Figure 3.
521
APPENDIX 4 ADVANCED CONCEPTS

Figure 3. Employees form.

Figure 4. A second form based on the Employees record definition, but showing only some of the
fields.

Once a form is built, and a record definition is bound to that form, Sesame can build
records based on that record definition. These records are bound to the record
definition that was used to make them. Just as a form has a record definition specified
as one of its parameters, every record in a Sesame application also has a record
definition as one of its parameters. This is how Sesame determines the type of any
record in the application. Unlike the layout element-to-field definition relationship, a

522
APPENDIX 4 ADVANCED CONCEPTS

record can never be unbound from its record definition, or re-bound to a different
definition.

Subforms and subrecords


Forms contain layout elements, but can also be contained within a layout element. In
Sesame, we call this a subform. A subform layout element is special in that, where
other elements are bound to a field definition in the containing forms record
definition, a subform layout element is bound to a reference to the form that it
displays. In a sense, the subform layout element has a form as its data. The subform
layout element is a window onto another form. The "Display Form" parameter in the
subform element tells it which form it is supposed to display through the window.

Subform elements have the concept of a view. A text field can be displayed in Sesame
using a text box, a combo box, or even a radio button group. Each of these are views
onto the text field. The subform element isnt quite so flexible. Its views are limited to
Table View or Form View. The views can be seen as both a kind of filter and a type of
format. The Table View, for example, filters out (does not display) any static elements
from the form displayed in the subform element. The format for a Table View subform
is the familiar tabular arrangement of columns and rows, where each column
represents a non-static layout element and each row represents a record. The view
used by an element to display a field value or another form does not change the
underlying bound data in any way. Views are there to help you and your users
understand and edit their data.

Natural vs. relational linking


Subforms also support two different types of linking: Natural and Relational. Natural
linking is the default. For many users, natural linking will provide a simple parent/child
relationship. For example, if you were to build an application to keep track of your
music collection, you might use natural linking to build a subform showing the songs
on each album. That subform might have elements for the songs title, the authors of
the song, and the length of the song in minutes and seconds. In almost every case,
that song would be unique to that album. The record for the album would point
directly at the records for the songs on that album.

If we were to look directly at the record definition for the Album record we would see a
field definition called SongList. That field definition would have the type SUBRECORD
and would contain the record identifier (an index into the application) that points to
the record definition for the Song records. If we looked directly at an actual Album
record, we would find a field that contains the record identifier for a Song record as its
data. That way each Album has a unique list of Songs as children. Note that natural
linking uses direct pointers to records. There are no key fields (hidden or otherwise) as
there are in relational linking. (See Figure 5.)

523
APPENDIX 4 ADVANCED CONCEPTS

Figure 5. With Natural linking, relationships are stored as pointers to actual records.

Natural linking has the advantage of being very simple and very fast. But it is also
inflexible. With natural linking, once a record is set as a child of another record, it
cannot be moved to be a child of a different parent record. The parent record can
delete its children, or add more children, but it cannot share a child with another
parent record. So, if a song is on an original album, and also on the Greatest Hits
album of the same musical group, that song would appear identically on two different
song records, under two different album records. If you were to correct the songs
author field in one of the two records, it would not be changed in the other. That can
lead to a data normalization problem, if the two recordings are actually identical
songs.

To remedy the normalization problem, Sesame also provides relational linking.


Relational linking retains the same parent/child relationship as natural linking. The
difference is in the method by which any particular parent record recognizes its child
Records. Where natural linking has a direct pointer form the parent record to the child
record, relational linking provides the addition of a Key Field set. The key field set
stores the name of a field in the parent and the name of a field in the child. For any of
the records that are of the correct type to be considered a child of a particular parent
record, the data in the parents key field and the child key field must match.

524
APPENDIX 4 ADVANCED CONCEPTS

Going back to our example of a record album collection, while it may make sense to
use natural linking to attach a Song to a particular album, you may want to look at
your Songs by genre instead. Since you may change your mind about how to
categorize a song, you probably want to use the more flexible relational linking.
Relational linking is slower that natural linking, because it has to match key values,
however, you can easily change the parent record to which any particular child record
belongs simply by changing the key value in the child. For example, if you create a
parent form and record definition called Genres (with a field named GenreName), you
can then add a field to Songs called Genre. When you create your subform, tell
Sesame that the relational link exists between Genres!GenreName and Songs!Genre.
When you view the Genres records, the Songs tagged "Jazz" will show up under the
Jazz record, the Songs tagged Classical will show up under the Classical record, and so
on.

Relational linking is even more flexible than a simple match between two fields. The
parents key field acts as a "Retrieve Spec" and can use the same syntax as the
retrieve form uses for that field type. You can use this capability to have a Song
appear under more than one Genre. If, instead of simply tagging a Song "Classical",
you tag it "Classical, Italian, Opera", then it can show up under three different Genre
records having the key values "..Classical..", "..Italian.." and "..Opera..", respectively.
(See Figure 6.) This way, you can use the same record for all three Genres, rather
than having to create three separate records. Also, because the same record appears
as a child under each parent, if you correct the spelling of the Song title in the record,
it will automatically appear correctly under each parent record. In most cases the key
field values should be generated by programming. In many cases they never need be
set visible to the user.

Figure 6. Relational linking allows the same record to appear under more than one parent
record.

525
APPENDIX 4 ADVANCED CONCEPTS

A simple way to understand the basic difference between relational and natural linking
is to imagine two families: the Nevilles and the Orvilles. The Nevilles all hold each
others hands. The Neville parents recognize their own children because they are
holding the eldest childs hand. The eldest child holds the next oldest childs hand, on
down the line of children to the youngest. The Nevilles are a naturally bound family.
The Orvilles are relational. The parent wears a tee shirt that says "Orville" on the
front. The children each have tee shirts that say "Orville" on the back. The parent
knows the children by matching the names on the tee shirts. (See Figure 7.)

Figure 7. Natural vs. relational Linking

Deciding whether to use natural or relational linking is simpler than understanding


either. Just ask yourself if the data in the subform you are designing will repeat,
unaltered, under more than one parent record. If the data will repeat, then it is wise to
use relational linking, otherwise, or if in doubt, use natural linking. If the data must be
unique to each parent, as in the example of logged transactions, natural linking is the
natural choice.

526
APPENDIX 4 ADVANCED CONCEPTS

Definitions summary

Form A collection of layout elements gathered under a single rectangular


component. A form knows what record definition (and thus what type of records)
to display. Forms live in the user interface.

Layout Element A display element (or "widget") that displays the contents of a
field (bound) or the result of a calculation (unbound). A bound layout element
knows what field definition defines the field value to display. A layout element is
contained by a form. Layout elements live in the user interface.

Subform A form that is placed on another form as a layout element. A subform


can be viewed as either a table or as a form. It can have natural or relational
linking to its parent form. Subforms live in the user interface.

Record A collection of fields, defined by a record definition. Records live in the


data engine.

Field The component of Sesame that can actually contain user data. It is
defined by a field definition. It is contained by a record. Fields live in the data
engine.

Record Definition The component of Sesame that contains field definitions. It


tells Sesame the type and composition of any record. Record definitions live in the
data engine.

Field Definition The component of Sesame that tells a field what type it is. It is
contained by a record definition. Field definitions live in the data engine.

Pipes and wires


Sesame is a client/server database manager. Usually that implies two or more
executables (.exe files), but that is not the case with Sesame. Sesame is built with a
client personality and a server personality in the same executable. You can tell
Sesame which personality to exhibit using start up flags:

sesame server MyComputer


tells Sesame to act like a server.

sesame client ServerName


tells Sesame to act like a client and connect to ServerName.

sesame
alone tells Sesame to start with the client behavior and the server behavior
integrated together in a one standalone executable.

527
APPENDIX 4 ADVANCED CONCEPTS

One of the most difficult aspects in writing a piece of software that must operate both
locally and through a network, is insulating the code from that difference in behavior.
To accomplish this, Sesame uses a set of "proxies" to allow the client or the server to
always act the same. A proxy is a component of the software that emulates something
else. If Sesame is running as a client through a network and is attached to a server,
there is a component on the client computer that is pretending to be the server. If you
run Sesame as a server, for each client actually connected through the network, there
is a proxy pretending to be that client running on the servers computer.

Running client/server vs. running standalone


The server never talks directly to the network, nor does the client. Instead they
always talk through a "pipe" to either a proxy or directly with one another. A pipe is a
piece of the computers memory, managed by the operating system, which allows
communication between two or more simultaneous tasks on the computer. Because
both the client and the server always talk to each other through pipes, neither ever
need know whether they are networked or not. The proxy tasks (if the system is
networked) manage the networking portion of Sesame.

If we were to follow a command (such as save a value) through the Sesame system
when a client is connected to a server through the network, it would take the following
steps:

1. Command originates on the client.


2. Command goes from the client to the "server proxy" on the client computer
through a pipe.
3. The server proxy passes the command through the network to the "client
proxy" on the server computer.
4. The client proxy passes the command to the server itself, through a pipe.
5. The server receives the command, executes it, and prepares a reply.
6. The reply is passed to the client proxy through a pipe.
7. The client proxy passes the reply through the network to the server proxy on
the client computer.
8. The server proxy passes the reply through a pipe to the actual Sesame client.
9. The Sesame client displays the results of the command on the screen.

As far as the client and the server are concerned, they talk to each other through the
pipe and are completely unaware of the intervening network. Figure 8 shows a
Sesame server with two Sesame clients connected. Figure 9 shows Sesame running
standalone, with the same machine acting as both server and client.

528
APPENDIX 4 ADVANCED CONCEPTS

Figure 8. Sesame server with two connected Sesame clients.

If Sesame is started without specifying any of the networking options via the startup
flags, the client and the server talk to each other directly through the same pipes
otherwise used to communicate with the proxies. This arrangement not only means
that neither the client nor the server ever have to be concerned with the network, it
also means that the network itself can be readily replaced with any other means of
communication simply by replacing the proxies for proxies that "speak" an
alternative protocol.

529
APPENDIX 4 ADVANCED CONCEPTS

Figure 9. Sesame running standalone on a single computer.

The only time the client or the server concern themselves with the network is during
startup and shutdown. When Sesame starts up it reads the startup flags and chooses
a single course of action depending on their state. If no startup flags are specified and
Sesame is running "standalone" (that is, all on one machine not client/server), the
server (or "data engine") starts first. If all is well, it then "spins off" the client thread.
A thread is a task that can run simultaneously with the process that started it. Pipes
are then established, so the server thread and the client thread can communicate. If
Sesame is started as a client and told to connect to a server on a different machine, it
starts by spinning off the server proxy thread. The server proxy thread attempts to
establish communications with the servers client thread across the network. If it can
establish network communications, it spins off the client thread and connects to it
using pipes. For each client that connects to the server, the server spins off another
client proxy.

When a command arrives at a networked server from any client, that command also
spins off an "execute thread" on the server. That way each client does not have to
wait for another clients command to finish executing before their command begins.
They both run simultaneously, sharing resources, including the CPU. If the server
machine is equipped with multiple CPUs, Sesame will take advantage of them, allowing
commands to run truly simultaneously. If the server machine only has one CPU, the
CPU is shared between execute threads in a round robin fashion, with each thread
receiving roughly equal time slices.

530
APPENDIX 4 ADVANCED CONCEPTS

The command protocol and the notification protocol


The protocol used by Sesame to communicate between client and server, whether
through a network or just through local pipes, is dual-fold. There is the command
protocol and the notification protocol. If you start Sesame using the flags for
networked client/server modes, and you are explicit about the port number to be used
(instead of using the default port numbers):

sesame server YourServerName:20011:20012

and

sesame client YourServerName:20011:20012

The first port is used for the command protocol. The second port is used for the
notification protocol.

The command protocol always originates on the client. The server cannot issue any
commands to the client. In that sense, the client drives Sesame. The command is
received by the server and queued with the other commands from other clients. The
communications engine on the server de-queues each command in the order in which
they arrived and hands that command to the data engine. The data engine spins off a
thread to execute that command. At the same time, the communications engine is de-
queuing the next command in line.

The command protocol is a "command and reply" type protocol. This means that every
time a client issues a command the server will reply to that command with data
results, a flag indicating success or failure, or an error message of some kind. The
client "waits" for that reply and cannot issue another command until that reply arrives.
A user level command, such as "Retrieve the records that match this Retrieve Spec
and sort them as specified", is actually issued as half a dozen (or so) smaller
commands. By breaking large commands down into many smaller component
commands, with replies, we prevent the client from waiting overly long and becoming
unresponsive to the user. In all, Sesames server responds to over 250 different low
level commands.

Notifications come solely from the server and can be sent to either an individual and
specific client, or broadcast to all of the clients at once. The notification protocol is a
"one-way" protocol. The server does not wait for the clients to reply. Most notifications
involve events that inform the user of an event on the server that was not originated
from that client. Specifically, the locking and unlocking of records by other clients, the
shutdown of the server, the closure of a shared database, or a catastrophic failure in
the data engine from which it cannot recover.

Encryption
With the exception of passwords, Sesame protocols are not encrypted. But because
Sesame communicates through ordinary TCP/IP network ports, it is quite possible for a
531
APPENDIX 4 ADVANCED CONCEPTS

network administrator to install SSL encryption/decryption on both the client


computers and the server. The SSL encryptor needs to intercept Sesames
communications at the port level, encrypt or decrypt as needed, and pass the data
through to Sesame, transparently. If secure communications or tunneling need be
used, it is the network administrators responsibility to install the appropriate software.

Delegation of labor
The client and the server both have jobs to do for the users. Largely, the server does
all of the work. (See Listing 1.) The client has a lot more fun. The client is concerned
primarily with providing a "window" a view, onto the data being managed by the
server. It also must be responsive to the input provided by the user interface (mouse
and keyboard) and translating the commands as issued by the user into commands
that the server can understand. It then sends those commands to the server and waits
for a reply. Once a reply comes in, the client must then display the results of the
command on the screen in a way the user can understand. The server receives
commands from one or more clients and opens database files, searches through data,
sorts, builds records, deletes records, modifies data, stores the forms, reports, and
specs and, of course, saves the results of these operations to the database files. If
multiple users open the same database file, the server does not load different copies
for each user, they share the same file. No two servers can access a Sesame database
file at the same time. If you wish to have multiple users use the same database files,
they must connect as clients to the same networked server.

The Sesame server is itself divided into two portions: the data engine and the
communications engine. The data engine manages the opening and closing of multiple
databases and applications. It performs the needed operations on the data, and saves
the results. The data engine performs nearly all of the file I/O operations in Sesame. It
is also in charge of managing the numerous "work threads" that run simultaneously to
create, edit, and delete records. The data engine keeps these work threads from
stepping on each others toes when trying to access the exact same data at the exact
same time.

The communications engine manages the multiple users connected to a Sesame


server. It spins off the client proxies on the server machine and communicates with
each one of them in turn. It receives the commands from the client proxies and
organizes them for the data engine. It also receives the results of the data engines
labor and passes that back to the appropriate child proxy for the client that issued that
command.

The client receives the forms, reports, and specs from the server. The server stores all
of the user defined Sesame components as records in the database file. It is the
clients job to determine the relationship between open forms, reports, and specs and
the data they display or manipulate. If, for example the user is using a retrieve spec,
the client receives the form (the user has selected) from the engine. It translates that
"form" into the layout elements that appear on the screen. The user types in the
retrieve spec and hits F10. The client gathers the specification from the layout
532
APPENDIX 4 ADVANCED CONCEPTS

elements and builds a "search command" for the engine to perform, including in that
command the name of the record definition attached to that form. The server uses
that record definition to determine which kind of records to search.

The client performs almost no data manipulation tasks, and therefore does not need to
be nearly as powerful a computer as the server. The one exception to this is SBasic
program execution. Almost all SBasic programs run on the client, not the server. That
is why SBasic programs use layout element names instead of field names. SBasic runs
on the client and has direct access to the form that generated the event (on enter, on
exit, on change, and so forth) that caused the execution to begin. That is how SBasic
programs can temporarily change the size, color, and position of layout elements.
SBasic can also change the data on a form without committing that data, if that is
desired. Again, this is only possible because the program is running on the client,
rather than directly changing the data on the server.

There is a single exception to this. Retrieve spec programming runs on the server. This
is because the retrieve itself is performed on the server. The limitations on SBasic
during retrieve spec program execution that the program consists entirely of an
expression, rather than statements, subroutines, declarations, or any other elements
prevents the server from attempting to alter a form or report while running. It also
means that you need to use Field Names in Retrieve spec programming whereas you
use layout element names universally elsewhere in Sesame programming.

Server Tasks Client Tasks


Managing database files User Interface
Storing all Sesame components SBasic program execution
Generation of reports
Retrieving Data (searching)
Sorting
Creation, deletion, and editing records
General file I/O
Managing multiple users / clients
Retrieve spec program execution
Printing

Listing 1. Delegation of tasks between Sesame components.

File pairings
The database files themselves are also divided. The .db/.dsr file contains only
structural components. It tells Sesame how the data is to be arranged what the
relationships are between the various records and record definitions. All the actual
data, the contents of the fields, and nothing else, is stored in the .dat/.ddt files. The
division between the Sesame runtime files (.db) and the Sesame Designer files allows
the application to be altered in the Sesame designer file while it is still in operation
and open by a Sesame server. It is only during the reconciliation step that an
application becomes the exclusive property of the Sesame Designer. When a .db file is
533
APPENDIX 4 ADVANCED CONCEPTS

opened by the Sesame server, it searches for the .dat file that matches the filename
specified, and merges the data in the .dat file with the structure found in the .db file.
Together, in memory, these two become a running application.

When changes are made to either the data (a field has been edited and the record
committed), or to the structure of a database (a record has been deleted or created),
the engine writes those changes out to the Sesame database file immediately.
Because such changes are interactive and must happen very quickly, it writes them in
a kind of "shorthand" notation. It isnt until the database file is reopened that the
changes are completely and seamlessly integrated into the file. You can see this occur
when the client informs the user that the database is being "optimized".

Operating system platforms


By separating the form from the records, Sesame provides a flexible form-based
design for the application developers. By separating the client and the server from the
network, Sesame becomes a flexible executable that can play either role (or both). By
separating the client from the server, and putting the bulk of the work on the server,
Sesames client can easily be replaced with a web front-end, or even a text-based
client. By separating the design files from the runtime files, Sesame allows a database
to evolve and change without having to come offline as it changes.

To continue the theme one step further, by separating Sesame as a whole from the
operating system on which it runs, we are able to produce Sesame for virtually any
modern operating system. This is done by putting a generic layer of code between
Sesame and the host operating system. In a sense, Sesame uses a "proxy" operating
system, which is always the same no matter what operating system is actually
running. Almost all of the operating system specific operations are done in this layer
and are thereby hidden from Sesame itself.

The user interface


The area where operating systems differ the most is in the user interface code. The
two user interfaces that Sesame currently uses is Win32 (the GUI provided by
Microsoft Windows 95, Microsoft Windows 98, Microsoft Windows NT, Microsoft
Windows 2000, Microsoft Windows ME, and Microsoft Windows XP) and X11 XWindows
(the GUI for all breeds of Linux). These two windowing systems are very different. X11
is a standards based GUI, provided originally by MIT. It has been implemented for
dozens of CPUs and architectures. It is completely independent of the operating
system on which it runs. There are versions of the X11 GUI for every breed of Unix
(there are over a hundred), VMS, Amiga, even Macintosh and Microsoft Windows.
XWindows has remained fairly stable over the last 20 years, with few innovations or
sudden changes in how it operates. Microsoft Windows, on the other hand, runs only
on a single architecture (generic Intel x86 / Pentium, though Microsoft Windows NT
was available, briefly, for DEC Alpha and some MIPS systems), is provided by a single
proprietary source (Microsoft), and conforms to few standards. Windows changes fairly
radically with nearly every release, offering a plethora of new features, while
discontinuing a number of others.
534
APPENDIX 4 ADVANCED CONCEPTS

Fortunately, there are several GUI toolkits that provide a unifying layer between
Windows and X11. The one used in Sesame is called FLTK. FLTK is an acronym for Fast
Light Toolkit. It is freely available at www.fltk.org and is protected by a modified GNU
Library license that provides for both commercial and non-commercial use. FLTK works
by using the underlying GUI to simply draw the window frame and read the mouse
and keyboard. It then uses the low level drawing routines of Microsoft Windows, X11,
or Macintosh to draw the "widgets" and other GUI elements. This ensures that they
appear identically on any of the supported operating systems. As far as Sesame is
concerned, it runs on FLTK, and it rarely needs to concern itself with whether the GUI
under FLTK is Windows or X11.

The hardware interfaces


Similar approaches were used for all of the "hardware" interfaces that are normally
accessed by using the operating system proprietary routines directly. Among these are
the network and printer interfaces. Operating system specific features, such as
internationalization, pipes, multithreading, and multiprocessing were similarly covered
with a generic layer. By doing so, we were able to develop Sesame simultaneously on
Windows and on Linux without any significant code changes. All of the interfaces used
by Sesame, not developed by Lantica are licensed with full source code, and so are not
subject to changes or discontinuations. Sesame is not a "port" (built on one O/S and
then rewritten on another). Sesame is precisely the same code, whether running on
Windows or Linux. This is true for all of the elements of Sesame, including Sesame
(the runtime executable), SDesigner, and the installation program. The only exception
is the ODBC driver, which does contain code specific to the Microsoft Windows
operating systems, and is unavailable on Linux.

Non-proprietary code and non-invasive installation


Beyond using "virtualizing" layers, Sesame also eschews the use of any code or
constructs that are only available on one operating system, or are specific to that
operating system. Sesame uses no DLL files that are not included with every Microsoft
Windows installation since Microsoft Windows 95. Sesame uses no DLLs that are not
required by Microsoft Windows for all Win32 executables. Sesame uses no registry
entries and makes none, nor changes any. Sesame does not require or rely on any
other specific programs or libraries. All of the libraries used by Sesame are included in
the Sesame executable. Sesame never has to look for custom libraries to dynamically
link to them. With the exception of the optional ODBC driver, Sesame comes with no
DLL files, no resource files, and no elements other than the executables themselves
that are required for proper execution.

Sesame does not use any proprietary interfaces. Proprietary interfaces limit the
lifespan of any program that uses them. Proprietary interfaces change, are replaced,
or are simply discontinued. All of the interfaces in Sesame were selected for their
proven stability, common sense approach, and adherence to widely accepted
standards.

535
APPENDIX 4 ADVANCED CONCEPTS

During operation Sesame does not create, delete, or attempt to manage directories. It
creates no temporary or hidden files. It does not require that it be placed in any one
particular directory. Nor does it require that its application files be placed in any
particular directory. While it does use defaults during installation, it will continue to
operate should the user or administrator move or rearrange things. When it is
necessary to limit Sesames access to specific directories, simple text files and
environment variables are used to tell Sesame where the files have gone. The number
and complexity of these external files is very low. The formats of these files comply
with the simplest and widest standards: ASCII and HTML. Even Sesames license file is
completely optional, though Sesame will only allow one client connection if it cannot
be found. And, while Sesame does require that the operating system provide a web
browser for report preview operations, it does not require that it be any particular
browser. Opera, Microsoft Internet Explorer, Netscape, Mozilla, or any other HTML 2.0
compliant browser is acceptable.

Future versions
By rigorously following this philosophy, Sesame will be able to move to additional
operating systems should the market demand and continue operation on Linux
and Microsoft Windows well into the foreseeable future. By being well insulated from
the host operating system, the network, even the printer interface, Sesame will be
able to adapt to changes in current technology and the introduction of new
technologies with aplomb. Additionally, because Sesame is self-contained and free of
external dependencies, entire product lines can be discontinued with no effect on
Sesames continued use and development.

536
Appendix 5
Sesame Utility Programs
Sesame comes with several utility programs, located in the Tools subdirectory of your
Sesame install directory. These programs are described as follows.

SUnlock
SUnlock (sunlock.exe) unlocks a locked application. An application is locked when it is
opened by Sesame. If the application is not properly closed due to a power failure or
other error, the application will remain locked and Sesame will be unable to reopen it.
In this case, SUnlock can be used to unlock the application. SUnlock should not be
used to unlock an application which is legitimately locked because it is in use.

Usage: sunlock filename

filename: The name of the application .db file to unlock. If the .db file is not located
in the current working directory, you must provide path to the .db file.

sunlock my_application.db
sunlock c:\sesame\data\my_application.db

SVersion
SVersion (s_version.exe) prints the internal version number and the lock status of an
application (.db file). Note that the version number returned is the internal structural
version number, not the release version number of the Sesame software itself. If you
contact Lantica Technical Support, they may request this version number.

Usage: s_version filename

filename: The name of the .db file to examine. If the .db file is not located in the
current working directory, you must provide the path to the .db file.

s_version my_application.db
s_version c:\sesame\data\my_application.db

Output:
VERSION NUMBER: 0.243000 LOCKED STATE: 1

537
Appendix 6
Sesame Shortcut Keys
Keystroke Module or Operation Description
F1 All Opens context sensitive help screens
F2 All Macro playback
Shift-F2 All Macro recording start/stop
F3 Add Data, Search Permanently deletes a record with user
Update, Table View confirmation.
F3 Retrieve Spec Clears the retrieve spec
Alt-F4 All Exit from active program Sesame,
Designer, table view, expanded field editor,
program editor, etc.
F5 Designer Property Editor, Fills in Current values for certain layout
Report Writer Property element settings such as Label, Name,
Editor Initial Value, Restrict values, tooltip,
Custom Help.
F5 Add Data, Search Dittos (copies) into the current field the
Update, Table View value of the same field from the record last
entered.
Shift-F5 Add Data, Search Dittos (copies) a whole record. It
Update, Table View overwrites the entire current record with
the record last entered (with user
confirmation).
Ctrl-F5 Add Data, Search Inserts the current date into the selected
Update, Table View field.
Alt-F5 Add Data, Search Inserts the current time into the selected
Update, Table View field.
F6 Add Data, Search Opens expanded field editor. Closes
Update, Table View, expanded field editor, saving changes, if it
Designer Property Editor, is already open.
Report Writer Property
Editor
Shift-F6 Add Data, Search Update Opens current result set in table view
Ctrl-F6 Search Update Switches from Update to Add mode

539
APPENDIX 6 SHORTCUT KEYS

Keystroke Module or Operation Description


F7 Add Data Switches to Search/Update window if one
is open; otherwise switches to Search
specification screen. Current Add record is
left open and unsaved.
F7 Search Update Returns to search retrieve spec. Does not
automatically save record.
Shift-F7 Search Update, Table Undo current record. Restores the record
View back to the state it was in when you
opened it.
Ctrl-F7 Search Update, Table Undo current Field. Restores the field back
View to the state it was in when you opened the
record.
F8 Add Data, Search Forces all On-Form-Change programming
Update, Table View to calculate.
F9 Add Data, Search Saves and moves from current record to
Update, Table View previous record. In a subform moves to
previous record in same subform
Ctrl-F9 Add Data, Search Saves and moves to previous record. In a
Update, Table View subform, saves changes to main form and
subform and moves to the previous main
form record.
F10 Add Data, Search Saves and moves to next record. If on the
Update, Table View last record of the result set, or last record
in a subform, moves to a new blank record.
Shift-F10 Add Data, Search Update Saves record, and subform if any, and
closes form.
Ctrl-F10 Add Data, Search Update Saves and moves to next record. In a
subform, saves changes to main form and
subform and moves to the next main form
record. If on the last record of the result
set, moves to a new blank main record.
F11 Add Data, Search Update Copies current record to buffer.
Shift-F11 Add Data, Search Update Pastes values in buffer to current record.
Ctrl-F11 Add Data, Search Update Copies entire current result set to buffer.
Alt-F11 Add Data, Search Update Pastes records in buffer to result set,
creating new records.

540
Appendix 7
Sesame Initialization File - sesame.ini
Sesame Initialization File

The Sesame initialization file provides a way for you to specify how Sesame looks and
behaves. It is typically named "sesame.ini". Sesame.ini is not required. If this ini file
does not exist, Sesame will use default settings.

Creating a Sesame.ini file


You can create a Sesame initialization file in these ways ..

 You can create one from scratch, using Notepad or any other text editor. It
must be saved with the name sesame.ini and stored in the current working
directory (normally \Sesame2).

 There is a sample file supplied with Sesame. You will find it in \Sesame.
Rename it from Sample.ini to Sesame.ini. This file contains a selection of the
more popular commands that you might like to alter as you wish.

 Sesame Designer can generate a comprehensive Sesame.ini file with all your
current settings. Select Save Global Settings from Designer's File menu.

Figure 1. To store current settings in an ini file.

The first time you use Save Global Settingsyou will see the message box shown in
Figure 2 below. If you repeat using Save Global Settings you will be asked to confirm
that you want to overwrite the .ini file.

The file created is automatically named Sesame.ini.

541
APPENDIX 7 SESAME.INI FILE

Figure 2. Confirmation that Sesame.ini file has been created.

Warning! The .ini file generated this way will contain a large number of settings.
Some of these are fairly obscure. Some of them, if modified, might make Sesame
work in unfamiliar ways, so take care. You are advised to alter only those settings you
are familiar with. It is safer to start with the sample ini file provided and modify that to
your requirements.

Sesame.ini is read at program startup by the server, the client, and in standalone
mode. Each mode will use only the settings appropriate to that mode. For example, a
Server will not use the BACKGROUND COLOR setting. It needs to appear in the current
working directory (Start In directory) unless the "-ini_file" startup flag is used or the
SESAME_INI_FILE environment variable is set. Settings in the sesame.ini file override
their matching startup switches.

The sesame.ini file is comprised of "commands" that tell Sesame how to behave. Lines
beginning with a hash mark (#) are treated as comments. Any line that is not
recognized as a command or comment is ignored. Commands must be placed in the
file with one command per line in the following format:
COMMAND: VALUE

Look and Feel Commands


If not otherwise noted, settings controlled by the Look and Feel commands default to
system settings, if not overridden in the ini file.

BACKGROUND COLOR: Sets the primary background color of Sesame windows to the
RGB value following the command. This setting affects the background color of many
Sesame screen elements, such as toolbars, message boxes and scrollbars. This setting
has no effect on user-defined Forms.
Example: BACKGROUND COLOR: 255 0 0

SECONDARY BACKGROUND COLOR: Sets the secondary background color of Sesame


windows to the RGB value following the command. This setting affects the background
color of many Sesame screen elements, such as command trees and text boxes. This
setting has no effect on user-defined Forms.
Example: SECONDARY BACKGROUND COLOR: 0 255 0

542
APPENDIX 7 SESAME.INI FILE

FOREGROUND COLOR: Sets the foreground color used by Sesame windows to the RGB
value following the command. This setting affects the foreground color of many
Sesame screen elements, such as text and labels. This setting has no effect on user-
defined Forms.
Example: FOREGROUND COLOR: 255 255 0

MENU FONT: Sets the primary font face used by Sesame screen elements such as
menus and dialog boxes. This setting has no effect on user-defined Forms.
Example: MENU FONT: Courier New

MENU FONT SIZE: Sets the size in pixels of the primary font used by Sesame screen
elements such as menus and dialog boxes. This setting may be ignored or limited for
screen elements with limited space. This setting has no effect on user-defined Forms.
Example: MENU FONT SIZE: 10

SECONDARY FONT: Sets the secondary font face used by Sesame screen elements
such as status bars. This setting has no effect on user-defined Forms.
Example: SECONDARY FONT: Courier New

SECONDARY FONT SIZE: Sets the size in pixels of the secondary font used by Sesame
screen elements such as status bars. This setting may be ignored or limited for screen
elements with limited space. This setting has no effect on user-defined Forms.
Example: SECONDARY FONT SIZE: 10

PROGRAM EDITOR FONT SIZE: Sets the size in pixels of the font used for code typed
into the Sesame Program Editor. Valid settings are 4 to 42.
Example: PROGRAM EDITOR FONT SIZE: 16

SCHEME: Sets the overall visual theme used by Sesame. The scheme affects the look
of all screen elements including those on user-defined Forms. The scheme can also be
set using the scheme startup switch. Available schemes are:
Plastic A highly stylized theme with rounded edges and softened colors.
Clean A crisp theme with minimal decoration.
Gradient All backgrounds are drawn as gradients of their background color.
Ghost Gradient theme that grades to lightened background colors.
Image Specifies an image to use as the background for all screen elements. The
path and filename of the image must be supplied.
SCHEME: image:\ImagePath\ImageName.jpg
Example: SCHEME: Plastic

SPLASH IMAGE: Replaces the usual Sesame splash image with the image specified in
Runtime and Preview modes. The SDesigner splash image is not replaced. The path
and filename of the image must be supplied. Same as using the splash startup
switch.
Example: SPLASH IMAGE: \ImagePath\ImageName.jpg
Default: Sesame Logo
543
APPENDIX 7 SESAME.INI FILE

SYNTAX HIGHLIGHT: Sets whether syntax highlighting is on by default for the


Programming Editor. This affects all Programming Editors both in Runtime and in
SDesigner. Valid settings are ON and OFF.
Example: SYNTAX HIGHLIGHT: ON
Default: OFF

Window Property Commands


COMMAND AREA WIDTH: Specifies the initial width of the Command Area where the
Command Trees and Spec Window appear. Set the command value to a number of
pixels or CLOSED. If CLOSED is used, users will not be able to open the Command
Area.
Example: COMMAND AREA WIDTH: 250
Default: 250

COMMAND TREE HEIGHT: Specifies how much of the Command Area is used by the
Command Tree. The remainder will be used by the Spec Window. Set the command
value to a number of pixels or CLOSED. If CLOSED is used, users will not be able to
open the Command Tree.
Example: COMMAND TREE HEIGHT: 200
Default: 300

COMMAND TREE MODE: Sets the mode of the Command Tree. Valid settings are
SINGLE and FULL. SINGLE shows only one level or "branch" of commands at a time.
FULL shows the entire command tree allowing branches of commands to be opened
and closed as needed. Use of SINGLE mode will not interfere with the use of the
@SelectTreeItem SBasic command. SINGLE is the same as using the single_level
startup switch.
Example: COMMAND TREE MODE: SINGLE
Default: FULL

FIELD EDITOR HEIGHT: Sets the initial height in pixels of the F6 Field Editor.
Example: FIELD EDITOR HEIGHT: 300
Default: 300

FIELD EDITOR WIDTH: Sets the initial width in pixels of the F6 Field Editor.
Example: FIELD EDITOR WIDTH: 300
Default: 400

FIELD EDITOR WORD WRAP: Sets word wrap behavior for the F6 Field Editor. Valid
settings are ON and OFF.
Example: FIELD EDITOR WORD WRAP: OFF
Default: ON

HEIGHT: Sets the initial height in pixels of the Sesame window.


Example: HEIGHT: 600
544
APPENDIX 7 SESAME.INI FILE

Default: 545

WIDTH: Sets the initial width in pixels of the Sesame window.


Example: WIDTH: 800
Default: 790

X: Sets the initial distance in pixels of the left edge Sesame window from the left edge
of the screen.
Example: X: 100
No Default

Y: Sets the initial distance in pixels of the top edge Sesame window from the top edge
of the screen.
Example: Y: 50
No Default

TABLE ROW HEADER WIDTH: Sets the width in pixels of the record number column
appearing in Table View and Table View subforms.
Example: TABLE ROW HEADER WIDTH: 50
Default: 70

Client Behavior Commands


BLINK: Turns cursor blinking on or off. Valid settings are ON and OFF. ON is the same
as using the blink startup switch.
Example: BLINK: OFF
Default: OFF

DEFAULT SEARCH SYNTAX: Sets whether the default search syntax is Q&A compatible
syntax or regular expression syntax. This default controls how search language is
interpreted when not specified with qanda() or regex(). The default is used wherever
search syntax can be used, including Retrieve Specs and X-Commands. Valid settings
are Q&A and REGEX.
Example: DEFAULT SEARCH SYNTAX: REGEX
Default: Q&A

EMBED DIALOGS: Causes most dialog boxes to appear in the main window instead of
creating a popup window. Valid settings are ON and OFF. ON is the same as using the
embed_dialogs startup switch.
Example: EMBED DIALOGS: ON
Default: OFF

MERGE FILE PRINT PATH: Setting this command causes the Merge File Print tree
commands to create a file on the Client instead of sending the merge results directly
to the printer. This allows for post-processing of Merge File Print results or use of a
third-party print spooler.
Example: MERGE FILE PRINT PATH: \MyMerges\lastmerge.rtf
545
APPENDIX 7 SESAME.INI FILE

No Default

PAUSE MACRO: Pauses a macro that is playing back whenever an alert appears,
allowing the user (as opposed to the macro) to "answer" the alert. Valid settings are
ON and OFF.
Example: PAUSE MACRO: ON
Default: OFF

PROGRESS POPUP: Causes progress meters in Runtime to also appear in a popup


window instead of only displaying in the Mode indicator. Valid settings are ON and
OFF.
Example: PROGRESS POPUP: ON
Default: OFF

QUICK START: Sets the initial state of the Quick Start menu. Valid settings are ON,
OFF and DISABLED. ON starts with the Quick Start menu visible and is the same as
using the quick_start startup switch. DISABLED prevents users from launching the
Quick Start menu after start up.
Example: QUICK START: ON
Default: OFF

RECENT FILE FILENAME: Sets the filename where Sesame looks for the recently used
file list.
Example: RECENT FILE FILENAME: my_recent_files.txt
Default: sesame_recent_files.txt

RUN UNIVERSAL ON MOVE: Sets whether SBasic code in the Universal event runs on
mouse movement events. As mouse movement events occur constantly, and are
usually not of consequence to normal operations, this setting is OFF by default. Valid
settings are ON and OFF.
Example: RUN UNIVERSAL ON MOVE: ON
Default: OFF

START FORM: Replaces the Sesame logo and content that appears beside the
Application Menu with the specified user-defined Form. The Start Form cannot be used
to save or edit records, but it can contain logos and application information. It can also
run SBasic, so it can be used as a custom menu for your Application. Same as using
the start_form startup switch.
Example: START FORM: My Custom Menu
No Default

TRANSLATE: The TRANSLATE command is followed by two pieces of text. Wherever


Sesame would normally draw the first piece of text on screen, it draws the second
piece instead. This is like using the @AddToTranslationTable command in SBasic. You
can have as many TRANSLATE lines in the sesame.ini file as are needed. Both pieces
of text must be enclosed in quotes.
546
APPENDIX 7 SESAME.INI FILE

Example: TRANSLATE: "Yes" "Ja"


No Default

USER PARAM: Allows Sesame to collect custom information from the initialization file
on startup which can then be retrieved in SBasic using @UserParameter. This
command is followed by text no longer than 1024 bytes. That is the text returned by
@UserParameter. You can have as many USER PARAM lines in the sesame.ini file as
are needed. The indexes for @UserParameter respect the order the USER PARAM
commands appear in the sesame.ini file. The first USER PARAM command would be
index 1, the second 2, etc. Same as using the user_param startup switch.
Example: USER PARAM: Lantica
No Default

VISUAL LOG: Sets whether Q&A Translation shows a progress log during the
translation process. Valid settings are ON and OFF. ON is the same as using the
visual_log startup switch.
Example: VISUAL LOG: OFF
Default: OFF

VISUAL UPDATE: Sets whether macros update the screen while running. Valid settings
are ON and OFF. OFF is the same as using the novisualupdate startup switch.
Example: VISUAL UPDATE: ON
Default: ON

WARNING LEVEL: Sets the level at which warning messages appear based on user
actions such as deleting records, entering values not matching data type, etc. Valid
settings are OFF, MEDIUM and HIGH. MEDIUM is the default. OFF is the same as using
the warn_none startup switch. HIGH is the same as using the warn_high startup
switch.
Example: WARNING LEVEL: MEDIUM
Default: MEDIUM

Server Behavior Commands


BACKUP ON LOAD: Causes Sesame to automatically backup an application just after
loading it. A directory is created (if none exists) in the current working directory that is
named after the application file. The backup files are copies of the application files with
a timestamp embedded as part of the filename. Valid settings are ON and OFF.
Example: BACKUP ON LOAD: ON
Default: OFF

BACKUP ON SAVE: Causes Sesame to automatically backup an application just before


any changes are written to disk. A directory is created (if none exists) in the current
working directory that is named after the application file. The backup files are copies
of the application files with a timestamp embedded as part of the filename. Valid
settings are ON and OFF. Note that this will create a backup before every change. If

547
APPENDIX 7 SESAME.INI FILE

your database is changed often, this will use up a lot of disk space and system
resources.
Example: BACKUP ON SAVE: ON
Default: OFF

BACKUP ON INTERVAL: Causes Sesame Server to automatically backup an application


at an interval of the specified number of seconds. A directory is created (if none
exists) in the current working directory that is named after the application file. The
backup files are copies of the application files with a timestamp embedded as part of
the filename. A backup is only made if changes have been made within the past
interval. This command has no effect if running standalone or in daemon mode.
Example: BACKUP ON INTERVAL: 3600
Default: 0

DATABASE RETENTION: Database retention determines if an application remains


loaded on the server even after there are no more clients accessing that application.
This allows an administrator to preload a set of databases, making subsequent loading
unneeded, both for normal use and for X-Commands. Valid settings are ON and OFF.
ON is the same as using the keep startup switch.
Example: DATABASE RETENTION: ON
Default: OFF

EXPLICIT SAVE ONLY: Normally, Sesame saves changes to disk as those changes
occur. This command causes Sesame to only save to disk when explicitly told to do so
using the Save button on the toolbar. This is a dangerous option in that if you make
changes and do not click the Save button before closing the application, the changes
will be lost Valid settings are ON and OFF.
Example: EXPLICIT SAVE ONLY: ON
Default: OFF

LOAD DATA ON REDESIGN: Sets whether Sesame includes user data when making a
dsr out of an existing db. Valid settings are ON and OFF.
Example: LOAD DATA ON REDESIGN: OFF
Default: ON

SERVER PREINDEX XLOOKUPS: Tells the Sesame server whether to optimize the
speed of X-Commands using a preindexing scheme. This command is best used in
situations where there are repeated lookups being made to an external database with
fairly static data. This optimization will only affect X-Commands where the Key value
contains no search characters. Valid settings are ON and OFF.
Example: SERVER PREINDEX XLOOKUPS: ON
Default: OFF

SERVER THREADS: Sesame Server is by default a multithreaded executable. Each


time a command arrives from a Client, Sesame Server creates a new thread to
execute that command. A thread is like a little tiny program that can run at the same
548
APPENDIX 7 SESAME.INI FILE

time as the main program. If you have just one processor, the main program and all
of its threads "round robin" where each of them get a small slice of CPU time
in their turn. If you have a multicore CPU or multiple CPUs, as many threads as you
have CPUs will all run at once. SERVER THREADS is ON by default if running in
client/server mode. It is OFF by default if running standalone. Valid settings are ON
and OFF.

There are two reasons to turn SERVER THREADS OFF on a multi-user client/server
setup. Turning it off will improve reliability. Multithreading is inherently complicated
and can lead to a condition known as memory contention, where two or more threads
are trying to read/write the same piece of memory at the same time. It is very
unlikely this will occur. The other reason is to preserve resources for other programs
you may want to run at the same time as Sesame. Keeping one or more CPUs
unoccupied will make the other programs appear to be more "snappy."

The main reason to leave this option ON is speed, especially if you have more than
one CPU or a multicore CPU. Sesame is an efficient multithreader. Sesame averages
close to a 1.8 speed increase and can exceed 1.95 with the right combination of
commands being executed.
Example: SERVER THREADS: OFF
Default: Depends on mode. See above.

SDesigner Commands
SNAP TO GRID: Sets the default state of Snap To Grid in Form Design Mode. Valid
settings are ON and OFF.
Example: SNAP TO GRID: ON
Default: OFF

GRID HEIGHT: Sets the default height in pixels of each snap-to-grid unit in Form
Design Mode.
Example: GRID HEIGHT: 10
Default: 0

GRID WIDTH: Sets the default width in pixels of each snap-to-grid unit in Form Design
Mode.
Example: GRID WIDTH: 10
Default: 0

HORIZONTAL SCOOTING: Sets the default state of Horizontal Scoot Mode in Form
Design Mode. Valid settings are ON and OFF.
Example: HORIZONTAL SCOOTING: ON
Default: OFF

VERTICAL SCOOTING: Sets the default state of Vertical Scoot Mode in Form Design
Mode. Valid settings are ON and OFF.
Example: VERTICAL SCOOTING: ON
549
APPENDIX 7 SESAME.INI FILE

Default: OFF

SCOOT MARGIN: Sets the default margin in pixels to trigger scooting in Form Design
Mode.
Example: SCOOT MARGIN: 8
Default: 4

Security Commands
PASSWORD MINIMUM LENGTH: Sets the minimum length in characters required for
newly added or changed passwords. Existing passwords are not affected.
Example: PASSWORD MINIMUM LENGTH: 8
No default

PASSWORD MUST CONTAIN NONALPHA: Sets whether at least one non-alpha


character is required for newly added or changed passwords. Existing passwords are
not affected. Valid settings are ON and OFF. ON requires at least one non-alpha
character.
Example: PASSWORD MUST CONTAIN NONALPHA: ON
No Default

Mode Commands
SERVER DAEMON MODE: Sets whether Sesame Server runs as a daemon. Daemon
mode is for use when running Sesame as a service or daemon, in which case it would
usually be started as part of booting the server computer. Typically services cannot
have graphical user interfaces. Daemon mode removes the server's user interface.
Valid settings are ON and OFF. ON is the same as using the daemon startup switch.
Example: SERVER DAEMON MODE: ON
Default: OFF

KIOSK MODE: Kiosk mode forces Sesame to run full screen, removes all window
decorations, all pulldown menus, and toolbar buttons. Kiosk mode makes it impossible
for the user to shutdown Sesame, choose a new application, or in any way interfere
with Sesame being ready for the next user at the kiosk. This mode is not appropriate
for anything other than a true kiosk environment. Ordinary applications should never
be run in kiosk mode. Valid settings are ON and OFF. ON is the same as using the
kiosk startup switch.
Example: KIOSK MODE: ON
Default: OFF

Memory Menu Commands


REMEMBER ON BROWSE: Causes elements that have a Memory Menu to place their
values on their Memory Menu as you browse records. Normally, values are only added
to the Memory Menu when changed. This prepopulates the Memory Menus with
common values. Valid settings are ON and OFF.
Example: REMEMBER ON BROWSE: ON
Default: OFF
550
APPENDIX 7 SESAME.INI FILE

DEFAULT MEMORY MENU LIMIT: Sets the default number of items that can appear on
any one Memory Menu.
Example: DEFAULT MEMORY MENU LIMIT: 20
Default: 10

Email Commands
A Sesame Client has the ability to poll a specified email account, retrieve emails sent
to that account, and automatically respond with information from an application. The
commands in this section control the behavior of this feature. It is best to use a
dedicated Sesame Client for automatic email polling.

Unless specified, these commands have no defaults.

EMAIL COMMANDS: Enables/disables automatic polling of the email account. Valid


settings are ON and OFF.
Example: EMAIL COMMANDS: ON
Default: OFF

EMAIL COMMANDS POP3 SERVER: POP3 server to poll.


Example: EMAIL COMMANDS POP3 SERVER: mail.yourmailserver.net

EMAIL COMMANDS POP3 LOGIN: Login name for the email account to poll
Example: EMAIL COMMANDS POP3 LOGIN: queries

EMAIL COMMANDS POP3 PASSWORD: Password for the email account to poll
Example: EMAIL COMMANDS POP3 PASSWORD: abc/123

EMAIL COMMANDS DELETE READ: Sets whether collected emails are deleted from the
mail server. Valid settings are ON and OFF. ON deletes collected messages. OFF leaves
messages on the mail server.
Example: EMAIL COMMANDS DELETE READ: OFF
Default: OFF

EMAIL COMMANDS POLL INTERVAL: Interval at which to poll the specified email
account in number of seconds.
Example: EMAIL COMMANDS POLL INTERVAL: 600
Default: 30

EMAIL COMMANDS SMTP SERVER: Outgoing SMTP server to use for replies.
Example: EMAIL COMMANDS SMTP SERVER: outgoing.yourmailserver.net

EMAIL COMMANDS SMTP LOGIN: Login name for the outgoing server (not needed for
all outgoing mail servers).
Example: EMAIL COMMANDS SMTP LOGIN: replies

551
APPENDIX 7 SESAME.INI FILE

EMAIL COMMANDS SMTP PASSWORD: Password for the outgoing server (not needed
for all outgoing mail servers).
Example: EMAIL COMMANDS SMTP PASSWORD: 123/abc

EMAIL COMMANDS LOCAL PASSWORD: Password that must be supplied in emailed


requests for information. If this command is used, all emailed requests must include
this password. It is recommended that you use this command to set a local password.
If you do not use this command, Sesame will respond to all emailed requests.
Example: EMAIL COMMANDS LOCAL PASSWORD: a12/3bc

Usage Example for Email Commands

If your sesame.ini file contains the following commands ...


EMAIL COMMANDS: ON
EMAIL COMMANDS POP3 SERVER: mail.yourmailserver.net
EMAIL COMMANDS POP3 LOGIN: queries
EMAIL COMMANDS POP3 PASSWORD: abc/123
EMAIL COMMANDS DELETE READ: ON
EMAIL COMMANDS POLL INTERVAL: 60
EMAIL COMMANDS SMTP SERVER: outgoing.yourmailserver.net
EMAIL COMMANDS SMTP LOGIN: replies
EMAIL COMMANDS SMTP PASSWORD: 123/abc
EMAIL COMMANDS LOCAL PASSWORD: a12/3bc

... your client could send an email like the one below to queries@yourmailserver.net ...
SCommand Open: Customers.db
SCommand Database: Customers
SCommand Query: !Key=<1000
SCommand Report: MyReport
SCommand Reply To: client@thecustomer.com
SCommand Password: a12/3bc

... and within 60 seconds Sesame will collect the request and send a copy of MyReport
from the Customers database showing records with Key values of less than 1000 to
their email address of client@thecustomer.com.

SCommands included in an email, like the one shown above, must appear in the email
with one command per line in the following format:
SCommand: Value

SCommands
SCommand Open: The name of the application file including extension to open. This
file must be available to the Sesame Server.
Example: SCommand Open: Customers.db

552
APPENDIX 7 SESAME.INI FILE

SCommand Database: The name of a database within the application specified by


SCommand Open.
Example: SCommand Database: Customers

SCommand Query: Criteria for which records should appear in the report. You can
include as many SCommand Query lines as needed. Each line represents what would
be typed in one field of a Retrieve Spec. Query values must be formatted as follows:
!FieldName=Criteria
Example: SCommand Query: !Key=<1000

SCommand Report: The name of a report within the application specified by


SCommand Open and attached to the database specified by SCommand Database.
Example: SCommand Report: MyReport

SCommand Reply To: Email address where the report will be sent.
Example: SCommand Reply To: client@thecustomer.com

SCommand Password: Password to allow the request to be processed. This must


match the value specified by the EMAIL COMMANDS LOCAL PASSWORD command in
the sesame.ini file.
Example: SCommand Password: a12/3bc

553
Appendix 8
Startup Switches
Sesame can be run from a command prompt or its shortcut can be changed to include
startup switches:

Syntax:

Syntax:
sesame [-macro <macro_file.mac>] [-server <server_name[:port1][:port2]>] [-client
<server_name[:port1][:port2]>] [-admin <server_name[:port1][:port2]>] [-command
<server_name[:port1][:port2]> <password> <SHUTDOWN | SUSPEND | CONTINUE>] [-
qa <qa_file.dtf>] [-closed] [-splash <image_file<.bmp|.jpg|.png|.gif>>] [-scheme
<scheme_name>] [-ini_file filename.ini] [-blink] [-novisualupdate] [-no_startup_program] [-
help] [-daemon] [-keep] [-start_form <form_name>] [-kiosk] [-warn_high] [-warn_none] [-
quick_start] [-raw_data] [-embed_dialogs] [-user_param <param>] [-web_server <port>] [-
system_id <id str>] [-reconcile | -reconcile_confirm <sesame_database.db> <options>
<sesame_designer_file.dsr>] [sesame_database.db] [sesame_design_file.dsr]

Items in "[ ... ]" are optional and may appear in any order. Items in "< ... >" are
required arguments and must immediately follow their command.

Usage:

-client server_name[:port_no1][:port_no2]
This command starts a Sesame client on the local machine and connects it to the
Sesame server already running on the remote machine using the ports specified. The
port numbers must match those used when starting the Sesame server, and must be
open ports not used by any other program on either machine.

-closed
The "-closed" command causes the command panel to be closed when the Sesame
client starts.

-help
Displays help on startup switches then starts Sesame.

-macro macro_file.mac
This command causes a macro file to be loaded and run during client startup.

-server server_name[:port_no1][:port_no2]
This command starts a Sesame server on the local machine using the ports specified.
The same port numbers will be used when starting Sesame clients, and must be open
ports not used by any other program.
555
APPENDIX 8 STARTUP SWITCHES

-splash image_file[.jpg|.bmp|.png]
This command replaces the usual splash screen with the image supplied in the image
file. The image file must be a jpeg, bmp, or png type image.

-scheme scheme_name
This command changes the look of sesame to the specified scheme.

-blink
This command turns on cursor blinking.

-warn_none
This command turns off all warnings, including restriction warnings, record deletion,
etc...

-warn_high
This command turns on additional warnings, including strict field conversion warnings.

-daemon
This command causes the server to run without a user interface (console window).

-kiosk
Kiosk mode forces Sesame to run full screen, removes all window decorations, all
pulldown menus, and toolbar buttons. Kiosk mode makes it impossible for the user to
shutdown Sesame, choose a new application, or in any way interfere with Sesame
being ready for the next user at the kiosk. This mode is not appropriate for anything
other than a true kiosk environment. Ordinary applications should never be run in
kiosk mode.

-admin server_name[:port1:[port2]
Brings up an Admin Client that does not use up a connection to the server. Only the
Server Administration window appears as the Client.

-command server_name admin_password command


Issues a special admin command to the specified Server. Available commands:
SUSPEND: Causes the Server to stop processing Client commands until it
receives a CONTINUE command. SUSPEND will cause any clients that are
connected to appear to be locked up, until CONTINUE is sent. SUSPEND
retains pending Client commands and may use a fair amount of memory if
there are a lot of suspended Clients. Never suspend indefinitely.
CONTINUE: Instructs the Server to resume from the last SUSPEND command.
Any pending Client commands received while in SUSPEND are processed.
SHUTDOWN: Shuts down the Server. This will disconnect any connected
clients without notification.

556
APPENDIX 8 STARTUP SWITCHES

-embed_dialogs
Causes most dialog boxes to appear in the main window instead of creating a popup
window. Same as EMBED_DIALOGS: ON in the sesame,ini file.

-keep
Keeps an application loaded on the server even after there are no more clients
accessing that application. This allows an administrator to preload a set of databases,
making subsequent loading unneeded, both for normal use and for X-Commands.
Same as DATABASE RETENTION: ON in the sesame,ini file.

-ini_file filepath
Tells Sesame to read settings from the specified ini file.

-quick_start
Starts Sesame with the Quick Start menu visible. Same as QUICK START: ON in the
sesame,ini file.

-raw_data
Diagnostic tool that turns off all data formatting. This causes the data to appear in a
raw unformatted state. For example, dates will appear as YYYY/MM/DD.

-scheme scheme_name
Sets the overall visual theme used by Sesame. The scheme affects the look of all
screen elements including those on user-defined Forms. Same as SCHEME:
scheme_name in the sesame,ini file. Available schemes are:
Plastic A highly stylized theme with rounded edges and softened colors.
Clean A crisp theme with minimal decoration.
Gradient All backgrounds are drawn as gradients of their background color.
Ghost Gradient theme that grades to lightened background colors.
Image Specifies an image to use as the background for all screen elements.
The path and filename of the image must be supplied.
image:\ImagePath\ImageName.jpg

-single_level
Shows only one level or "branch" of the Command Tree commands at a time. Same as
COMMAND TREE MODE: SINGLE in the sesame,ini file.

-start_form
Replaces the Sesame logo and content that appears beside the Application Menu with
the specified user-defined Form. The Start Form cannot be used to save or edit
records, but it can contain logos and application information. It can also run SBasic, so
it can be used as a custom menu for your Application. Same as START FORM:
FormName in the sesame,ini file.

557
APPENDIX 8 STARTUP SWITCHES

-user_param
Allows Sesame to collect custom information from the initialization file on startup
which can then be retrieved in SBasic using @UserParameter. This switch is followed
by text no longer than 1024 bytes. That is the text returned by @UserParameter. You
can have as many user_param switches as are needed. The indexes for
@UserParameter respect the order the switches appear on the command line. The first
user_param would be index 1, the second 2, etc. Same as USER PARAM: Value in the
sesame,ini file. See @UserParameter in the Sesame Programming Guide for examples
of using these values.

-visual_log
Causes Q&A Translation to show a progress log during the translation process. Same
as VISUAL LOG: ON in the sesame,ini file.

-web_server
Enables the built-in web server. Complete documentation for the built-in web server is
available in the Sesame User Guide.

-reconcile | -reconcile_confirm <sesame_database.db options


sesame_designer_file.dsr>
Causes Sesame to reconcile the .db file against the .dsr using the options "nnnn". The
options are a combination of "N" and "Y" with four positions. Each position is a
reconcile option:

1: Auto delete unused field definitions


2: Keep @number value
3: Keep global values
4: Keep specs
5: Keep Security

Example:
sesame -reconcile Clients.db NYYNY Another.dsr
.. will reconcile Clients.db against Another.dsr, but will keep the @number value, the
global values, and the security that are in Clients.db.

-novisualupdate
Causes macro visibility to be set off as default

-no_startup_program
Allows bypass of the On Application Open event

558
APPENDIX 8 STARTUP SWITCHES

-system_id <id str>


Allows a system id to be passed from the client to the server and appears in the admin
interface for use with systems like Citrix where all of the clients come in from the
same IP address and need to be distinguished by the admin.
This switch can also be used to show a 'user-friendly' identity to network users. When
a user on a network encounters a record which is locked by another user, the
system_id switch appends the ID String to the computer name. For example If the ID
string supplied is "Bill" for example, the message could read, instead of just the
anonymous computer name. . .

"This form is currently locked by another user on ADM82 Bill."

Examples:
------------
To start Sesame and automatically open an application named "client_list.db":
sesame client_list.db

To open an application named "client_list.db" and run a macro file named


"my_macro.mac" immediately:
sesame client_list.db -macro my_macro.mac

To start a sesame server on a machine named "Cruncher":


sesame -server Cruncher

To start a sesame client that connects to the server running on "Cruncher":


sesame -client Cruncher

To start a sesame client that connects to the server running on "SERV01", using the
ID "Hazel" on this client PC, and opening Countries.db (which is in the Data\Samples
folder) automatically:

sesame-clientSERV01-system_idHAZELData\Samples\Countries.db

(The symbol is used to indicate a space.)

559
Index

! (mandatory restriction), 126, 142 Administrator, security, 435


.DAT (File extension), 23 Advance Record, 50
.DB (File extension), 23 Advanced Concepts, 519
.DSR (File extension), 23 Advanced Element Selector Control Panel,
.DDT (File extension), 23 131
.DSR (File extension), 62 Advanced searches, 259
.DSR (File extension), 63 Advanced Undo, 153
.DB (File extension), 63 Aligning layout elements, example, 181
.DSR (File extension), 63 Alignment, changing, 116
.DB (File extension), 64 allow file, 500
.DSR (File extension), 64 Allow IP addresses, 500
<, as LE start character, 80 Alternate form, switching to, 155
. (period), as image path, 159 Application
.DB (File extension), 168 Copying a complete application, 431
.DSR (File extension), 168 Default formats for, 124
;, in searches, 255 Previewing, 105
/, in searches, 255 Sample design, 64
=, in searches, 255 Application Documenter, 165
/=, in searches, 255 Application Menu, 43
.. (in range searches), 256 Application menu, using, 49
?, in searches, 258 Application Programming, 159
.. (in 'wildcard' searches), 258 Application Property Manager, 158
\ , in searches, 268 Application Settings, 119
], in searches, 268 Application Title, 159
&, in searches, 269 Application Utilities, 427
`, in searches, 269 Application, merging another, 167
~, in searches, 269 Application, new, 66
{}, in searches, 281 Application, Open on startup, 559
, in searches, 282 Application, setting properties for, 158
\n (Carriage return, exporting), 352 Application, unloading, 493
ASCII Database, 34, 68
ASCII Export dialog, 346
A ASCII file, 337, 344
Abnormal termination, 480 ASCII files, sorting, 344
About Sesame (Help menu), 36 ASCII import, 338
Add Data menu, 45 Asterisks, Secret Input, 138
Add New Database, 74 Attaching retrieve and sort specs, 416
Adding a Layout Element to a Tab Page, 177 Attachment, 57
Adding a new field (Field Manager), 161 Attachment, toggle, 53
Adding a new record, 204 Attribute Table, 165
Adding a Tab Group, 176 Autocalc, setting for a form, 127
Adding and editing pictures, 212 Autocomplete, 35, 207, 224
Adding layout elements to a form, 78 Autocomplete when searching, 250
Adding static text, 77 Auto-selection, 207
Adding tab pages to a tab group, 179
Administrative password, 496
Administrator login, 477, 480, 489

561
INDEX
Command Area - Open/Close, 36
B Command button element, defined, 84
Backtick (`), in searches, 269 Command button, adding, 89
Backup Application, 427, 428, 495 Command line options, 486
Binding, 125 Command line switches, 555
Blank field, searching for, 255 Command line utilities, 537
Blink, cursor, 35, 556 Commands panel, 110
Bookmark a Record, 217 Configurations, network, 483
Boolean elements, adding, 81 Connections, 488
Boolean field, entries permitted, 95 Constructs regex() and qanda(), 292
Boolean formatting, layout element, 121 Control Panels, 109
Bound to (layout element), 125 Converting Q&A databases, 30
Box element, defined, 84 Copy (Edit menu), 34
Boxes (static), 84 Copy a layout element, 99, 100
Boxes (text). See Text boxes Copy an application, 431
Buffer, 227 Copy and paste records, 227
Buffer (copying a record), 52 Copy dialog, 354
Copy form to buffer, 52, 227
C Copy Forms to Buffer, 52
Copy records (Results commands menu), 53
Calculate form, 51 Copy Spec, 229, 354
Calculate Programming (Autocalc), 127 Copying a database. See Merge Application
Cancelling a Mass Update, 301 Copying a Designer file, 432
Canvas (area off form), 105 Copying a form (Layout Manager), 164
Capitalization in searches, 252 Copying a layout (Layout Manager), 164
Case sensitivity in searches, 252 Copying a report (Layout Manager), 164
Case-sensitive searches, 269 Copying a single record, 52, 227
Change Log, 153 Copying fields and records, 226
Charts, creating, 235 Copying Layout elements, 99
Check box element, defined, 84 Copying LE formatting, 97
Check box, adding, 87 Copying Records, 227, 228, 352
Child records, 185 Difference Q&A, 353
Clearing a retrieve spec, 254 Match names, 355
Client, 486 Creating a New Sesame Application, 68, 73
Client-server, 483 Creating an applictation from an ASCII
Clipboard, using when editing, 225 Database, 68
Close (File menu), 34 Creating an applictation from an XML
Close Form Without Saving, 51 Database, 70
"-closed" startup switch, 43 Cross-platform, 21
Color CSV file, 348
Changing form color, 115 Ctrl-F10, 51
Color palettes, 115 Ctrl-F5, 53
Colors, changing, 115 Ctrl-F6, 51
Colors, custom, 115 Ctrl-F7, 52
Colors, setting, 115 Ctrl-F9, 51
Column width export files), 350 Currency elements, adding, 81
Combination Freeform/Columnar reports, Currency formatting, layout element, 122
409 Current date, inserting, 53
Combo box element, defined, 84 Current time, inserting, 53
Combo box, adding, 85 Cursor blink, 35, 556
Combo box, editing choices, 86 Custom colors, 115
Comma Separated Values, 348
562
INDEX
Custom Format, 119 Deleting a report (Layout Manager), 164
Custom help, 31 Deleting layout elements, 101
Custom help, adding, 147 Deleting static text, 78
Custom help, described, 146 Deleting tab pages, 182
Custom tooltips, 149 Delimit All Fields, 349
Customizing Forms, 133 Delimit Strings, 349
Cut (Edit menu), 34 Delimited file. See ASCII file
Cut/Copy/Paste, 225 Delimiter, exporting, 349
Delimiter, importing, 338
deny file, 500
D Derived columns, in reports, 423
.DAT (File extension), 23 Design New Application, 428
Data entry shortcut keys, 213 Designer, 23, 61
Data entry templates, 144 Copying a Designer file, 432
data source, 331, 332 Fields & layout elements defined, 65
Data types, 201 Starting as a standalone application, 61
Data typing, 139 Designer file, 62, 63, 168
"Database .. failed to open" message, 480 Delete All Data Records, 166
Database, defined, 23, 65 Previewing, 106
Database, deleting, 161 Designer, defined, 61
Database, merging another, 167 Designer, starting, 30, 61, 66
Database, new, 74 Directional Navigation, 35, 153
Database, Open on startup, 559 Disconnect, 491
Database, renaming, 127, 161 Ditto, 213
Database, Searching and Sorting, 247 Ditto Current Field, 52
Databases, opening recently used, 27 Ditto Current Form, 52
@Date (not valid as initial value), 126 Ditto Field/Record, 226
Date (current), inserting, 53 Documentation, 22, 24
Date elements, adding, 81 Drill-down search, 272
Date field, entries permitted, 95 .DB (File extension), 63, 64
Date formatting, layout element, 120 .DSR (File extension), 23, 62, 63
Date retrievals, 254, 255, 257 .DSR (File extension), 63
.DB (File extension), 23, 168 .DSR (File extension), 64
.DDT (File extension), 23 .DSR (File extension), 168
Default display format, 159 .DSR file, 169
default formats, 123 DSR file, defined, 67
default formats for an application, 124 Duplicate Me, 99
Default retrieve spec, 287 Duplicate Records, 218
Default sort spec, 296 Deleting, 218
Delete (Edit menu), 35 Notes on removing, 220
Delete a database (trim application), 429 Removing temporarily, 218
Delete All Data Records (from Designer file), Searching for, 221, 223
166 Duplicate records, deleting (Results
Delete duplicate records (Results commands commands menu), 54
menu), 54 Duplicate Selected Elements, 100
Delete Record, 51 Duplicates (removing from results), 221
Deleting a database (Field Manager), 161 Dynamic sort, 294
Deleting a field (Field Manager), 161
Deleting a form (Layout Manager), 164
Deleting a layout (Layout Manager), 164 E
Deleting a record, 217 Edit Window, 58

563
INDEX
Editing ASCII options, 347
Boolean elements, 203 carriage returns, 352
check box, 210 Custom Separator, 348
combo box, 209 Delimited ASCII file, 344
Cut/Copy/Paste, 225 Delimiter, 349
Data entry shortcut keys, 213 Export dialog, 346
Date elements, 202 F (Fixed width), 350
Deleting a record, 217 Field Name Header, 349
Ditto, 213 File format, 344
Expanded field editor, 208 Fixed, 350
Image editor, 212 Fixed ASCII & truncating values, 350
image field, 211 How to export, 344
Keyword elements, 203 Ignore Fixed/Max Lengths, 350
list box, 209 M (Max num characters), 350
Making Corrections, 232 Max, 350
Money (currency) elements, 202 \n (carriage return), 352
Multi-line text elements, 207 O (variable width), 350
Number elements, 202 Open, 350
radio button group, 211 quotes around text, 344
Saving a record, 216 separator, 347
special layout elements, 208 Sorting, 344
Table view, 233 Subform data, 372
Text elements, 202, 206 tab separator, 348
Time elements, 203 Exporting Data, 343
Undo, 231, 232 Exporting data from subforms, 352
Undo field, 232 Exporting multi-line text fields, 352
Undo form, 232 Extension, file, 23, 62, 64
Using Forms, 204
Yes/No elements, 203
Editing static text, 78
F
Element. See Layout Element(s) F (Exporting option), 350
Element Example Palette, 82 F1, 53
Email retrieval via Sesame Web Server, 472 F10, 262
Embedded Dialogs, 57 F10 key, 50, 214, 240, 245, 365, 540
Empty field, searching for, 255 F11, 52
Envelopes, 331 F3, 51
Environment Variables, 507 F5, 52
Error log, (on importing, 343 F5 (Current value), 133
Esc, 51 F6 (Field editor), 133
Escape, 51 F6 Edit Window, 58
Example Palette, 82 F6 expanded field editor, 208
Execution Order, Programming, 150 F7 key, 214, 271, 540
Exit (File menu), 34 F7 Key, 540
Expanded field editor, 208 F8 (Calculate), 51, 127
Export (for merge printing), 331 F9, 50
Export Application to XML, 430 "Failed to open" message, 480
Export Data (Results commands menu), 54 Field Manager, 161
Export Design to XML, 167, 359 Adding a new field, 161
Export Layouts to XML, 359 Changing a field type, 161
Export spec, 344 Deleting a database, 161
Exporting Deleting a field, 161

564
INDEX
Renaming a database, 161 Full-Feature Reports, 390
Renaming a field, 161 Function Key Menu, 36, 55
Field Name Header, 349
Field name, changing, 161
Field type, changing (Field Manager), 161
G
Field, adding a new, 161 Getting Started, 23
Field, defined, 24, 65 Global code, 303
Field, deleting, 161 Global Values List Manager, 167
File extension, 23, 62, 64 Global Values, replacing when reconciling,
File New (toolbar button), 36 173
File Open (toolbar button), 36 GoTo (use of deprecated), 152
File Save (toolbar button), 36 Grayed out (Read-only) elements, 137
Files, Sesame, 63, 64 Grid, in form design, 97
Find First Match, 251
Find on this Form, 283
Find on This Form, 35
H
First Record (go to), 36 Height, changing, for a form, 104
Fixed ASCII export and truncating values, Height, changing, for Layout Elements, 103
350 Help, 53
Fixed ASCII import, 339 Context-sensitive, 31
Focus, 49 Custom help, 31
Focus, defined, 41 Custom help appears automatically, 32
Fonts, changing, 116 Tooltips, 32
Form compilation, 505 Using, 31
Form customization, other, 150 Help Menu, 36
Form Design, Keystrokes, 83 Hidden layout elements, 138
form letter, 329 Hide macro results (view menu), 35
Form Navigation, 239 Hide menu tree, 36, 43
Form, startup, 156 Hierarchical import, 21, 373
Formatting layout elements, 114, 120 HTML (printing form(s) to), 323
Formatting report elements, 114 HTML files, 508
Forms HTML output files, 425
Canvas, 105 HTML, printing Form to, 52
Changing color of, 115
Changing the Appearance of, 109 I
Copying, 164
Icons (toolbar), 36
Creating a new form, 74
IGNORE COLUMN, 340
Customizing, 133
Ignore Fixed/Max Lengths, 350
Default Formats, 123
Image box, adding, 90
Deleting, 164
Image editor, 212
Improving appearance of, 133
Image elements, adding, 81
Laying out a form, 75
Image field element, defined, 84
Navigation, 212
Image field, entries permitted, 96
Opening a form, 28
Image files, path to, 159
Redesigning, 109
Image labels, 90
Renaming, 164
Image path, 159
Resizing, 104
Image searches, 277
Forms, relinking, 155
Image, as a LE label, 90
Forms, Resizing, 77
Import a database. See Merge Application
Forms, switch to alternate form, 155
Import Data (Results commands menu), 54
Freeform reports, 405
Import errors, 343

565
INDEX
Import Layouts from XML, 360 Bound to, 125
Import Q&A, 34, See Translate Q&A Defined, 24, 65, 78
Import spec, 339 Unbound, 66
Importing Layout Element Adder, 81
Blank fields, 338 Layout Elements
Fixed ASCII, 339 Adding a multi-line text box by typing on
How to import, 339 the form, 80
IGNORE COLUMN, 340 Adding by Typing on the Form, 78
Standard ASCII, 339 Adding data elements, 78
Subform data, 373 Adding multiple, 80
Importing Data, 337 Adding to a Tab Page, 177
Importing data into subforms, 373 Adding with the layout element adder, 81
Importing Q&A databases, 30 Adjusting position incrementally, 118
Importing subform data, 198 Adjusting size incrementally, 118
Indexed fields, 127 Advanced element selector, 131
Initial values, 126 Aligning to each other, 116
Initial values, programming alternative, Binding, 94, 126
126, 136 Boolean formatting, 121
Insert Current Date, 53 Border style, 116
Insert Current Time, 53 Box style, 116
Installation Guide, 25 Centering on form, 116
Installing Sesame, 25 Change label, 133
Internet, Sesame on the, 499 Change LE name, 134
Interrupting a Mass Update, 301 Changing Color, 115
Introducing Sesame, 21 Changing fonts, 116
Invalid LE names, 79, 135 Changing label alignment, 116
Inverted Search, 265 Changing text alignment, 116
Invisible layout elements, 138 Changing text size, 116
IP addresses, 500, 501 Copying, 99, 100
Allowing, 500 Currency formatting, 122
Restricting, 500 Custom help, adding, 147
Date formatting, 120
Deleting, 101
J Format settings, 119
Just in Time Compilation, 505 Formatting, 120
Formatting multiple elements, 123
K Grayed out, 137
Hidden, 138
Keyboard shortcuts, 539 Invalid names, 79, 135
Keystrokes (navigation), 239 Invisible, 138
Keyword elements, adding, 81 LE names & labels, 79
Keyword field, entries permitted, 95 LE names & programming, 79
Keyword searches, 267 lower case formatting, 120
Making same size, 118
L Money formatting, 122
Moving, 102
Label Alignment, 116
Multi-line text boxes, creating, 116
Label, changing an element's, 133
Naming rules, 79
Last Record (go to), 36
Number formatting, 122
Layout Element
Position of elements, 116
Auto-selection, 207
Position of labels, 116
Bound, 66

566
INDEX
Properties list, 165
Read-only, 137
M
Relabelling, 98 M (Exporting option), 350
Relative alignment, 116 Machine name, 486
Relative sizing, 116 Macro indicator, 378
Renaming, 134 Macro visibility (view menu), 35
Resizing, 103 Macros, 377
Restrictions, 139 Alerts, 378
Rubber-banding, 101, 102 Autoloading, 555
Rules for naming, 79 difference Q&A, 312, 377
'Secret formatting', 138 Human readable macro files, 381
Selecting multiple, 101, 102 Loading a macro, 380
Setting formats for, 120 Macro files, 381
Sizing, 103 Macro visibility, 379
Sizing to match, 118 Nested macros, 381
Spaces in LE names, 79 Playing back a macro, 379
Spacing of elements, 116 Recently-used Macro List, 383
Templates, 144 Recording a macro, 378
Time formatting, 121 Saving a macro, 380
Tooltips, adding custom, 149 Series Counter, 382
Types of, 77, 83 Macros vs. programming, 381
Unique, 138, 143 mailing labels, 331
UPPER CASE formatting, 120 Mailmerge, 329, See also Merge Printing
Using the different element types, 85 Main Advance Record, 51
Visibility, 138 Main Previous Record, 51
Working with multiple, 101, 118 Make Like Me, 97
Yes/No formatting, 121 Managing a Database, 161
Layout Manager, 163 Managing fields, 161
Copying a layout, 164 Managing Layouts, 163
Deleting a layout, 164 Mandatory restrictions, 126
Renaming a layout, 164 Mass Delete (Results commands menu), 53
Layout Settings, 119 Mass update, 297
Layout, copying, 164 Backup first, 298
Layout, defined, 23, 65 by other means, 314
Layout, deleting, 164 Continuous mode, 300
Layout, renaming, 164 Default mass update Spec, 311
Layouts, Managing, 163 Endurance of the mass update spec, 314
LE. See Layout Element(s) Global code, 303
License file, location of, 499 IF/THEN programming, 313
LICENSE_PATH, 499, 507 in a multi-user environment, 314
Line element, defined, 84 Interactive, 300
Linking, types of, 523 Invalid programming, 306
Linux, 21, 25 Mass Update Spec, 298
List box element, defined, 84 network considerations, 314
List box, adding, 86 Order in which records are updated, 313
List box, editing choices, 86 overview, 297
Load a macro, 35 Program editor, 302, 304, 305
Lock/Unlock an application, 502 programming execution order, 302
Locked, database, 480 Programming in just one element, 303
Log File, 502 programming statement, 299
Log(s), 493 Q&A and mass updates, 312
Saved mass update spec, using, 309
567
INDEX
Saving mass update specs, 307
Saving the programming, 306
N
security, 312 Name, changing an element's, 134
Skip record(s), 300 Naming Layout Elements, rules for, 79
Sort order of records, 313 Naming multiple elements, 126, 136
Spec Manager, 307 Natural vs. relational linking, 523
Testing your programming, 306 Navigating around a form, 212
Translated Q&A mass updates, 313 Navigation, 239
Mass Update (Results commands menu), 54 Arrow keys, 240
Mass update programming, 299 End, 239
Mass Update Spec, 298, 301 Enter key, 239
Mass Update, Interrupting, 301 Home, 239
Max and Min, in searches, 257 Moving between main form and subforms,
maximized window, 56 243
Memory Menu, 226 Multi-line text, 241
Menu Bar, 33 Tab key, 239
Menu button element, adding, 89 Table view, 244
Menu button element, defined, 85 Text Editor, 241
Menu Buttons, searching, 277 Navigation keys, 239
Menu Tree, 41 Navigation menu, 50
Menu tree - Open/Close, 36 Navigation Order, 152
Menu Tree, defined, 38 Navigation Order, resetting, 96, 153
Menu Trees, Single Level, 42 Navigation, Directional, 153
Merge Application, 167, 428 Nested macros, 381
Merge documents, 329 Network Administration, 483
Merge fields, 332 Network administration tips, 498
Merge File Print, 52, 54 Network Communications, 503
Merge Printing, 329 Network configurations, 483
Merge Printing, using WordMerge, 334 Network Setup, 485
Merging two applications, 429 New (File menu), 34
Merging via data export, 331 New Application, 66, 428
Message Log, 153 New database, 74
Microsoft Word, 331, 333 New form, 74
Migrating to Sesame, 21 Next Matching Record, 51
Mode indicator, 37 Next matching record in current results, 273
Money elements, adding, 81 Next Record (go to), 36
Money field, entries permitted, 95 NOT empty, searching for, 255
Money formatting, layout element, 122 NOT, in searches, 255
Mouse Notification tab, 491
Center button, 215 NotifyForm() programming (alternative to
Left button, 215 restrictions), 143
Right button, 215 @Number (not valid as initial value), 126
Using, 215 @Number, setting, 160
Moving around a form, 239 @Number, replacing when reconciling, 172
Moving around in table view, 244 Number field, entries permitted, 95
Moving Between Elements in Designer, 96 Number formatting, layout element, 122
Moving layout elements, 102 Number of Records (toolbar), 36
Moving Tab Groups, 184
Multi-line text element, setting, 116
Multiple Servers, 484
O
O (Exporting option), 350
Open (Exporting), 350
568
INDEX
Open (File menu), 34 Print Form, 51
Open a database, 26 Print Form to HTML, 52
Open a form to search, 205 Print Forms, 54
Open an application, 26 Appearance of the printed record, 322
Open an application automatically, 559 in Add mode, 322
Open an database automatically, 559 in update mode, 316
Open command area, 36 More ways to print, 327
Opening a form, 28 Multiple pages per record, 320
Opening a form to add data, 204 Multiple records per page, 319
Opening Sesame, 25 Printing table view, 324
Operational mode indicator, 37 Table View, 325
Optimization, 504, 505 to HTML, 323
Optional restrictions, 126 Print Forms Dialog Box, 317
OR, in searches, 255, 259 Printing an individual record, 317
Order (Navigation), 152 Printing commands, 51
Order (Program Execution), 150 Printing Commands (Menu), 54
Order of tab pages, changing, 181 Printing Forms, 315
Orphan records, 366 PrintString as alternative, 327
"Other" Tab (Property Editor), 125 Printing subforms, 368
Printing table view, 324, 325
Printing the result set, 317
P Printing, ways to print data, 315
Page Down, 240 Program Application, 159
Page marker, adding, 93 Program Editor, 150
Page marker, defined, 85 Program Execution Order, 150
Page Up, 240 Program form, 150
Parent records, 185 Program layout, 150
Password Controls, 446 Program Report, 150
Password, minimum length, 446 Programmed data entry restrictions, 142
Passwords, changing, 450 Programmed retrieves, 280
Passwords, Secret Input, 138 Programmed retrieves, speeding up, 282
Paste (Edit menu), 34 Programming Guide, Sesame, 22
Paste buffer to form, 52 Programming, mass update, 299
Paste buffer to forms, 52 Programs, Sesame, 23
Paste Form to Buffer, 228 Property Editor, 114
Paste records, 227 Alignment, changing, 116
Philosophy, 515 Apply all settings, 118
Picklists (alternatives to restrictions), 126 Autocalc, 127
Picture elements, adding, 81 Boolean element formatting, 121
Picture fields, editing, 211 Border style, 116
Picture searches, 277 Box style, 116
Pipe symbol, in searches, 282 Color palettes, 115
Playback macro, 35 Color tab, 115
Point size. See Fonts Currency element formatting, 122
Ports, 486 Current settings not shown, 114
Preloading applications, 498 Date formatting, 120
Preview mode, 105 Font & size, changing, 116
Previewing a report, 418 Format settings, 119
Previewing the application, 105 Format tab, 119
Previous Record, 50 Initial values, 126
Previous Record (go to), 36 Look tab, 116

569
INDEX
Money element formatting, 122 Quick-Start Tutorials, Sesame, 22
Multi-line text boxes, creating, 116
Number element formatting, 122
Other Tab, 125
R
Position of elements, 116 R button (in import spec), 341
Position of labels, 116 "R" setting, naming multiple elements, 126,
Position tab, 116 136
Relative alignment, 116 Radio button group element, defined, 84
Relative sizing of elements, 116 Radio button group, adding, 87
Rename Database, 127 Ranges, in searches, 256
Restrictions, 126, 140 Read-only elements, 137
Spacing of elements, 116 Recently Opened File list, 27
Text tab, 116 Reconcile, 62, 63, 170
Time element formatting, 121 Reconcile Options, 171
Yes/No element formatting, 121 Reconcile Options dialog, 173
Property Editor vs. Property Viewer, 112 Reconciling, 170
Property Viewer, 112 Record Macro, 35
Protected Application (Security), 445 Record Navigation (Toolbar), 36
Proxy, 528 Record set. See Result set
Record, bookmarking, 217
Record, defined, 24, 65
Q Record, Next matching Record, 273
Q&A Records
Converting database into Sesame, 34 Copying, 226, 228
Database defined, 63 Ditto record, 226
Differences in restrictions, 126 Records, Searching, 247
GoTo (use of deprecated), 152 Record-to-record navigation, 216
Mass updates, 312 Redesign Current Application, 66, 168, 428
Restrictions as picklists, 140 Regex, 288
Searching differences, 251 Regional Options, 203, 254
Speedy fields, 127 Regional settings, 120, 202
Time not stored with seconds, 53 Regular expressions, 288
Translated mass updates, 313 Relabel layout element, 98
Translation into Sesame, 34 Relational Linking, 523
Weaker data typing, 139, 202 Relational vs. natural linking, 523
Q&A (Translate) (File menu), 34 Relationships, 185
Q&A Database Translation Guide, 22 Relink Form, 155
Q&A drawing characters, removing, 105 Remove (records). See Mass Delete
Q&A line draw characters, removing, 105 Remove a database, 429
Q&A phonetic search, 270 Remove Duplicates from Results, 221
Q&A programmed retrieve differences, 281 Remove Duplicates from Results (Results
Q&A Translation, 70 commands menu), 54
Q&A Translation Errors, 477 Remove from results, 51, 274
Q&A Translation Options, 71 Removing. See Deleting
Q&A Translation, Managing Errors, 72, 477 Rename Application, 163
Q&A Translation, programming, 72 Renaming
Q&A Translation, Reports, 72 Database, 127
Quick Report Spec, 386 Layout Elements, 134
Quick Reports, 386 Renaming a database (Field Manager), 161
Quick Reports, saving, 388 Renaming a field (Field Manager), 161
Quick Start Menu, 36, 39, 41 Renaming a form (Layout Manager), 164

570
INDEX
Renaming a layout (Layout Manager), 164 Resizing layout elements, 103
Renaming a report (Layout Manager), 164 Resizing tab groups, 183
Renaming tab pages, 180 Resizing the form, 77, 104
Report Creation Wizard \b, 412 Restrict IP addresses, 500
Report Writer. See Reports Restrict network connections, 500
REPORT_PATH, 507, 509 Restrict values, 139
Reports, 385 Restrictions, 126, 139
Adding layout elements, 397 ! (make mandatory, 126
Advanced Report Features, 420 Allow blank field, 126
Attaching retrieve and sort specs, 416 Checked on saving record, 126
Columnar reports, 396 Different to Q&A, 126
Combination reports, 409 Do not use as picklists, 126
Combination reports, typical example, Mandatory, 126
411 Optional, 126
Copying, 164 Restrictions, applying, 140
Default Formats, 123 Restrictions, Mandatory, 141, 142
Deleting, 164 Restrictions, Optional, 141
Derived columns, 423 Restrictions, programmed, 142
Freeform reports, 405 Result set, 251
full-feature reports, 390 Result Set, moving through, 251
HTML output files, 425 Results Commands menu, 53
Ignore blank values, 404 Retrieve spec, 248
Introduction, 385 Retrieve spec programming, 280
Month and year breaks, 405 Retrieving. See Searching
Moving elements, 401 Reveal menu tree, 36
Multiple breaks, 404 Right Click Menu, 97
Naming reports, 391 ROOTDIRS.INI, 499
No repeat option, 405 Rubber-banding, 101, 102
Page Headers and Footers, 404 Rules for naming Layout Elements, 79
Preview mode, 403 Run macro, 35
Previewing a report, 418 Runtime, Sesame, 23
Printing options, 405
Property Editor & Viewer, 402
Quick Report spec, 386
S
Quick reports, 386 s_conf, 499
Reconciling a report, 420 Save (File menu), 34
Relocating HTML output files, 426 Save As (File menu), 34
Renaming, 164 Save As New Application, 169
Report Creation Wizard, 412 Save Global Settings, 541
report interface, 392 Save macro, 35
Report sections, 396 Save Record, 51
Running a report, 420 Save Record and Close Form, 51
Saving a report, 418 Saved Specs, replacing when reconciling,
Selecting elements, 401 173
Subreport, 394 Saving a record, 216
Summary totals and breaks, 421 Saving a report, 418
Typical report example, 392 Saving Searches for re-use, 284
Reports, location of, 508 Saving Your Design as a Sesame
Reports, running, 54 Application, 108
Reserved Word, 79 Scoot Mode, 96
Reset Navigation Order, 96, 153 Scroll region, adding, 91

571
INDEX
Scroll region, defined, 85 Field types, 254
sDesigner. See Designer, See Designer Find First Match, 251
Search Commands, 262 for images by filename, 279
Search criteria essentials, 254 for images graphically, 278
Search in Current Results, 272 for pictures, 277
search logic, 260 French braces, 281
Search, phonetic, 269 Image searches, 277
Search, soundex, 269 Inverted Search, 265
Search/Update menu, 44 Keyword searches, 267
Searching, 247 List boxes, 276
&, 269 Main records with no subrecords, 371
\ (literal), 268 Max and Min, 257
* (wildcard character). See .. Meet ALL restrictions, 260
.. (ranges), 256 Meet Any restriction, 260
.. (wildcard character), 258 Menu Buttons, 277
/, 255 Next matching Record, 273
/=, 255 NOT, 255
;, 255 NOT empty, 255
? (wildcard character), 258 Operators and ranges examples, 257
], 268 OR, 255
`, 269 OR across fields, 260
{}, 281 Performing a new search, 253
~, 269 Pipe symbol, 282
, 282 Programmed retrieves, 280
= (empty field), 255 Programmed retrieves, performance, 282
Add to Current Results, 271 Q&A - phonetic search, 270
Advanced searches, 259 Q&A v. similar, 252, 255
AND across fields, 260 Q&A, differences, 281
Arithmetic operator examples, 256 Radio button groups, 276
Autocomplete, 250 Ranges, 256
Backtick (`), 269 Refining the result set, 271
Basic search criteria examples, 256 Regex() and qanda(), 292
Basic searches, 247 Regular expressions, 288
Blank field, 255 Remove Duplicates from Results, 221
Browser-type Searches, 263 Remove from Current Results, 274
Case sensitivity, 252 Renaming a saved retrieve spec, 287
Case-sensitive searches, 269 Result set, 251
Check boxes, 275 Retrieve spec, 251
Clearing a retrieve spec, 254 Retrieve Spec, 248
Combo boxes, 276 return to retrieve spec, 253
Date fields, 254 Saving a search, 284
Dates, 254, 255, 257 Saving Searches for re-use, 284
Default retrieve spec, 287 Search Commands, 262
Deleting a saved retrieve spec, 287 Search criteria essentials, 254
differences Q&A, 251 Search in Current Results, 272
Differences Q&A, 251 search logic, 260
Drill-down search, 272 search mode, 261
Either/Or, 255 Searching a single field, 252
Empty field, 255 Searching multiple fields, 253
Examples of special search characters, Searching one record, 283
270 Simple Search and Sorting, 265

572
INDEX
Simple Searches, 263 Security, replacing when reconciling, 173
Sorting records, 250, 293 Select All (Edit menu), 35
Spec Manager, 284 Select All Elements on a tab page, 182
Special Layout Elements, 252, 275 Selecting all layout elements on a tab page,
Special search characters, 255 181
Special search characters (advanced), Selecting Position of Tab Labels, 184
268 Selection Layers, 128
Templates, 250 Selection layers, moving up/down, 98
unbound layout elements, 254 separator, exporting, 347
Universal search, 266 Server, 486
Upper or lower case, 252 Server administration, 447, 489
Using a previously-saved retrieve, 285 Server Administration
View Current Results, 274 Standalone administrative client, 498
When and how to sort, 294 Server Administration (File menu), 34
Wildcard characters, 258 Server Administration, starting, 477, 480
Wildcard search examples, 259 Server Console, 488
Searching and Sorting, 247 Server Status Window, 488
Searching for Duplicate Records, 221 Server, stopping, 482, 491
Searching Special Layout Elements, 275 Sesame application, defined, 63
Searching subforms, 368 Sesame Designer. See Designer
Secret Input, 138 Sesame Designer, starting, 30, 61
Securing Your Applications, 433 Sesame Initialization File, 541
Security, 433, See also Security Manager Sesame server, 487
Administrator, 435 Sesame, Opening, 25
attributes, 433 Sesame, Starting, 25, 30, 61
Changing passwords, 450 Sesame.ini file, 541
Data Entry user, 435 Setting formats for a layout element, 120
Disabling temporarily, 167 Setting up client-server, 485
Frequently-asked questions, 450 Shift-F10, 51
Login dialog, 446 Shift-F11, 52
Manager, 435 Shift-F5, 52
Mass updates, 312 Shift-F6, 53
password dialog, 445 Shift-F7, 52
preventing design changes, 446 Shortcut Keys, 539
Q&A compatibility, 433 Shut down Sesame Server, 482
Remove All Application Security, 443 Simple Searches, 263
Remove Security For Element, 442 Sizing. See Resizing
Remove Security For Layout, 442 Snap To Grid, 97
Server administration, 447 Sort (Results commands menu), 54
Summary, 449 Sort by Timestamp (Results commands
User levels, 434 menu), 54
User Management, 447 Sorting, 293
X Password, 443 Default sort spec, 296
XLookups, 443 Dynamic sort, 294
Security and Sesame Web Server, 471 Saving sort specs, 296
Security Manager, 437 Spec window, 293
Delete a user, 441 Using the spec window, 47
Element level access, 441 When and how to sort, 294
Element-level permissions, 442 Sorting records, 293
Groups, 438 Sounds-like Search, 269
Users, 439 Spaces in Layout Element names, 79

573
INDEX
Spec action bar, 46, 48, 293 Make Natural Child Records, 191
Spec Manager, 284, 307 Mass Delete, 366
Spec selector buttons, 46, 293 Mass Update, 367
Spec window, 46 Moving between main form & subforms,
Spec Window, defined, 38 363
Spec window, described, 293 Natural link, 186
Spec window, using, 47 Orphan records, 366
Special search characters (advanced), 268 Printing forms, 368
"Speedy fields", 127 Relational link, 186
splash screen, 556 Re-parenting, 366
Standalone administrative client, 498 Searching, 368
Standard ASCII, 339, 348 Searching for main records with no
Start macro recording, 35 subrecords, 371
Starting Sesame, 25 Select records to display, 191
Starting Sesame Designer, 30, 61 Select Subrecord type, 191
Startup Form, 156 Settings dialog, 190
Startup Switches, 555 Show Existing Natural Child Records, 191
Static Layout Elements, defined, 77 Subform properties, 192
Static picture element, defined, 84 Subrecord, 186
Static picture, adding, 90 Table view subform, 186
Static Scroll region, adding, 91 Terminology, 186
Static text element Subforms, creating, 200
Adding by typing on the form, 77 Subforms, importing data into, 198
Adding with layout element adder, 85 Subforms, Using, 361
Defined, 77, 84 Subrecord, 185, 186
Deleting, 78 Subreport, 394
Editing, 78 Summary totals and breaks, in reports, 421
Status line, 37 SUnlock, 537
Stop macro recording, 35 SVersion, 537
Stop This Server, 491 Switch to Add Data Mode, 51
Subform element, defined, 84 Switch to Alternate Form, 54, 155
Subform Settings dialog, 190 System Settings, 119, 120
Subform, adding, 91
Subform, form view, 361
Subform, table view, 362
T
Subform, types of, 361 Tab groups
Subforms, 361 Label position, 184
Adding and editing data, 364 Sizing, 183
Adding new subrecords, 365 Tab Groups, 175
Create a new Database with Shared Adding, 91, 176
Template, 192 Adding tab pages, 179
Creating a subform, 187 Changing order of tab pages, 181
Creating using relational linking, 195 Deleting tab pages, 182
Data source, 186 Label, 177
Deleting a parent record, 366 Moving, 184
Deleting subrecords, 366 Naming, 177
Exporting data, 372 Tab key (form navigation), 239
Form view subform, 186 "Tab Order". See Navigation Order
Hierarchical import, 373 Tab Pages, 175
import ASCII file, 375 Aligning layout elements, 181
Importing data, 373 Changing color of a tab page, 182

574
INDEX
Changing labels, 180 Trim Application, 429
Changing order, 181 Troubleshooting, 477
Deleting, 182 Tutorials, 24
Moving within group, 181
Renaming, 180
Select All layout elements, 181
U
Selecting all elements on a page, 182 Unbound layout elements, 66
Tab Pages, Adding layout elements to, 177 Undo, 101, 231, 232
tab separator, 348 Undo (Edit menu), 34
Tabbed Pages, 175 Undo Current Field, 52
Adding, 91 Undo Current Form, 52
Defined, 175 Undo Last Change, 101
Described, 175 Undo multiple actions (advanced), 153
Tabbed Pages, defined, 84 Unhide menu tree, 43
Table view Uninstalling Sesame, 32
Editing data in, 233 Unique fields, 138, 143
Navigating, 244 Universal search, 266
Table View Unload application, 493
Charts from, 235 Unlocking an application, 480, 492
Customizing, 234 UPPER or lower case when searching, 252
Functions from, 235 Use as Example, 99
Saving layout of, 235 User Guide, Sesame, 22
Sorting, 235 User levels (Security), 434
Table View (Other Commands menu), 53 User Management, 447, 497
Table View, printing, 325 @UserID (not valid as initial value), 126
Templates and searching, 250 Users, security, 439
Templates, data entry, 144 Utility Programs, 537
Temporarily Disable Security, 167, 449
Text box
Adding a multi-line text box element by
V
typing on the form, 80 View options, 39
Adding by typing on the form, 79
Text box element, defined, 84 W
Text Box, defined, 78
warnings, 556
Text editor element, adding, 88
Ways of working with Sesame, 49
Text Editor element, defined, 85
Web Capabilities, 451
Text field, entries permitted, 95
Web Server, 451
ThrowFocus navigation programming, 152
Adding a new record, 466
@Time (not valid as initial value), 126
Dynamic web page, 458
Time (current), inserting, 53
Email retrieval, 472
Time elements, adding, 81
Posting a new record to the database,
Time field, entries permitted, 95
468
Time formatting, layout element, 121
Posting updates to the database, 464
Toggle Attachment, 53
Start Create menu page, 453
Toolbar, 33
Start Searching a database, 454
Toolbar, described, 36
Start Sesame web server, 452
Tooltip, 26, 32
Updating data, 460
Tooltips, custom, 149
Web server security, 471
Translate Q&A (File menu), 34
Web Server Security, 471
Translating Q&A databases, 30, 34
Width, changing, for a form, 104
Translation Guide, Q&A (documentation), 22
Width, changing, for Layout Elements, 103

575
INDEX
Width, setting, for export file columns, 350
Wildcard characters, in searches, 258
X
Window Management, 56 XML Database, 34, 70, 359
Windows Clipboard, 225 XML Export can take a long time, 359
Windows, sizing, 39 XML Utilities, 359
Wittgenstein. See Philosophy XML, Export Application to XML, 430
Word (mailmerge with), 331, 333 XML, export design to, 167
WordMerge, 334
WordPerfect, 331, 333 Y
Yes/No elements, adding, 81
Yes/No formatting, layout element, 121

576
READER'S NOTES
_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

577
READER'S NOTES
_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

578
READER'S NOTES
_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

_____________________________________________________________________________

____________________________________________________________________________

579

You might also like