Sesame 2 User Guide

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 User’s 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

CONDITIONS OF THIS LICENSE AGREEMENT CAREFULLY

BEFORE USING THE SOFTWARE. LANTICA SOFTWARE,

LLC AND/OR ITS SUBSIDIARIES (“LANTICA”) IS WILLING

TO LICENSE THE SOFTWARE TO THE INDIVIDUAL,

COMPANY OR OTHER LEGAL ENTITY THAT WILL BE

USING THE SOFTWARE (REFERENCED BELOW AS “YOU”

OR “YOUR”) ONLY ON THE CONDITION THAT YOU

ACCEPT ALL OF THE TERMS OF THIS LICENSE

AGREEMENT. THIS IS A LEGAL AND ENFORCEABLE

CONTRACT BETWEEN YOU AND LANTICA. BY OPENING

THIS PACKAGE, BREAKING THE SEAL, OR LOADING THE

SOFTWARE, YOU AGREE TO THE TERMS AND

CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT

AGREE TO THESE TERMS AND CONDITIONS, MAKE NO

FURTHER USE OF THE SOFTWARE AND REMOVE ANY

INSTALLATION FROM YOUR SYSTEM.

1. License

The software which accompanies this license (collectively, the

“Software”) is the property of Lantica and/or its licensors and is

protected by U.S. and international copyright law. While Lantica

continues to own the Software, you will have certain rights to use

the Software after you accept this license. This license governs any

releases, revisions, or enhancements to the Software that Lantica

may furnish to you. You may be held legally responsible for any

copyright infringement which is caused or encouraged by your

failure to abide by the terms of this license. Except as may be

modified by a Lantica license certificate, license coupon, license

key (each a “License Module”) which accompanies, precedes, or

follows this license, your rights and obligations with respect to the

use of the Software are as follows:

You may:

A. Use one copy of the Software on a single computer. If a License

Module accompanies, precedes, or follows this license, you may

make that number of copies of the Software licensed to you by

Lantica as provided in your License Module. Your License Module

shall constitute proof of your right to make such copies;

B. Make one copy of the Software for archival purposes;

C. Use the Software on a network, provided that you have a

licensed copy of the Software for each computer simultaneously

accessing the Software over that network; and

D. After written notice to Lantica, transfer the Software to another

person or entity on a permanent basis, provided that you retain no

copies of the Software and that the transferee agrees to the terms of

this license.

You may not:

A. Copy the printed documentation that accompanies the Software;

B. Sublicense, lease, or rent any portion of the Software;

C. Distribute the Software to others;

D. Reverse engineer, decompile, disassemble, modify, adapt,

translate, make any attempt to discover the source code of the

Software, or create derivative works based on or incorporating the

Software; or

E. Use the Software in any manner not authorized by this license.

2. Limited Warranty:

Lantica warrants that the media on which the Software is

distributed will be free of defects in materials and workmanship

under normal use and service for a period of sixty (60) days from

the date of delivery of the Software to you. Your SOLE remedy in

the event of a breach of this warranty will be that Lantica will, at its

option, replace any defective media returned to Lantica within the

warranty period or refund the money that you paid for the Software.

This warranty will not apply if the defect resulted from accident,

abuse or misuse. All replacement media will be warranted for the

remainder of the original warranty period or thirty (30) days,

whichever is longer. Lantica does not warrant that the Software will

meet your requirements or that the operation of the Software will be

uninterrupted or that the Software will be error-free.

THE ABOVE WARRANTY IS EXCLUSIVE AND IN LIEU OF

ALL OTHER WARRANTIES, WHETHER EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED

WARRANTIES OF MERCHANTABILITY, FITNESS FOR A

PARTICULAR PURPOSE AND NON-INFRINGEMENT OF

INTELLECTUAL PROPERTY RIGHTS. THIS WARRANTY

GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE

OTHER RIGHTS WHICH VARY FROM STATE TO STATE

AND COUNTRY TO COUNTRY.

3. Disclaimer of Damages:

SOME STATES AND COUNTRIES DO NOT ALLOW THE

LIMITATION OR EXCLUSION OF LIABILITY FOR

INCIDENTAL OR CONSEQUENTIAL DAMAGES SO THE

BELOW LIMITATION OR EXCLUSION MAY NOT APPLY TO

YOU.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE

LAW AND REGARDLESS OF WHETHER ANY REMEDY SET

FORTH HEREIN FAILS OF ITS ESSENTIAL PURPOSE, IN NO

EVENT WILL LANTICA OR ITS LICENSORS BE LIABLE TO

YOU FOR ANY SPECIAL, CONSEQUENTIAL, INDIRECT,

PUNITIVE, INCIDENTAL OR SIMILAR DAMAGES,

INCLUDING BUT NOT LIMITED TO ANY LOST PROFITS OR

LOST DATA ARISING OUT OF THE USE OR INABILITY TO

USE THE SOFTWARE, EVEN IF LANTICA HAS BEEN

ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN NO

EVENT SHALL LANTICA’S OR ITS LICENSORS' LIABILITY

EXCEED THE PRICE THAT YOU PAID FOR THE

SOFTWARE. The disclaimers and limitations set forth above will

apply regardless of whether you accept this license or not.

4. General:

This license will be governed by the laws of the Commonwealth of

Pennsylvania, United States of America, notwithstanding any

conflicts rules to the contrary. This license agreement and any

related License Module is the entire agreement between you and

Lantica relating to the Software and supercedes all prior or

contemporaneous oral or written communications, proposals and

representations with respect to its subject matter, and shall prevail

over any conflicting or additional terms of any quote, order,

acknowledgement, or similar communications between the parties.

This agreement may only be modified by a License Module or by a

written document which has been signed by both you and Lantica.

This license will automatically terminate without notice from

Lantica if you fail to comply with any of the terms contained

herein. You may terminate this license at any time by giving

written notice of termination to Lantica. Upon any termination of

this license, you must cease all use of and destroy all copies of the

Software. The disclaimers of warranties and damages and limitation

on liability shall survive any termination of this license. Should you

have any questions concerning this license, or if you desire to

contact Lantica for any reason, please write to: Lantica Customer

Service, P.O. Box 27, Penns Park, PA 18943-0027, USA

4

Sesame's Menu Trees

Sesame Application Menu

Add Data Menu (top)

Application Menu (multiple databases)

Add Data Menu (bottom)

MENU TREES

5

Search Menu

Search Update Menu – Submenus

Application Utilities Menu

MENU TREES

6

Search Update Menu (top)

Search Update Menu (bottom)

Table of Contents

7

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 Sesame’s 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

Contents continued

8

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

Contents continued

9

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

Contents continued

10

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

Contents continued

11

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

Contents continued

12

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

Contents continued

13

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

Contents continued

14

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

Contents continued

15

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

Contents continued

16

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

Contents continued

17

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

Contents continued

18

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 What’s 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

Contents continued

19

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

------------------------- �� -------------------------

21

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 Sesame’s features and capabilities. Four guides are included with the product:

INTRODUCING SESAME

22

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 Sesame’s 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.

23

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.

1 — GETTING STARTED

24

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 don’t understand all this, can I still use Sesame? Yes. You don’t need to understand database structure or theory to make a useful application that’s 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:


25

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:


26

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 (Windows XP).

Figure 2. Starting Sesame from the Programs menu.

The Sesame opening screen is displayed:

Figure 3. Sesame opening screen.

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 4. File Open dialog. Samples folder highlighted


27

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


28

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)


29

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.


30

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 Designer (see Starting Sesame, above).

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 9. Redesign Current Application

Figure 10. Opening Designer to create a new application

Figure 8. Desktop shortcut for Starting Sesame Designer.


31

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.

� Sesame’s 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, Sesame’s 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 window’s title bar, or by pressing F1 a second time to bring up Sesame’s 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.


32

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. Sesame’s 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.

33

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. Sesame’s 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.)

2 — SCREENS & MENU SYSTEM

34

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.


35

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


36

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


37

You can type a record number into the current record number box to move directly to that record number. (The current record number represents Sesame’s internal record numbering scheme and is not related to any record number data field.)

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

Figure 4. The Record Navigation Toolbar.


38

Sesame’s 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.)


39

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.


40

Figure 9. Quick Start on Entering Add mode

Figure 11. Quick Start in Update Mode

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.

Figure 8. Quick Start On Open Application

Figure 10. Quick Start at Search


41

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. Sesame’s 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 Sesame’s 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.


42

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.

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.

Figure 12. Single Level vs Normal Level Display Menu Tree


43

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 when starting a Sesame application.

Figure 14. Main application menu with the Application Utilities menu expanded.

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


44

� 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 you’ve 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.


45

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.


46

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.

Figure 17. The spec window for the Customers form.

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

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


47

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

Figure 18. The spec window components. Sort spec shown.


48

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 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 19. Spec Action Bar/dropdown list.

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


49

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.

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:

Figure 21. The Opening Application menu


50

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 Menu Choice (Keystroke)

What it Does

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


51

Navigation Menu Menu Choice (Keystroke)

What it Does

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

Saves record and closes form.

Close Form Without Saving (Esc) Closes form without saving (warning if unsaved edits).

Record Commands menu

Record Commands Menu Menu Choice (Keystroke)

What it Does

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.


52

Record Commands Menu Menu Choice (Keystroke)

What it Does

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

Allows current record to be merged with a previously created external document.

Edit Commands menu

Edit Commands Menu Menu Choice (Keystroke)

What it Does

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) (See note below)

Copies the data from the current record 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 Form (Shift-F11)

Pastes the data from Sesame's buffer into the 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.


53

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 Menu Choice (Keystroke)

What it Does

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 Menu Choice

What it Does

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.


54

Results Commands Menu Menu Choice

What it Does

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.


55

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


56

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.

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.

Figure 24. Activating the Function Key Menu


57

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.


58

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

Figure 27. Embedded dialog – filling window area.


59

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.

61

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 Designer’s 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 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.

Figure 1. Desktop shortcut for Starting Sesame Designer.

3 — DESIGNING A SESAME APPLICATION

62

Figure 4. Naming your Designer file: in this example Stamp_Collection.dsr

Figure 2. Redesign Current Application

Figure 3. Opening Designer to create a new 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 application’s 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 open file dialog prompting you to select or supply a


63

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 application’s 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.


64

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 don’t directly work with .dat files, but you do work with .dsr files.


65

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 database’s 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 you’ll 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


66

ordinarily used to display data is called a text box — it’s 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.


67

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.


68

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","Email","Position","Live_Prospect","Date_Entered","Hobbies","Numerical","TimeField","Checked","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"


69

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


70

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.


71

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

Figure 7. Q&A Translation Options.


72

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


73

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, Designer’s 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.


74

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.


75

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


76

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.


77

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


78

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)


79

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 element’s 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.)


80

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.) Adding a multi-line text box element by typing on the form 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

Figure 15. Adding a vertical series of text box layout elements by pressing Enter from each element to position correctly for the next.


81

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 order to see the label.

Figure 16. Layout Element Adder.


82

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 don’t 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.


83

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.


84

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 displayed on a form to act as an on-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

Figure 18. Layout Element Adder’s Select Element Type list


85

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.


86

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


87

Figure 22. Adding a Check Box.

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 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 has a label and is bound to 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 saved to the database field for a bound group.

Figure 23. Step 1 - Adding a Radio Button Group — add the group to the form.

Figure 24. Step 2 - Adding a Radio Button to the group on the form.


88

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.

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.

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.


89

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

Figure 27. Adding a Command Button.


90

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


91

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


92

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.


93

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 LE’s text box to the bottom of the lowest LE’s 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.


94

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


95

• 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 people’s records. See more in the section on Retrieving Records.


96

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.


97

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

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 selecting the elements you want to change, you right-click and release

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 33. Using Make Like Me to transfer formatting from irst Name element to Company, Add1, Add2, City, and State elements.


98

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.


99

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

Figure 35. Use as Example


100

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.


101

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. 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. It’s 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

Figure 36. Undo Last Change


102

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. 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 comprehensive—and 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:

Figure 38. Right-click to Select All


103

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

Figure 39. Moving element - coordinates shown.


104

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: These are the two most common ways to move 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.

Figure 41. Resizing element - dimensions shown.


105

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:

Figure 44. Preview Application button


106

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.


107

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.


108

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.


109

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.


110

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, Alignment

Text Tab

Set Element Box style, shape, fill and Label alignment

Look Tab

Set Element width, height, position, alignment, spacing, size, and selection layer

Position Tab

Set Display format for data Format Tab

Set Element Label, Name, Bound to, Initial Value, Read Only, Visibility, Restriction, Tool Tip, Custom Help, and Template

Options for Selected Elements, Other Tab


111


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 for Elements and Layouts,

View Settings for Selected Element, Color/Text Tab

View Current General information on Database and application

View Settings for Database or Application

View Current alignment, position, size, box type of element, and selection layer

View Settings for Selected Element, Look/Position Tab

View Element Data Display format View Settings for Selected Element, Format Tab

View Element Current Name, Label, Binding, Initial value, Restriction, Read Only, Visibility, Custom Help, Tool Tip, Entry Template

View Settings for Selected Element, Other Tab

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 formats

View Settings for Layout, Other Tab

View Current Database Name View Settings for Database, Database Tab

View Current Name, Formats, Image Paths for Application

View Settings for 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)


112


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

Figure 48. Control Panels.


113

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.


114

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 set in the Property Editor for 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.

Figure 50. Property Editor and Viewer displaying settings for First Name data element.


115

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 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 Set Color button which also previews the color.

Figure 51. Property Editor: Color tab.

Figure 52. Property Editor Custom Color tool.


116

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 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 keystroke combinations to cycle the element 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 element’s 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).

Figure 53. Property Editor: Look tab.

Figure 54. Setting Label Position with Property Editor.


117

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

Figure 55. Property Editor: Position tab.


118

Right Align all to right-most selected element

Center on parent element

Center element(s) on parent — eg. form

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.


119

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

Figure 56. Property Editor: Format tab.


120

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


121

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:


122

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)

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 60. Format / Custom / Number

Figure 61. Format / Custom / Currency


123

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.) Note: Settings for Number and Money 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.)

Figure 62. Mixed element types selected. In this case Number and Boolean (checkbox). Note the yellow tab.


124

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.


125

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

Figure 64. Property Editor — Other tab for Selected Elements.


126

Setting What it Does

Custom

Help

Sets what will appear when you press F1 for help in this data element 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.


127

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

Figure 65. Property Editor / Other tab / Options for Layout


128

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.


129

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.


130

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.


131

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


132

� 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 types

Select all text boxes or all 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 match.

Accepts search criteria. "M.." selects all elements whose name begins with "M".

Bound To Name Text box to enter name to match.

Accepts search criteria. "/=" selects all bound elements. "=" selects all unbound elements.

Property A separate list of Properties is offered. Criteria offers choices appropriate to the selected Property.

Select all read-only elements. Select elements that have Restrictions set.

Size and Position Controls appear to specify size and position criteria.

Select all elements wider than 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.


133

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.


134

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.


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)


135

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.


136

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:


137

1. Select the pertinent element.


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.


3. Click on the arrow to the right of the Read Only box, highlight Either Yes- Grayed Out or Yes- Not Grayed Out, and release the mouse.

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

Figure 73. Changing the Read Only property of an element


138

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

Figure 74. Secret format in use.


139

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.


140

Sesame’s 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.


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:


141

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 equal to X

If X is a numeric value such as 20, then the value 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 equal to X

If X is a numeric value such as 20, then the value 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 than X to less than Y

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

>X..<=Y From greater than X to less than or equal to Y

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


142

Expression Meaning Example

<X; >=Y Less than X or Greater than or equal to Y

If X is 20 and Y is 30 then the value must be less than 20 or equal to 30 or more. If X is C and Y is F 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 character

Any character, but only one character.

?? Any two characters

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

???R Four characters ending with r

Must be a four character entry where the last 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 and ends with E

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

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

..A..B..S.. Contains A, B, and S in that order

Any entry that contains a, b, and s in that order, such as "Database."

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


143

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.


144

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.


145

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


146

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.

• Sesame’s 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, Sesame’s 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 window’s title bar, or by pressing F1 a second time to bring up Sesame’s 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.


147

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


148

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 editor’s 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.


149

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 editor’s 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.


150

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 Sesame’s 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.


151

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 Line Totals was finished before the Form Total value was calculated.

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

Figure 84. Selecting Change Program Execution Order from the Commands panel.

Figure 85. Set Program Execution Order .


152

These changes are not incorporated back into the live Sesame application until you Save Layout Design / Close Design Tab and then perform a Reconciliation.

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 86. Set Program Execution Order dialog — Numerical and Checked moved to below Add2.

Figure 87. Set Navigation Order dialog


153

• 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 in. It keeps a Change log and Advanced undo

Figure 88. Control Panels – Change Log/Advanced undo.


154

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.


155

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.


156

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


157

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


158

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

Figure 93. Designer Commands menu.


159

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.


160

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.


161

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

Figure 95. Designer menu tree – Manage a Database


162

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 transaction’s 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.


163

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.


164

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.


165

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


166

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


167

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.


168

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.


169

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 —


170

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


171

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.


172

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


173

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

Figure 102. Reconcile Options dialog.

175

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

4 — TABBED PAGES

176

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.

4 — TABBED PAGES

177

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.

4 — TABBED PAGES

178

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 element’s 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.

4 — TABBED PAGES

179

Adding additional tab pages A single tab page isn’t much use. If a form is to have tab pages at all, it needs multiple tabs. Let’s 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.)

4 — TABBED PAGES

180

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: Now’s 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 they’re 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.

4 — TABBED PAGES

181

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. Let’s 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.

4 — TABBED PAGES

182

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

4 — TABBED PAGES

183

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

4 — TABBED PAGES

184

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.

185

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.

5 - CREATING SUBFORMS

186

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.


187

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


188

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.


189

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.

Figure 4. Cities database and Cities form added.

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.

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.


190

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


191

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


192

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


193

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.


194

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.


195

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.


196

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 song’s 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 parent’s 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.


197

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.


198

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.


199

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.


200

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.

201

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

6 - ADDING AND EDITING DATA

202

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,


203

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.


204

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


205

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.


206

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


207

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.


208

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.


209

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

To use the mouse with a combo box, you can click on the Down arrow to the right 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 combo box, it is not added to the pick-list for 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.

Figure 5. Combo box with its pick-list expanded.

Figure 6. A combo box showing its entry.

Figure 7. A combo box showing a typed entry not on the list.


210

Figure 8. List box with no value currently selected.

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 9. "Green" selected in a list box.

To choose an entry in a list box, simply click on the one you want. Sesame highlights it. (See figure 9.)

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 "doesn’t matter; retrieve all values" — like leaving a text box empty.

Figure 10. Check boxes. Entries shown are No, Yes, and null.


211

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


212

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


213

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.


214

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

Switches to Search/Update tab if one is open; otherwise opens a new Search/Update tab at a retrieve spec. Current Add record is left open and unsaved.

F7 (from Search/Update Record)

Returns to the retrieve spec. Does not automatically save record. If record contains unsaved changes, you will be 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.


215

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.


216

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.


217

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.


218

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.


219

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


220

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.


221

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


222

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


223

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.


224

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

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.


225

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.


226

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.


227

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.


228

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.


229

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.

Figure 26. The Copy Spec window with just 3 LE's selected.

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

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


230

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


231

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


232

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.


233

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


234

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

Figure 28. Table spec. Only LEs with "T" will show.

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 element to include it.

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


235

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.


236

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

Figure 30. 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 summary by clicking on the 'return' button attached to it.


237

Figure 31. Summary displayed.

To display a chart

Figure 32. Displaying 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.


238

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.

239

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.

7 — NAVIGATING FORMS

240

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 Arrow

Normally moves to the next element on the form in the same order as 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

Arrow

Normally moves through the data in an element, then to the previous element on the form in the same order as Shift-Tab movement, except through element types where arrow keys select or change selection.

Right

Arrow

Normally moves through the data in an element, then to the next 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 Down

Scrolls down a long form.

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:


241

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

Enter Moves to next form element.

Down Arrow Moves to next form element.

Right Arrow Moves through data, then to next form element.

Up Arrow Moves to previous form element.

Single line

text

Left Arrow Moves through data, then to previous form element.

Enter Remains in element and moves down one line. Multi-line

text All Arrow keys Moves through data until reaching end, then acts like

an arrow key in a single-line text element.

Enter Remains in element and moves down one line. Text Editor

All Arrow keys Moves through data until reaching end, then acts like an arrow key in a single-line text element.

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 Acts the same as arrow keys in single-line element.


242


Spacebar Opens image editor window for selection of image filename.

Mouse Double-Click

Opens image editor window for selection of image filename.

Arrow Keys Moves through the different buttons. Right arrow also moves selection down and left arrow moves up.

Spacebar Selects highlighted button.

Radio

Button Group

Enter Selects highlighted button.

Mouse Click Selects/deselects list box choice.

Up/Down Arrow Keys

Moves through list box choices. Leaving the list box leaves the highlighted choice selected.

Right/Left Arrow Keys

Moves to next and previous form elements respectively.

List Box

Spacebar Toggles selection on and off.

Shift-Tab Moves to previous element.

Mouse click or down arrow

Opens dropdown list.

Shift Opens dropdown list.

Escape Cancels open dropdown list.

Up/Down Arrows

Moves through dropdown list selections.

Enter Moves forward to next form element.

Enter, with list open

Enters the highlighted list item.

Combo

Box

Tab Moves forward to next form element. If tab is pressed with the list active, tab cancels current selection and leaves entered value unchanged.


243


Mouse click Activates button.

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.

Command Buttons

Shift-Tab Navigates backward through the button to the previous form element without activating the button.

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 arrow

Moves to next element.

Check Box

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.


244

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


245

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-numeric key

Starts editing selected field of the current record, adding text to the end of the current contents.

Mouse click Moves to the selected cell (field in the selected record)

Double mouse click

Opens that cell (field) for editing, with contents selected. A 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.

247

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. Here’s 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.

8 — SEARCHING & SORTING

248

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.


249

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.


250

Autocomplete when searching.

Figure 3. Turning off Autocomplete

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.

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.


251

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


252

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


253

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


254

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.


255

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 Nov 16 2005 or November 16 2005 or 16.11.05 or 11/16/2005 etc.

November 16, 2005 Date

1236 1,236 or 1,236.00 Number

714.56 $714.56 Money

/ philadelphia Anything but Philadelphia Text, keyword


256

= Empty field All

/ = Field NOT empty All

smith;brown Smith or Brown Text, keyword

/chicago;new york

All except Chicago and New York Text, keyword

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.


257

Table 2 below shows examples using operators and ranges.

Enter This... To Retrieve... Data Type

>01 15 06 or >jan 15 2006 etc.

Dates after January 15, 2006

Date

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

02/23/06.. etc.

From February 23, 2006 onward Date

14 mar..8 jul Dates between March 14 and July 8 inclusive in the current year

Date

>wi All entries after Wi in a telephone directory, for example: Wilson, Woodruff, Wright, Zimmerman

Text, Keyword

>wi..<Z All entries after Wi but before Z in a telephone directory, for example: Wilson, Woodruff, Wright and Xum, but not Zimmerman

Text, Keyword

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.


max 5 Finds 5 records with the latest dates sorted by date.

Date


258

Min 10 Finds 10 records with the lowest numbers sorted by number.

Number

min 20 or

min20

Finds 20 records, nearest the start of the alphabet, in ascending order alphabetically.

Text

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.


259


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. and also simply "son"

Text, keyword

b..er Baker, Becker, Buckmiller, Branch Manager, etc.

Text, keyword

.. beach (Note the space)

Daytona Beach, Huntington Beach, Long Beach, etc. but not Beachview, Longbeach, etc.

Text, keyword

..west.. Westerville, Key West, newest, Rowestoft, etc.

Text, keyword

1-212.. Phone numbers or the like beginning with 1-212

Text, keyword

93.. Zip codes or the like beginning with 93 Text, keyword

..s..b..m.. Sesame database Manager, Hey - somebody's home, etc.

Text, keyword

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:


260

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


261

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

Figure 5. The Search Commands menu

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.


262

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

Current Results

Apply this search to the current result set, not the 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 Results

Remove records retrieved in this search from the 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.


263

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


264

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 [email protected]. 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 …


265

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


266

Universal search

Figure 9. Using 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.

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.


267

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


268

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.


269

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.


270

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.


271

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


272

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 1—note 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:


273

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:


274

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.


275

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.


276

Combo boxes

Figure 17. Searching a Combo Box.

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

Figure 19. Searching a radio button group.

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.


277

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


278

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


279

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.


280

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


281

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.


282

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:


283

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

Figure 23. Find on this Form on Edit menu

Figure 24. Using Find on this Form.


284

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:

Figure 25. To open Spec Manager to view saved Specs

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

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.


285

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.


286

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.



287

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.


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.


288

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.


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.


289

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


290

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 the line ^ ^Hello Matches a line that starts with "Hello"

Match the end of the line $ Hello$ Matches a line that ends with "Hello"

Match any character . b.t Matches "but", "bit", "bet", "bat", and any text starting with "b", ending in "t" with one character between,

Match a character listed in the square braces [ ] b[uei]t Matches only "but", "bet", and "bit".

Match zero or more * M.*d Matches "Maid" and "Mad" and any text that starts with "M" and ends in "d"

Match zero or one ? start.?ing Matches both "startling" and "starting"

At least one + Mo+re Matches "Moore" and "More", but not "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"

Two matches {2} Mo{2}re Matches "moore" but not "more" or "mooore"

At least 2 matches but not more than 4 {2,4} Mo{2,4}re Matches "moore", "mooore" and "moooore",

but not "more" or "mooooore"

At least 2 matches {2,} Mo{2,}re Matches "moore" and "mooooore", but not "more"

No more than 2 matches {,2} Mo{,2}re Matches "more" and "moore", but not

"mooore"


291

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 characters [:cntrl:] character in the ASCII range less than 32 or equal to 127

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

punctuation [:punct:] all characters that are neither alphanumeric or control 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


292

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.


293

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 the spec action bar and clicking on Sort [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

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


294

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.


295

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

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.

Figure 31. Sort by timestamp.


296

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.


6. Click on Close.

You can likewise clear a default sort spec by opening the Spec Manager and clicking the Clear Default button.

297

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 customer’s 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.

9 — MASS UPDATING

298

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

9 — MASS UPDATING

299

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.

9 — MASS UPDATING

300

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 also have the option to cancel the operation. (See Figure 4.)

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

Figure 3. You can run a mass update from the Results Command menu or the Mass Update spec Action bar dropdown.

9 — MASS UPDATING

301

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:

9 — MASS UPDATING

302

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

9 — MASS UPDATING

303

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 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 element’s 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…"

Figure 7. Mass update spec — moving the Last field.

9 — MASS UPDATING

304

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

9 — MASS UPDATING

305

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

9 — MASS UPDATING

306

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

9 — MASS UPDATING

307

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

9 — MASS UPDATING

308

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 active. See figure 13.


9 — MASS UPDATING

309

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.

9 — MASS UPDATING

310

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.


3. The Spec Manager displays, showing Copy as the type of spec and with the Load tab active.


5. Click on the Delete tab.

6. From the list of saved mass updates, select the one you want to delete.

9 — MASS UPDATING

311

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.


3. The Spec Manager displays, showing Copy as the type of spec and with the Load tab active.


5. Click on the Defaults tab.

6. From the list of saved mass updates, select the one you want to use as a default.


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.

9 — MASS UPDATING

312

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

9 — MASS UPDATING

313

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.

9 — MASS UPDATING

314

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.

315

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.

10 - PRINTING FORMS

316

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.

10 - PRINTING FORMS

317

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.

10 - PRINTING FORMS

318

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.

10 - PRINTING FORMS

319

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

10 - PRINTING FORMS

320

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.

10 - PRINTING FORMS

321

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.

10 - PRINTING FORMS

322

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.

10 - PRINTING FORMS

323

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.

10 - PRINTING FORMS

324

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

10 - PRINTING FORMS

325

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.

10 - PRINTING FORMS

326

Figure 9. Multiple records, printed 1 column, 3 rows.

10 - PRINTING FORMS

327

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.

329

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 you’ll 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.

11 — MERGE PRINTING YOUR DATA

330

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.


331

Merging via data export Another way to create a merge letter is to use Sesame to export what’s 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.


332

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.


333

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 you’ve 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.


334

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.


335

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 you’ve retrieved. (This could be all the records in the database.)

3. When you’ve 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.

337

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

12 — IMPORT, EXPORT & COPY RECORDS

338

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.


339

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.


340

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.


341

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.

Figure 3. The completed import spec. Five fields are to be imported in this example.

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


342

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.


343

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.


344

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


345

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


346

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


347

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.


348

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.


349

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


350

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


351

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.


352

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.


353

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

The steps are as follows:

Figure 12. Countries and More Countries.


354

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


355

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.


356

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

Figure 16. The completed Copy Spec window.


357

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 with the same name

Click on the Match Names button.

To clear all matchings Click on the Clear button.

To store these parameters and return to the Copy spec

Click on Close.

To save this Copy spec Use the Spec Manager.


358

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.


359

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.


360

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.

361

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-

13 — WORKING WITH SUBFORMS

362

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.


363

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.


364

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.


365

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


366

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.


367

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


368

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.


369

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.


370

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. The first 15 of these are shown in table view below in Figure 8.

Figure 7. Searching the Cities form.


371

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.


372

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.

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.

Figure 10. Only subform fields exported.

In the example in Figure 10, fields are exported only from the subform — one record per city.

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

"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

"Perth",1365600

"Rosario",1229800

"Springwood",0

"Sydney",3985800

"Vienna",1610100

"Yerevan",1278700


373

Figure 11 shows a third example.

Figure 11. Main form and subform fields exported.

In Figure 11, fields are exported from both the main form and the subform. There is one record per city. In other words, the information derived from 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.

"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

"Australia","Canberra",0

"Australia","Darwin",0

"Australia","Melbourne",3317300

"Australia","Perth",1365600

"Australia","Springwood",0

"Australia","Sydney",3985800

"Austria","Vienna",1610100

"Azerbaijan","Baku",1214400


374

� 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














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.


375

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














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.

377

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 computer’s 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, Sesame’s 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.

14 — CREATING AND USING MACROS

378

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 Sesame’s 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.


379

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.


380

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


381

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 Sesame’s 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, Sesame’s 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:


382

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.


383

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.


384

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.

385

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

15 — DESIGNING REPORTS

386

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


387

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.


388

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

Figure 3. Saving a Quick Report.


389

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. 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 4. Quick Report HTML output dialogue.

Figure 5. Quick Report HTML output dialogue


390

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. Sesame’s Report Writer can be found in the Designer module as a selection on Designer’s 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


391

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.


392

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 Sesame’s 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.


393

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.


394

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.


395

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


396

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

Figure 12. Tooltip on View Header Row


397

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.


398

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 element’s 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.)


399

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


400

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.


401

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.


402

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.


403

As with Sesame’s 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 Sesame’s 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.


404

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 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 22. Ignore Blank Values in Summary calculations

Figure 23. Setting a second (multiple) break in a


405

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:


406

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.

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.

Figure 24. Setting the report type to Freeform.


407

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: [person’s 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.


408

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.


409

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 you’ll 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.


410

3. In the second View’s 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.


411

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.


412

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.


413

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


414

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.


415

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.


416

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


417

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.


418

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

Figure 37. Quick Preview Mode in the reports designer control panel.


419

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

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.

Figure 38. Opening Reports list after retrieving data in preview. Note that the vertical scroll bar indicates more below. Scroll down to see list.


420

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.

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.


421

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.


422

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.


423

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 person’s 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 doesn’t show, but it must be in the report layout. Derived columns are created using Sesame’s Program Editor. To make a derived column, you create a Value Box layout element that is unbound (not linked to any


424

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.


425

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.


426

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

427

Section 16

Using the Application Utilities The Application Utilities Menu

Sesame’s 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.

16 — USING THE APPLICATION UTILITIES

428

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 won’t 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


429

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 Sesame’s 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.


430

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.


431

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 bar’s 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 Sesame’s 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 Designer’s 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.


432

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.

433

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, or Data Entry.

User Levels determine how much access 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 specific groups.

Each user must be assigned to a group. 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.

17 — SECURING YOUR APPLICATIONS

434

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.


435

• 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

Results Commands

After creating a result set, access to Results Commands is as shown in Table 2.

Figure 1. Application Utilities menu — seen by Administrators only.


436

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.


437

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


438

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.

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

Figure 2. Security Manager — Groups tab with two new groups.


439

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


440

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.


441

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, you’ll 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.


442

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


443

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


444

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.


445

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


446

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.


447

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


448

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.


449

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 don’t 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.


450

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

451

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.

18 — WEB CAPABILITIES

452

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:


453

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.


454

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.


455

<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> </TD><TD> </TD>

</TR>

<TR>

<TD><input TYPE="SUBMIT" NAME="b1" VALUE="Find

Matches"></TD><TD> </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.


456

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


457

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.


458

<html>

<head>

</head>

<body>

<p>Matching Member Records</p>

[[SESAME_START_REPEAT]]

<p>

[[First]] [[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:



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.


459

Figure 3. Dynamic web page created from live Sesame data - result.html


460

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="searchfields" VALUE="KEY">

<P>Please enter your Key.</P>

<TABLE>

<TR>


461

<TD class="copy">Key</TD><TD><input type="text" size="20"

name="KEY"></TD>

</TR>

<TR>


</TR>

<TR>

<TD class="copy"><input TYPE="SUBMIT" NAME="b1" VALUE="Find My

Listing"></TD><TD> </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.


462

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>


<form name="kmp" method="post" action="postupdate.html">




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


463

</TR>

<TR>

<TD>ZIP</TD><TD><input type="text" size="20" name="ZIP"

value="[[ZIP]]"></TD>

</TR>

<TR>


</TR>

<TR>

<TD><input TYPE="SUBMIT" NAME="b1" VALUE="Submit


</TR>

</TABLE>

</form>


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


464

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.


465

<html>

<head>

</head>

<body>

<p>Listing Update Confirmation</p>


<p>


[[Company]]<br>

[[Add1]]<br>


<hr>

</p>


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


466

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


467

</TR>

<TR>


</TR>

<TR>

<TD><input TYPE="SUBMIT" NAME="b1" VALUE="Submit


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


468

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>


469

<body>

<p>New Listing Confirmation</p>


<p>


[[Company]]<br>

[[Add1]]<br>


<hr>

</p>


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


470

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.


471

@(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


472

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

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.

Figure 10. ClientList report emailed automatically


473

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.


474

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.


475

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.

477

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.

19 — TROUBLESHOOTING

478

Figure 3. Server Admin in Client-Server Mode

Figure 4. Server Admin in standalone mode


479

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


480

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.



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


481

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.


482

Figure 9. Shut down a Sesame server and disconnect all clients

Figure 10. Unload an Application

483

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.

APPENDIX 1 — NETWORK ADMINISTRATION

484

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 Department’s 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


485

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.


486

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


487

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.


488

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.


489

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



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.


490

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.


491

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


492

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.


493

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


494

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


495

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.


496

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.


497

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 User’s 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.


498

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


499

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"


500

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 computer’s 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.


501

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.


502

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


503

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.


504

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


505

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.

507

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 server’s 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.

APPENDIX 2 — ENVIRONMENT VARIABLES

508

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.


509

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 computer’s 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 doesn’t 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.)


510

Figure 1a. The Windows XP System Properties Advanced tab with the Environment Variables button.


511

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


512

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.


513

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 doesn’t 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"

515

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 don’t really know how it works and they can’t 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.

APPENDIX 3 — PHILOSOPHY

516

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 won’t 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 don’t have that property and deselect them.

APPENDIX 3 — PHILOSOPHY

517

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. What’s 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 Sesame’s 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 Sesame’s choices. Ultimately, what’s in it for you is whatever you choose to make out of it.

519

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

APPENDIX 4 — ADVANCED CONCEPTS

520

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.


521

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.


522

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


523

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 form’s 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 isn’t 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 song’s 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.)


524

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 song’s 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 parent’s key field and the child key field must match.


525

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 parent’s 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.


526

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 other’s hands. The Neville parents recognize their own children because they are holding the eldest child’s hand. The eldest child holds the next oldest child’s 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.


527

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.


528

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 server’s 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 computer’s 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.


529

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.


530

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 server’s 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 client’s 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.


531

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, Sesame’s 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


532

network administrator to install SSL encryption/decryption on both the client computers and the server. The SSL encryptor needs to intercept Sesame’s 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 administrator’s 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 other’s 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 engine’s 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 client’s 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


533

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


534

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 isn’t 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, Sesame’s 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.


535

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.


536

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 Sesame’s 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 Sesame’s 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 Sesame’s continued use and development.

537

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

539

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 Update, Table View

Permanently deletes a record with user 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, Report Writer Property Editor

Fills in Current values for certain layout element settings such as Label, Name, Initial Value, Restrict values, tooltip, Custom Help.


Dittos (copies) into the current field the value of the same field from the record last entered.

Shift-F5 Add Data, Search Update, Table View

Dittos (copies) a whole record. It overwrites the entire current record with the record last entered (with user confirmation).

Ctrl-F5 Add Data, Search Update, Table View

Inserts the current date into the selected field.

Alt-F5 Add Data, Search Update, Table View

Inserts the current time into the selected field.

F6 Add Data, Search Update, Table View, Designer Property Editor, Report Writer Property Editor

Opens expanded field editor. Closes expanded field editor, saving changes, if it is already open.

Shift-F6 Add Data, Search Update Opens current result set in table view

Ctrl-F6 Search Update Switches from Update to Add mode

APPENDIX 6 — SHORTCUT KEYS

540

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 View

Undo current record. Restores the record back to the state it was in when you opened it.

Ctrl-F7 Search Update, Table View

Undo current Field. Restores the field back to the state it was in when you opened the record.


Forces all On-Form-Change programming to calculate.


Saves and moves from current record to previous record. In a subform moves to previous record in same subform

Ctrl-F9 Add Data, Search Update, Table View

Saves and moves to previous record. In a subform, saves changes to main form and subform and moves to the previous main form record.


Saves and moves to next record. If on the 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.

541

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.

APPENDIX 7 — SESAME.INI FILE

542

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


543

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


544

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


545

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


546

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.


547

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


548

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


549

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


550

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


551

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


552

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 [email protected] ... SCommand Open: Customers.db SCommand Database: Customers SCommand Query: !Key=<1000 SCommand Report: MyReport SCommand Reply To: [email protected] 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 [email protected]. 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


553

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: [email protected] 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

555

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.

APPENDIX 8 — STARTUP SWITCHES

556

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


557

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


558

-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


559

-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□-client□SERV01□-system_id□HAZEL□Data\Samples\Countries.db

(The symbol □ is used to indicate a space.)

561

Index

! (mandatory restriction), 126, 142 .DAT (File extension), 23 .DB (File extension), 23 .DSR (File extension), 23 .DDT (File extension), 23 .DSR (File extension), 62 .DSR (File extension), 63 .DB (File extension), 63 .DSR (File extension), 63 .DB (File extension), 64 .DSR (File extension), 64 <, as LE start character, 80 . (period), as image path, 159 .DB (File extension), 168 .DSR (File extension), 168 ;, in searches, 255 /, in searches, 255 =, in searches, 255 /=, in searches, 255 .. (in range searches), 256 ?, in searches, 258 .. (in 'wildcard' searches), 258 \ , in searches, 268 ], in searches, 268 &, in searches, 269 `, in searches, 269 ~, in searches, 269 {}, in searches, 281 ¦, in searches, 282 \n (Carriage return, exporting), 352

A Abnormal termination, 480 About Sesame (Help menu), 36 Add Data menu, 45 Add New Database, 74 Adding a Layout Element to a Tab Page, 177 Adding a new field (Field Manager), 161 Adding a new record, 204 Adding a Tab Group, 176 Adding and editing pictures, 212 Adding layout elements to a form, 78 Adding static text, 77 Adding tab pages to a tab group, 179 Administrative password, 496 Administrator login, 477, 480, 489

Administrator, security, 435 Advance Record, 50 Advanced Concepts, 519 Advanced Element Selector Control Panel, 131

Advanced searches, 259 Advanced Undo, 153 Aligning layout elements, example, 181 Alignment, changing, 116 allow file, 500 Allow IP addresses, 500 Alternate form, switching to, 155 Application Copying a complete application, 431 Default formats for, 124 Previewing, 105 Sample design, 64

Application Documenter, 165 Application Menu, 43 Application menu, using, 49 Application Programming, 159 Application Property Manager, 158 Application Settings, 119 Application Title, 159 Application Utilities, 427 Application, merging another, 167 Application, new, 66 Application, Open on startup, 559 Application, setting properties for, 158 Application, unloading, 493 ASCII Database, 34, 68 ASCII Export dialog, 346 ASCII file, 337, 344 ASCII files, sorting, 344 ASCII import, 338 Asterisks, Secret Input, 138 Attaching retrieve and sort specs, 416 Attachment, 57 Attachment, toggle, 53 Attribute Table, 165 Autocalc, setting for a form, 127 Autocomplete, 35, 207, 224 Autocomplete when searching, 250 Auto-selection, 207

INDEX

562

B Backtick (`), in searches, 269 Backup Application, 427, 428, 495 Binding, 125 Blank field, searching for, 255 Blink, cursor, 35, 556 Bookmark a Record, 217 Boolean elements, adding, 81 Boolean field, entries permitted, 95 Boolean formatting, layout element, 121 Bound to (layout element), 125 Box element, defined, 84 Boxes (static), 84 Boxes (text). See Text boxes Buffer, 227 Buffer (copying a record), 52

C Calculate form, 51 Calculate Programming (Autocalc), 127 Cancelling a Mass Update, 301 Canvas (area off form), 105 Capitalization in searches, 252 Case sensitivity in searches, 252 Case-sensitive searches, 269 Change Log, 153 Charts, creating, 235 Check box element, defined, 84 Check box, adding, 87 Child records, 185 Clearing a retrieve spec, 254 Client, 486 Client-server, 483 Clipboard, using when editing, 225 Close (File menu), 34 Close Form Without Saving, 51 "-closed" startup switch, 43 Color Changing form color, 115

Color palettes, 115 Colors, changing, 115 Colors, custom, 115 Colors, setting, 115 Column width export files), 350 Combination Freeform/Columnar reports, 409

Combo box element, defined, 84 Combo box, adding, 85 Combo box, editing choices, 86 Comma Separated Values, 348

Command Area - Open/Close, 36 Command button element, defined, 84 Command button, adding, 89 Command line options, 486 Command line switches, 555 Command line utilities, 537 Commands panel, 110 Configurations, network, 483 Connections, 488 Constructs regex() and qanda(), 292 Control Panels, 109 Converting Q&A databases, 30 Copy (Edit menu), 34 Copy a layout element, 99, 100 Copy an application, 431 Copy and paste records, 227 Copy dialog, 354 Copy form to buffer, 52, 227 Copy Forms to Buffer, 52 Copy records (Results commands menu), 53 Copy Spec, 229, 354 Copying a database. See Merge Application Copying a Designer file, 432 Copying a form (Layout Manager), 164 Copying a layout (Layout Manager), 164 Copying a report (Layout Manager), 164 Copying a single record, 52, 227 Copying fields and records, 226 Copying Layout elements, 99 Copying LE formatting, 97 Copying Records, 227, 228, 352 Difference Q&A, 353 Match names, 355

Creating a New Sesame Application, 68, 73 Creating an applictation from an ASCII Database, 68

Creating an applictation from an XML Database, 70

Cross-platform, 21 CSV file, 348 Ctrl-F10, 51 Ctrl-F5, 53 Ctrl-F6, 51 Ctrl-F7, 52 Ctrl-F9, 51 Currency elements, adding, 81 Currency formatting, layout element, 122 Current date, inserting, 53 Current time, inserting, 53 Cursor blink, 35, 556 Custom colors, 115

INDEX

563

Custom Format, 119 Custom help, 31 Custom help, adding, 147 Custom help, described, 146 Custom tooltips, 149 Customizing Forms, 133 Cut (Edit menu), 34 Cut/Copy/Paste, 225

D .DAT (File extension), 23 Data entry shortcut keys, 213 Data entry templates, 144 data source, 331, 332 Data types, 201 Data typing, 139 "Database .. failed to open" message, 480 Database, defined, 23, 65 Database, deleting, 161 Database, merging another, 167 Database, new, 74 Database, Open on startup, 559 Database, renaming, 127, 161 Database, Searching and Sorting, 247 Databases, opening recently used, 27 @Date (not valid as initial value), 126 Date (current), inserting, 53 Date elements, adding, 81 Date field, entries permitted, 95 Date formatting, layout element, 120 Date retrievals, 254, 255, 257 .DB (File extension), 23, 168 .DDT (File extension), 23 Default display format, 159 default formats, 123 default formats for an application, 124 Default retrieve spec, 287 Default sort spec, 296 Delete (Edit menu), 35 Delete a database (trim application), 429 Delete All Data Records (from Designer file), 166

Delete duplicate records (Results commands menu), 54

Delete Record, 51 Deleting a database (Field Manager), 161 Deleting a field (Field Manager), 161 Deleting a form (Layout Manager), 164 Deleting a layout (Layout Manager), 164 Deleting a record, 217

Deleting a report (Layout Manager), 164 Deleting layout elements, 101 Deleting static text, 78 Deleting tab pages, 182 Delimit All Fields, 349 Delimit Strings, 349 Delimited file. See ASCII file Delimiter, exporting, 349 Delimiter, importing, 338 deny file, 500 Derived columns, in reports, 423 Design New Application, 428 Designer, 23, 61 Copying a Designer file, 432 Fields & layout elements defined, 65 Starting as a standalone application, 61

Designer file, 62, 63, 168 Delete All Data Records, 166 Previewing, 106

Designer, defined, 61 Designer, starting, 30, 61, 66 Directional Navigation, 35, 153 Disconnect, 491 Ditto, 213 Ditto Current Field, 52 Ditto Current Form, 52 Ditto Field/Record, 226 Documentation, 22, 24 Drill-down search, 272 .DB (File extension), 63, 64 .DSR (File extension), 23, 62, 63 .DSR (File extension), 63 .DSR (File extension), 64 .DSR (File extension), 168 .DSR file, 169 DSR file, defined, 67 Duplicate Me, 99 Duplicate Records, 218 Deleting, 218 Notes on removing, 220 Removing temporarily, 218 Searching for, 221, 223

Duplicate records, deleting (Results commands menu), 54

Duplicate Selected Elements, 100 Duplicates (removing from results), 221 Dynamic sort, 294

E Edit Window, 58

INDEX

564

Editing Boolean elements, 203 check box, 210 combo box, 209 Cut/Copy/Paste, 225 Data entry shortcut keys, 213 Date elements, 202 Deleting a record, 217 Ditto, 213 Expanded field editor, 208 Image editor, 212 image field, 211 Keyword elements, 203 list box, 209 Making Corrections, 232 Money (currency) elements, 202 Multi-line text elements, 207 Number elements, 202 radio button group, 211 Saving a record, 216 special layout elements, 208 Table view, 233 Text elements, 202, 206 Time elements, 203 Undo, 231, 232 Undo field, 232 Undo form, 232 Using Forms, 204 Yes/No elements, 203

Editing static text, 78 Element. See Layout Element(s) Element Example Palette, 82 Email retrieval via Sesame Web Server, 472 Embedded Dialogs, 57 Empty field, searching for, 255 Envelopes, 331 Environment Variables, 507 Error log, (on importing, 343 Esc, 51 Escape, 51 Example Palette, 82 Execution Order, Programming, 150 Exit (File menu), 34 Expanded field editor, 208 Export (for merge printing), 331 Export Application to XML, 430 Export Data (Results commands menu), 54 Export Design to XML, 167, 359 Export Layouts to XML, 359 Export spec, 344 Exporting

ASCII options, 347 carriage returns, 352 Custom Separator, 348 Delimited ASCII file, 344 Delimiter, 349 Export dialog, 346 F (Fixed width), 350 Field Name Header, 349 File format, 344 Fixed, 350 Fixed ASCII & truncating values, 350 How to export, 344 Ignore Fixed/Max Lengths, 350 M (Max num characters), 350 Max, 350 \n (carriage return), 352 O (variable width), 350 Open, 350 quotes around text, 344 separator, 347 Sorting, 344 Subform data, 372 tab separator, 348

Exporting Data, 343 Exporting data from subforms, 352 Exporting multi-line text fields, 352 Extension, file, 23, 62, 64

F F (Exporting option), 350 F1, 53 F10, 262 F10 key, 50, 214, 240, 245, 365, 540 F11, 52 F3, 51 F5, 52 F5 (Current value), 133 F6 (Field editor), 133 F6 Edit Window, 58 F6 expanded field editor, 208 F7 key, 214, 271, 540 F7 Key, 540 F8 (Calculate), 51, 127 F9, 50 "Failed to open" message, 480 Field Manager, 161 Adding a new field, 161 Changing a field type, 161 Deleting a database, 161 Deleting a field, 161

INDEX

565

Renaming a database, 161 Renaming a field, 161

Field Name Header, 349 Field name, changing, 161 Field type, changing (Field Manager), 161 Field, adding a new, 161 Field, defined, 24, 65 Field, deleting, 161 File extension, 23, 62, 64 File New (toolbar button), 36 File Open (toolbar button), 36 File Save (toolbar button), 36 Files, Sesame, 63, 64 Find First Match, 251 Find on this Form, 283 Find on This Form, 35 First Record (go to), 36 Fixed ASCII export and truncating values, 350

Fixed ASCII import, 339 Focus, 49 Focus, defined, 41 Fonts, changing, 116 Form compilation, 505 Form customization, other, 150 Form Design, Keystrokes, 83 form letter, 329 Form Navigation, 239 Form, startup, 156 Formatting layout elements, 114, 120 Formatting report elements, 114 Forms Canvas, 105 Changing color of, 115 Changing the Appearance of, 109 Copying, 164 Creating a new form, 74 Customizing, 133 Default Formats, 123 Deleting, 164 Improving appearance of, 133 Laying out a form, 75 Navigation, 212 Opening a form, 28 Redesigning, 109 Renaming, 164 Resizing, 104

Forms, relinking, 155 Forms, Resizing, 77 Forms, switch to alternate form, 155 Freeform reports, 405

Full-Feature Reports, 390 Function Key Menu, 36, 55

G Getting Started, 23 Global code, 303 Global Values List Manager, 167 Global Values, replacing when reconciling, 173

GoTo (use of deprecated), 152 Grayed out (Read-only) elements, 137 Grid, in form design, 97

H Height, changing, for a form, 104 Height, changing, for Layout Elements, 103 Help, 53 Context-sensitive, 31 Custom help, 31 Custom help appears automatically, 32 Tooltips, 32 Using, 31

Help Menu, 36 Hidden layout elements, 138 Hide macro results (view menu), 35 Hide menu tree, 36, 43 Hierarchical import, 21, 373 HTML (printing form(s) to), 323 HTML files, 508 HTML output files, 425 HTML, printing Form to, 52

I Icons (toolbar), 36 IGNORE COLUMN, 340 Ignore Fixed/Max Lengths, 350 Image box, adding, 90 Image editor, 212 Image elements, adding, 81 Image field element, defined, 84 Image field, entries permitted, 96 Image files, path to, 159 Image labels, 90 Image path, 159 Image searches, 277 Image, as a LE label, 90 Import a database. See Merge Application Import Data (Results commands menu), 54 Import errors, 343

INDEX

566

Import Layouts from XML, 360 Import Q&A, 34, See Translate Q&A Import spec, 339 Importing Blank fields, 338 Fixed ASCII, 339 How to import, 339 IGNORE COLUMN, 340 Standard ASCII, 339 Subform data, 373

Importing Data, 337 Importing data into subforms, 373 Importing Q&A databases, 30 Importing subform data, 198 Indexed fields, 127 Initial values, 126 Initial values, programming alternative, 126, 136

Insert Current Date, 53 Insert Current Time, 53 Installation Guide, 25 Installing Sesame, 25 Internet, Sesame on the, 499 Interrupting a Mass Update, 301 Introducing Sesame, 21 Invalid LE names, 79, 135 Inverted Search, 265 Invisible layout elements, 138 IP addresses, 500, 501 Allowing, 500 Restricting, 500

J Just in Time Compilation, 505

K Keyboard shortcuts, 539 Keystrokes (navigation), 239 Keyword elements, adding, 81 Keyword field, entries permitted, 95 Keyword searches, 267

L Label Alignment, 116 Label, changing an element's, 133 Last Record (go to), 36 Layout Element Auto-selection, 207 Bound, 66

Bound to, 125 Defined, 24, 65, 78 Unbound, 66

Layout Element Adder, 81 Layout Elements Adding a multi-line text box by typing on the form, 80

Adding by Typing on the Form, 78 Adding data elements, 78 Adding multiple, 80 Adding to a Tab Page, 177 Adding with the layout element adder, 81 Adjusting position incrementally, 118 Adjusting size incrementally, 118 Advanced element selector, 131 Aligning to each other, 116 Binding, 94, 126 Boolean formatting, 121 Border style, 116 Box style, 116 Centering on form, 116 Change label, 133 Change LE name, 134 Changing Color, 115 Changing fonts, 116 Changing label alignment, 116 Changing text alignment, 116 Changing text size, 116 Copying, 99, 100 Currency formatting, 122 Custom help, adding, 147 Date formatting, 120 Deleting, 101 Format settings, 119 Formatting, 120 Formatting multiple elements, 123 Grayed out, 137 Hidden, 138 Invalid names, 79, 135 Invisible, 138 LE names & labels, 79 LE names & programming, 79 lower case formatting, 120 Making same size, 118 Money formatting, 122 Moving, 102 Multi-line text boxes, creating, 116 Naming rules, 79 Number formatting, 122 Position of elements, 116 Position of labels, 116

INDEX

567

Properties list, 165 Read-only, 137 Relabelling, 98 Relative alignment, 116 Relative sizing, 116 Renaming, 134 Resizing, 103 Restrictions, 139 Rubber-banding, 101, 102 Rules for naming, 79 'Secret formatting', 138 Selecting multiple, 101, 102 Setting formats for, 120 Sizing, 103 Sizing to match, 118 Spaces in LE names, 79 Spacing of elements, 116 Templates, 144 Time formatting, 121 Tooltips, adding custom, 149 Types of, 77, 83 Unique, 138, 143 UPPER CASE formatting, 120 Using the different element types, 85 Visibility, 138 Working with multiple, 101, 118 Yes/No formatting, 121

Layout Manager, 163 Copying a layout, 164 Deleting a layout, 164 Renaming a layout, 164

Layout Settings, 119 Layout, copying, 164 Layout, defined, 23, 65 Layout, deleting, 164 Layout, renaming, 164 Layouts, Managing, 163 LE. See Layout Element(s) License file, location of, 499 LICENSE_PATH, 499, 507 Line element, defined, 84 Linking, types of, 523 Linux, 21, 25 List box element, defined, 84 List box, adding, 86 List box, editing choices, 86 Load a macro, 35 Lock/Unlock an application, 502 Locked, database, 480 Log File, 502 Log(s), 493

M M (Exporting option), 350 Machine name, 486 Macro indicator, 378 Macro visibility (view menu), 35 Macros, 377 Alerts, 378 Autoloading, 555 difference Q&A, 312, 377 Human readable macro files, 381 Loading a macro, 380 Macro files, 381 Macro visibility, 379 Nested macros, 381 Playing back a macro, 379 Recently-used Macro List, 383 Recording a macro, 378 Saving a macro, 380 Series Counter, 382

Macros vs. programming, 381 mailing labels, 331 Mailmerge, 329, See also Merge Printing Main Advance Record, 51 Main Previous Record, 51 Make Like Me, 97 Managing a Database, 161 Managing fields, 161 Managing Layouts, 163 Mandatory restrictions, 126 Mass Delete (Results commands menu), 53 Mass update, 297 Backup first, 298 by other means, 314 Continuous mode, 300 Default mass update Spec, 311 Endurance of the mass update spec, 314 Global code, 303 IF/THEN programming, 313 in a multi-user environment, 314 Interactive, 300 Invalid programming, 306 Mass Update Spec, 298 network considerations, 314 Order in which records are updated, 313 overview, 297 Program editor, 302, 304, 305 programming execution order, 302 Programming in just one element, 303 programming statement, 299 Q&A and mass updates, 312 Saved mass update spec, using, 309

INDEX

568

Saving mass update specs, 307 Saving the programming, 306 security, 312 Skip record(s), 300 Sort order of records, 313 Spec Manager, 307 Testing your programming, 306 Translated Q&A mass updates, 313

Mass Update (Results commands menu), 54 Mass update programming, 299 Mass Update Spec, 298, 301 Mass Update, Interrupting, 301 Max and Min, in searches, 257 maximized window, 56 Memory Menu, 226 Menu Bar, 33 Menu button element, adding, 89 Menu button element, defined, 85 Menu Buttons, searching, 277 Menu Tree, 41 Menu tree - Open/Close, 36 Menu Tree, defined, 38 Menu Trees, Single Level, 42 Merge Application, 167, 428 Merge documents, 329 Merge fields, 332 Merge File Print, 52, 54 Merge Printing, 329 Merge Printing, using WordMerge, 334 Merging two applications, 429 Merging via data export, 331 Message Log, 153 Microsoft® Word, 331, 333 Migrating to Sesame, 21 Mode indicator, 37 Money elements, adding, 81 Money field, entries permitted, 95 Money formatting, layout element, 122 Mouse Center button, 215 Left button, 215 Right button, 215 Using, 215

Moving around a form, 239 Moving around in table view, 244 Moving Between Elements in Designer, 96 Moving layout elements, 102 Moving Tab Groups, 184 Multi-line text element, setting, 116 Multiple Servers, 484

N Name, changing an element's, 134 Naming Layout Elements, rules for, 79 Naming multiple elements, 126, 136 Natural vs. relational linking, 523 Navigating around a form, 212 Navigation, 239 Arrow keys, 240 End, 239 Enter key, 239 Home, 239 Moving between main form and subforms, 243

Multi-line text, 241 Tab key, 239 Table view, 244 Text Editor, 241

Navigation keys, 239 Navigation menu, 50 Navigation Order, 152 Navigation Order, resetting, 96, 153 Navigation, Directional, 153 Nested macros, 381 Network Administration, 483 Network administration tips, 498 Network Communications, 503 Network configurations, 483 Network Setup, 485 New (File menu), 34 New Application, 66, 428 New database, 74 New form, 74 Next Matching Record, 51 Next matching record in current results, 273 Next Record (go to), 36 NOT empty, searching for, 255 NOT, in searches, 255 Notification tab, 491 NotifyForm() programming (alternative to restrictions), 143

@Number (not valid as initial value), 126 @Number, setting, 160 @Number, replacing when reconciling, 172 Number field, entries permitted, 95 Number formatting, layout element, 122 Number of Records (toolbar), 36

O O (Exporting option), 350 Open (Exporting), 350

INDEX

569

Open (File menu), 34 Open a database, 26 Open a form to search, 205 Open an application, 26 Open an application automatically, 559 Open an database automatically, 559 Open command area, 36 Opening a form, 28 Opening a form to add data, 204 Opening Sesame, 25 Operational mode indicator, 37 Optimization, 504, 505 Optional restrictions, 126 OR, in searches, 255, 259 Order (Navigation), 152 Order (Program Execution), 150 Order of tab pages, changing, 181 Orphan records, 366 "Other" Tab (Property Editor), 125

P Page Down, 240 Page marker, adding, 93 Page marker, defined, 85 Page Up, 240 Parent records, 185 Password Controls, 446 Password, minimum length, 446 Passwords, changing, 450 Passwords, Secret Input, 138 Paste (Edit menu), 34 Paste buffer to form, 52 Paste buffer to forms, 52 Paste Form to Buffer, 228 Paste records, 227 Philosophy, 515 Picklists (alternatives to restrictions), 126 Picture elements, adding, 81 Picture fields, editing, 211 Picture searches, 277 Pipe symbol, in searches, 282 Playback macro, 35 Point size. See Fonts Ports, 486 Preloading applications, 498 Preview mode, 105 Previewing a report, 418 Previewing the application, 105 Previous Record, 50 Previous Record (go to), 36

Print Form, 51 Print Form to HTML, 52 Print Forms, 54 Appearance of the printed record, 322 in Add mode, 322 in update mode, 316 More ways to print, 327 Multiple pages per record, 320 Multiple records per page, 319 Printing table view, 324 Table View, 325 to HTML, 323

Print Forms Dialog Box, 317 Printing an individual record, 317 Printing commands, 51 Printing Commands (Menu), 54 Printing Forms, 315 PrintString as alternative, 327

Printing subforms, 368 Printing table view, 324, 325 Printing the result set, 317 Printing, ways to print data, 315 Program Application, 159 Program Editor, 150 Program Execution Order, 150 Program form, 150 Program layout, 150 Program Report, 150 Programmed data entry restrictions, 142 Programmed retrieves, 280 Programmed retrieves, speeding up, 282 Programming Guide, Sesame, 22 Programming, mass update, 299 Programs, Sesame, 23 Property Editor, 114 Alignment, changing, 116 Apply all settings, 118 Autocalc, 127 Boolean element formatting, 121 Border style, 116 Box style, 116 Color palettes, 115 Color tab, 115 Currency element formatting, 122 Current settings not shown, 114 Date formatting, 120 Font & size, changing, 116 Format settings, 119 Format tab, 119 Initial values, 126 Look tab, 116

INDEX

570

Money element formatting, 122 Multi-line text boxes, creating, 116 Number element formatting, 122 Other Tab, 125 Position of elements, 116 Position of labels, 116 Position tab, 116 Relative alignment, 116 Relative sizing of elements, 116 Rename Database, 127 Restrictions, 126, 140 Spacing of elements, 116 Text tab, 116 Time element formatting, 121 Yes/No element formatting, 121

Property Editor vs. Property Viewer, 112 Property Viewer, 112 Protected Application (Security), 445 Proxy, 528

Q Q&A Converting database into Sesame, 34 Database defined, 63 Differences in restrictions, 126 GoTo (use of deprecated), 152 Mass updates, 312 Restrictions as picklists, 140 Searching differences, 251 Speedy fields, 127 Time not stored with seconds, 53 Translated mass updates, 313 Translation into Sesame, 34 Weaker data typing, 139, 202

Q&A (Translate) (File menu), 34 Q&A Database Translation Guide, 22 Q&A drawing characters, removing, 105 Q&A line draw characters, removing, 105 Q&A phonetic search, 270 Q&A programmed retrieve differences, 281 Q&A Translation, 70 Q&A Translation Errors, 477 Q&A Translation Options, 71 Q&A Translation, Managing Errors, 72, 477 Q&A Translation, programming, 72 Q&A Translation, Reports, 72 Quick Report Spec, 386 Quick Reports, 386 Quick Reports, saving, 388 Quick Start Menu, 36, 39, 41

Quick-Start Tutorials, Sesame, 22

R R button (in import spec), 341 "R" setting, naming multiple elements, 126, 136

Radio button group element, defined, 84 Radio button group, adding, 87 Ranges, in searches, 256 Read-only elements, 137 Recently Opened File list, 27 Reconcile, 62, 63, 170 Reconcile Options, 171 Reconcile Options dialog, 173 Reconciling, 170 Record Macro, 35 Record Navigation (Toolbar), 36 Record set. See Result set Record, bookmarking, 217 Record, defined, 24, 65 Record, Next matching Record, 273 Records Copying, 226, 228 Ditto record, 226

Records, Searching, 247 Record-to-record navigation, 216 Redesign Current Application, 66, 168, 428 Regex, 288 Regional Options, 203, 254 Regional settings, 120, 202 Regular expressions, 288 Relabel layout element, 98 Relational Linking, 523 Relational vs. natural linking, 523 Relationships, 185 Relink Form, 155 Remove (records). See Mass Delete Remove a database, 429 Remove Duplicates from Results, 221 Remove Duplicates from Results (Results commands menu), 54

Remove from results, 51, 274 Removing. See Deleting Rename Application, 163 Renaming Database, 127 Layout Elements, 134

Renaming a database (Field Manager), 161 Renaming a field (Field Manager), 161 Renaming a form (Layout Manager), 164

INDEX

571

Renaming a layout (Layout Manager), 164 Renaming a report (Layout Manager), 164 Renaming tab pages, 180 Report Creation Wizard \b, 412 Report Writer. See Reports REPORT_PATH, 507, 509 Reports, 385 Adding layout elements, 397 Advanced Report Features, 420 Attaching retrieve and sort specs, 416 Columnar reports, 396 Combination reports, 409 Combination reports, typical example, 411

Copying, 164 Default Formats, 123 Deleting, 164 Derived columns, 423 Freeform reports, 405 full-feature reports, 390 HTML output files, 425 Ignore blank values, 404 Introduction, 385 Month and year breaks, 405 Moving elements, 401 Multiple breaks, 404 Naming reports, 391 No repeat option, 405 Page Headers and Footers, 404 Preview mode, 403 Previewing a report, 418 Printing options, 405 Property Editor & Viewer, 402 Quick Report spec, 386 Quick reports, 386 Reconciling a report, 420 Relocating HTML output files, 426 Renaming, 164 Report Creation Wizard, 412 report interface, 392 Report sections, 396 Running a report, 420 Saving a report, 418 Selecting elements, 401 Subreport, 394 Summary totals and breaks, 421 Typical report example, 392

Reports, location of, 508 Reports, running, 54 Reserved Word, 79 Reset Navigation Order, 96, 153

Resizing layout elements, 103 Resizing tab groups, 183 Resizing the form, 77, 104 Restrict IP addresses, 500 Restrict network connections, 500 Restrict values, 139 Restrictions, 126, 139 ! (make mandatory, 126 Allow blank field, 126 Checked on saving record, 126 Different to Q&A, 126 Do not use as picklists, 126 Mandatory, 126 Optional, 126

Restrictions, applying, 140 Restrictions, Mandatory, 141, 142 Restrictions, Optional, 141 Restrictions, programmed, 142 Result set, 251 Result Set, moving through, 251 Results Commands menu, 53 Retrieve spec, 248 Retrieve spec programming, 280 Retrieving. See Searching Reveal menu tree, 36 Right Click Menu, 97 ROOTDIRS.INI, 499 Rubber-banding, 101, 102 Rules for naming Layout Elements, 79 Run macro, 35 Runtime, Sesame, 23

S s_conf, 499 Save (File menu), 34 Save As (File menu), 34 Save As New Application, 169 Save Global Settings, 541 Save macro, 35 Save Record, 51 Save Record and Close Form, 51 Saved Specs, replacing when reconciling, 173

Saving a record, 216 Saving a report, 418 Saving Searches for re-use, 284 Saving Your Design as a Sesame Application, 108

Scoot Mode, 96 Scroll region, adding, 91

INDEX

572

Scroll region, defined, 85 sDesigner. See Designer, See Designer Search Commands, 262 Search criteria essentials, 254 Search in Current Results, 272 search logic, 260 Search, phonetic, 269 Search, soundex, 269 Search/Update menu, 44 Searching, 247 &, 269 \ (literal), 268 * (wildcard character). See .. .. (ranges), 256 .. (wildcard character), 258 /, 255 /=, 255 ;, 255 ? (wildcard character), 258 ], 268 `, 269 {}, 281 ~, 269 ¦, 282 = (empty field), 255 Add to Current Results, 271 Advanced searches, 259 AND across fields, 260 Arithmetic operator examples, 256 Autocomplete, 250 Backtick (`), 269 Basic search criteria examples, 256 Basic searches, 247 Blank field, 255 Browser-type Searches, 263 Case sensitivity, 252 Case-sensitive searches, 269 Check boxes, 275 Clearing a retrieve spec, 254 Combo boxes, 276 Date fields, 254 Dates, 254, 255, 257 Default retrieve spec, 287 Deleting a saved retrieve spec, 287 differences Q&A, 251 Differences Q&A, 251 Drill-down search, 272 Either/Or, 255 Empty field, 255 Examples of special search characters, 270

Field types, 254 Find First Match, 251 for images by filename, 279 for images graphically, 278 for pictures, 277 French braces, 281 Image searches, 277 Inverted Search, 265 Keyword searches, 267 List boxes, 276 Main records with no subrecords, 371 Max and Min, 257 Meet ALL restrictions, 260 Meet Any restriction, 260 Menu Buttons, 277 Next matching Record, 273 NOT, 255 NOT empty, 255 Operators and ranges examples, 257 OR, 255 OR across fields, 260 Performing a new search, 253 Pipe symbol, 282 Programmed retrieves, 280 Programmed retrieves, performance, 282 Q&A - phonetic search, 270 Q&A v. similar, 252, 255 Q&A, differences, 281 Radio button groups, 276 Ranges, 256 Refining the result set, 271 Regex() and qanda(), 292 Regular expressions, 288 Remove Duplicates from Results, 221 Remove from Current Results, 274 Renaming a saved retrieve spec, 287 Result set, 251 Retrieve spec, 251 Retrieve Spec, 248 return to retrieve spec, 253 Saving a search, 284 Saving Searches for re-use, 284 Search Commands, 262 Search criteria essentials, 254 Search in Current Results, 272 search logic, 260 search mode, 261 Searching a single field, 252 Searching multiple fields, 253 Searching one record, 283 Simple Search and Sorting, 265

INDEX

573

Simple Searches, 263 Sorting records, 250, 293 Spec Manager, 284 Special Layout Elements, 252, 275 Special search characters, 255 Special search characters (advanced), 268

Templates, 250 unbound layout elements, 254 Universal search, 266 Upper or lower case, 252 Using a previously-saved retrieve, 285 View Current Results, 274 When and how to sort, 294 Wildcard characters, 258 Wildcard search examples, 259

Searching and Sorting, 247 Searching for Duplicate Records, 221 Searching Special Layout Elements, 275 Searching subforms, 368 Secret Input, 138 Securing Your Applications, 433 Security, 433, See also Security Manager Administrator, 435 attributes, 433 Changing passwords, 450 Data Entry user, 435 Disabling temporarily, 167 Frequently-asked questions, 450 Login dialog, 446 Manager, 435 Mass updates, 312 password dialog, 445 preventing design changes, 446 Q&A compatibility, 433 Remove All Application Security, 443 Remove Security For Element, 442 Remove Security For Layout, 442 Server administration, 447 Summary, 449 User levels, 434 User Management, 447 X Password, 443 XLookups, 443

Security and Sesame Web Server, 471 Security Manager, 437 Delete a user, 441 Element level access, 441 Element-level permissions, 442 Groups, 438 Users, 439

Security, replacing when reconciling, 173 Select All (Edit menu), 35 Select All Elements on a tab page, 182 Selecting all layout elements on a tab page, 181

Selecting Position of Tab Labels, 184 Selection Layers, 128 Selection layers, moving up/down, 98 separator, exporting, 347 Server, 486 Server administration, 447, 489 Server Administration Standalone administrative client, 498

Server Administration (File menu), 34 Server Administration, starting, 477, 480 Server Console, 488 Server Status Window, 488 Server, stopping, 482, 491 Sesame application, defined, 63 Sesame Designer. See Designer Sesame Designer, starting, 30, 61 Sesame Initialization File, 541 Sesame server, 487 Sesame, Opening, 25 Sesame, Starting, 25, 30, 61 Sesame.ini file, 541 Setting formats for a layout element, 120 Setting up client-server, 485 Shift-F10, 51 Shift-F11, 52 Shift-F5, 52 Shift-F6, 53 Shift-F7, 52 Shortcut Keys, 539 Shut down Sesame Server, 482 Simple Searches, 263 Sizing. See Resizing Snap To Grid, 97 Sort (Results commands menu), 54 Sort by Timestamp (Results commands menu), 54

Sorting, 293 Default sort spec, 296 Dynamic sort, 294 Saving sort specs, 296 Spec window, 293 Using the spec window, 47 When and how to sort, 294

Sorting records, 293 Sounds-like Search, 269 Spaces in Layout Element names, 79

INDEX

574

Spec action bar, 46, 48, 293 Spec Manager, 284, 307 Spec selector buttons, 46, 293 Spec window, 46 Spec Window, defined, 38 Spec window, described, 293 Spec window, using, 47 Special search characters (advanced), 268 "Speedy fields", 127 splash screen, 556 Standalone administrative client, 498 Standard ASCII, 339, 348 Start macro recording, 35 Starting Sesame, 25 Starting Sesame Designer, 30, 61 Startup Form, 156 Startup Switches, 555 Static Layout Elements, defined, 77 Static picture element, defined, 84 Static picture, adding, 90 Static Scroll region, adding, 91 Static text element Adding by typing on the form, 77 Adding with layout element adder, 85 Defined, 77, 84 Deleting, 78 Editing, 78

Status line, 37 Stop macro recording, 35 Stop This Server, 491 Subform element, defined, 84 Subform Settings dialog, 190 Subform, adding, 91 Subform, form view, 361 Subform, table view, 362 Subform, types of, 361 Subforms, 361 Adding and editing data, 364 Adding new subrecords, 365 Create a new Database with Shared Template, 192

Creating a subform, 187 Creating using relational linking, 195 Data source, 186 Deleting a parent record, 366 Deleting subrecords, 366 Exporting data, 372 Form view subform, 186 Hierarchical import, 373 import ASCII file, 375 Importing data, 373

Make Natural Child Records, 191 Mass Delete, 366 Mass Update, 367 Moving between main form & subforms, 363

Natural link, 186 Orphan records, 366 Printing forms, 368 Relational link, 186 Re-parenting, 366 Searching, 368 Searching for main records with no subrecords, 371

Select records to display, 191 Select Subrecord type, 191 Settings dialog, 190 Show Existing Natural Child Records, 191 Subform properties, 192 Subrecord, 186 Table view subform, 186 Terminology, 186

Subforms, creating, 200 Subforms, importing data into, 198 Subforms, Using, 361 Subrecord, 185, 186 Subreport, 394 Summary totals and breaks, in reports, 421 SUnlock, 537 SVersion, 537 Switch to Add Data Mode, 51 Switch to Alternate Form, 54, 155 System Settings, 119, 120

T Tab groups Label position, 184 Sizing, 183

Tab Groups, 175 Adding, 91, 176 Adding tab pages, 179 Changing order of tab pages, 181 Deleting tab pages, 182 Label, 177 Moving, 184 Naming, 177

Tab key (form navigation), 239 "Tab Order". See Navigation Order Tab Pages, 175 Aligning layout elements, 181 Changing color of a tab page, 182

INDEX

575

Changing labels, 180 Changing order, 181 Deleting, 182 Moving within group, 181 Renaming, 180 Select All layout elements, 181 Selecting all elements on a page, 182

Tab Pages, Adding layout elements to, 177 tab separator, 348 Tabbed Pages, 175 Adding, 91 Defined, 175 Described, 175

Tabbed Pages, defined, 84 Table view Editing data in, 233 Navigating, 244

Table View Charts from, 235 Customizing, 234 Functions from, 235 Saving layout of, 235 Sorting, 235

Table View (Other Commands menu), 53 Table View, printing, 325 Templates and searching, 250 Templates, data entry, 144 Temporarily Disable Security, 167, 449 Text box Adding a multi-line text box element by typing on the form, 80

Adding by typing on the form, 79 Text box element, defined, 84 Text Box, defined, 78 Text editor element, adding, 88 Text Editor element, defined, 85 Text field, entries permitted, 95 ThrowFocus navigation programming, 152 @Time (not valid as initial value), 126 Time (current), inserting, 53 Time elements, adding, 81 Time field, entries permitted, 95 Time formatting, layout element, 121 Toggle Attachment, 53 Toolbar, 33 Toolbar, described, 36 Tooltip, 26, 32 Tooltips, custom, 149 Translate Q&A (File menu), 34 Translating Q&A databases, 30, 34 Translation Guide, Q&A (documentation), 22

Trim Application, 429 Troubleshooting, 477 Tutorials, 24

U Unbound layout elements, 66 Undo, 101, 231, 232 Undo (Edit menu), 34 Undo Current Field, 52 Undo Current Form, 52 Undo Last Change, 101 Undo multiple actions (advanced), 153 Unhide menu tree, 43 Uninstalling Sesame, 32 Unique fields, 138, 143 Universal search, 266 Unload application, 493 Unlocking an application, 480, 492 UPPER or lower case when searching, 252 Use as Example, 99 User Guide, Sesame, 22 User levels (Security), 434 User Management, 447, 497 @UserID (not valid as initial value), 126 Users, security, 439 Utility Programs, 537

V View options, 39

W warnings, 556 Ways of working with Sesame, 49 Web Capabilities, 451 Web Server, 451 Adding a new record, 466 Dynamic web page, 458 Email retrieval, 472 Posting a new record to the database, 468

Posting updates to the database, 464 Start Create menu page, 453 Start Searching a database, 454 Start Sesame web server, 452 Updating data, 460 Web server security, 471

Web Server Security, 471 Width, changing, for a form, 104 Width, changing, for Layout Elements, 103

INDEX

576

Width, setting, for export file columns, 350 Wildcard characters, in searches, 258 Window Management, 56 Windows Clipboard, 225 Windows, sizing, 39 Wittgenstein. See Philosophy Word (mailmerge with), 331, 333 WordMerge, 334 WordPerfect, 331, 333

X XML Database, 34, 70, 359 XML Export can take a long time, 359 XML Utilities, 359 XML, Export Application to XML, 430 XML, export design to, 167

Y Yes/No elements, adding, 81 Yes/No formatting, layout element, 121

READER'S NOTES

577

_____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________

READER'S NOTES

578

_____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________

READER'S NOTES

579

_____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ _____________________________________________________________________________ ____________________________________________________________________________

Sesame 2 User Guide

Documents

Transcript of Sesame 2 User Guide